Vigilae Connect

API, който можете да прочетете, преди да подпишете.

Спецификацията е публична, повърхностите са неутрални, подписът на webhook-а може да бъде проверен в десет реда от ваша страна. Тази страница документира това, което API-ят излага днес — нищо повече, и това е съзнателно: което не е доставено, не е документирано.

OpenAPI спецификация, четима без ключ и без акаунт
Никога уведомление за съмнителна операция, никога дословно клиентско съдържание
Подписани webhooks, проверими извън Vigilae

Прочетете спецификацията Справочник на грешките

Сервира се от самия API: договорът, който четете, е този, който работи.

Периметърът

Неутрални повърхности, по конструкция.

API-ят излага това, което един интегратор може да консумира, без да докосва тайната на преписките: журнала за наблюдение и броячите. Съдържанието на преписка по надлежния контрол, документите, уведомленията за съмнителни операции не преминават през този API — не ограничение на плана, а архитектурата.

Журнал за наблюдение

pKYC събитията на кантората — изтекъл документ, промяна на действителен собственик, повторна проверка за преглед — в неутрална форма: последователност, тип, тежест, дата. Отговорите винаги са ограничени до 500 събития.

Агрегати на портфейла

Броячи, никога преписка: обеми по статус, забавяния, пълнота. Достатъчно, за да изградите табло във вашия инструмент, без в него да влезе каквато и да е клиентска информация.

Квалифициране

Единственият запис: квалифициране на събитие от журнала (статус qualifie или clos, диспозиция planifie, traite или ecarte). Изисква обхвата за запис — минималните привилегии са правилото, а не опция.

API-ят е замислен сървър към сървър: ключ в код, доставен до браузъра, е публикуван ключ. Нека ключа държи прокси от страната на сървъра, никога страницата.

Ключове

Ключове с ограничен обхват, показвани веднъж, отменими незабавно.

Формат. Всеки ключ започва с vgk_ и се изпраща като Authorization: Bearer vgk_…. Тайната се показва само при създаването: ние пазим единствено нейния SHA-256 отпечатък.
Обхвати. lecture (четене, по подразбиране) и ecriture (запис). Ключ без изисквания обхват получава 403 — вж. #scopes.
Изтичане. Една година след създаването (видимо в конзолата на кантората). Изтекъл ключ получава изричен 401 — вж. #cle-expiree.
Дебит. 60 заявки/минута на ключ (променимо за всеки ключ). Отговорът 429 носи Retry-After и заглавките X-RateLimit-Limit / -Remaining / -Reset.
Отмяна. Незабавна, от конзолата. Разпознаването е по отпечатък: ключовете не могат да бъдат изброявани.

Бърз старт

Три curl заявки и сте видели всичко.

# Здраве + удостоверяване на ключа
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Журнал за наблюдение, от началото, на страници по 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Квалифициране на събитие 42 (обхват за запис)
curl -s -X POST https://vigilae.org/api/v1/evenements/42/qualifier \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"statut":"qualifie","disposition":"traite"}'

Странициране, в едно правило

Подайте depuisSeq (0 при първата заявка) и limite (ограничено до 500): отговорът е сортиран по възходящ seq и връща prochainSeq, който подавате обратно без промяна при следващата заявка. Страница, по-къса от limite, означава край на журнала — тогава prochainSeq остава стабилен и служи като курсор за периодично допитване. Без depuisSeq получавате изгледа „най-новите първи“, ограничен до 500.

Портфейлът се заявява на /api/v1/portefeuille/agregats — броячи, един отговор, без странициране.

Webhooks

Подписани, с времеви печат, доставяни поне веднъж.

Вместо да допитвате журнала, получавайте го: Vigilae доставя събитията на вашия URL, по ред, на партиди от най-много 100. Доставката е at-least-once — курсорът напредва само при ваш 2xx, партида по партида — а идемпотентността е по seq: обработвайте всяка последователност точно веднъж (#idempotence).

Проверка на подписа

Всяка доставка носи заглавката x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Изчислете отново v1 от суровото получено тяло и отхвърляйте всеки времеви печат t отвъд 5 мин: това е защитата срещу повторение. По време на ротация на тайната заглавката носи по един v1 за всяка все още валидна тайна (24 ч припокриване): приемете, ако който и да е от тях съвпада.

// Node — проверка на подписа (без зависимости)
import { createHmac, timingSafeEqual } from 'node:crypto';

export function signatureValid(header, rawBody, secrets, toleranceMs = 5 * 60 * 1000) {
  const t = Number((/(?:^|,)t=(\d+)/.exec(header) || [])[1]);
  if (!t || Math.abs(Date.now() - t * 1000) > toleranceMs) return false; // защита срещу повторение
  const received = [...header.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  return [].concat(secrets).some((secret) => {
    const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
    return received.some((r) => r.length === expected.length
      && timingSafeEqual(Buffer.from(r), Buffer.from(expected)));
  });
}

# Python — същата проверка
import hmac, hashlib, re, time

def signature_valid(header: str, raw_body: bytes, secrets, tolerance_s: int = 300) -> bool:
    m = re.search(r"(?:^|,)t=(\d+)", header)
    if not m or abs(time.time() - int(m.group(1))) > tolerance_s:
        return False  # защита срещу повторение
    received = re.findall(r"v1=([0-9a-f]{64})", header)
    for secret in secrets:
        expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body,
                            hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, r) for r in received):
            return True
    return False

Преходно: старият формат sha256=HMAC(body) все още се излъчва в x-vigilae-signature-legacy за вече работещите приемници; премахването му е планирано с webhooks v2. Новите приемници проверяват схемата с времеви печат по-горе, а не старата.

Ротацията се задейства от конзолата (POST /connect/webhook/rotation от страна на приложението): в продължение на 24 ч старата тайна продължава да подписва — време да разположите новата от ваша страна без прозорец на отказ.

Тестова среда

Sandbox: при поискване.

Все още няма самообслужваща се sandbox среда — предпочитаме да ви го кажем тук, вместо да го откриете сами. Пишете на contact@vigilae.org (тема „API достъп“): отваряме пробна кантора с фиктивни данни за времето на вашата интеграция и оставаме на разположение, докато тя напредва.

Всеки клас API грешки има стабилен адрес в справочника на грешките: #authentification, #scopes, #cloisonnement, #debit, #signature… Отговорите за грешка на API-я ще сочат към тези котви.

API-ят не излага нито уведомления за съмнителни операции, нито дословно клиентско съдържание, по конструкция (art. L.561-18 от френския CMF). Никакво решение по надлежния контрол не се взема от API-я: той излага и квалифицира събития; професионалистът решава.