Vigilae Connect

API, amelyet aláírás előtt elolvashat.

A specifikáció nyilvános, a felületek semlegesek, a webhook-aláírás tíz sorban ellenőrizhető az Ön oldalán. Ez az oldal azt dokumentálja, amit az API ma kitesz — semmi többet, és ez szándékos: amit nem szállítottunk le, azt nem dokumentáljuk.

Az OpenAPI-specifikáció kulcs és fiók nélkül is olvasható
Gyanús ügylet bejelentése soha, szó szerinti ügyféltartalom soha
Aláírt webhookok, a Vigilae-n kívül is ellenőrizhetők

Specifikáció elolvasása Hibareferencia

Maga az API szolgálja ki: a szerződés, amelyet olvas, ugyanaz, amely fut.

A hatókör

Semleges felületek, felépítésből adódóan.

Az API azt teszi ki, amit egy integrátor a dossziék titkosságának érintése nélkül fogyaszthat: a monitorozási naplót és a számlálókat. Az átvilágítási dosszié tartalma, a dokumentumok, a gyanús ügyletek bejelentései nem haladnak át ezen az API-n — ez nem csomagkorlát, hanem az architektúra.

Monitorozási napló

Az iroda pKYC-eseményei — lejárt dokumentum, tényleges tulajdonos változása, felülvizsgálandó újraszűrés — semleges formában: sorszám, típus, súlyosság, dátum. A válaszok mindig legfeljebb 500 eseményre korlátozottak.

Portfólió-aggregátumok

Számlálók, soha nem dosszié: volumenek státusz szerint, határidők, teljesség. Elég ahhoz, hogy műszerfalat jelenítsen meg a saját eszközében úgy, hogy egyetlen ügyféladat sem kerül bele.

Minősítés

Az egyetlen írási művelet: egy naplóesemény minősítése (státusz: qualifie vagy clos, elintézés: planifie, traite vagy ecarte). Írási hatókört igényel — a legkisebb jogosultság elve itt szabály, nem opció.

Az API szerver–szerver használatra készült: a böngészőbe kiszállított kódban lévő kulcs nyilvánosságra hozott kulcs. A kulcsot szerveroldali proxy tartsa, soha ne az oldal.

Kulcsok

Szabott hatókörű kulcsok, egyszer megjelenítve, azonnal visszavonhatók.

Formátum. Minden kulcs vgk_ előtaggal kezdődik, és Authorization: Bearer vgk_… formában küldendő. A titok csak létrehozáskor jelenik meg: semmit sem őrzünk meg belőle az SHA-256 lenyomatán kívül.
Hatókörök. lecture (olvasás, az alapértelmezés) és ecriture (írás). A szükséges hatókör nélküli kulcs 403-at kap — lásd #scopes.
Lejárat. A létrehozás után egy évvel (látható az iroda konzoljában). A lejárt kulcs kifejezett 401-et kap — lásd #cle-expiree.
Sebességkorlát. Kulcsonként 60 kérés/perc (kulcsonként felülírható). A 429 Retry-After-t és X-RateLimit-Limit / -Remaining / -Reset fejléceket hordoz.
Visszavonás. Azonnali, a konzolból. A feloldás lenyomat alapján történik: a kulcsok nem sorolhatók fel.

Gyorsindítás

Három curl-hívás, és mindent látott.

# Állapot + kulcs-hitelesítés
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Monitorozási napló, az elejétől, 100-as lapokban
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# A 42-es esemény minősítése (írási hatókör)
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"}'

Lapozás, egyetlen szabályban

Adja át a depuisSeq (első híváskor 0) és a limite (legfeljebb 500) paramétert: a válasz növekvő seq szerint rendezett, és visszaadja a prochainSeq értéket, amelyet a következő hívásban változatlanul kell visszaadni. A limite-nél rövidebb lap a napló végét jelenti — a prochainSeq ekkor stabil marad, és lekérdezési kurzorként szolgál. depuisSeq nélkül a „legfrissebb elöl” nézetet kapja, 500-ra korlátozva.

A portfólió a /api/v1/portefeuille/agregats végponton kérdezhető le — számlálók, egyetlen válasz, lapozás nélkül.

Webhookok

Aláírva, időbélyegezve, legalább egyszer kézbesítve.

A napló lekérdezgetése helyett fogadja azt: a Vigilae az eseményeket az Ön URL-jére kézbesíti, sorrendben, legfeljebb 100-as kötegekben. A kézbesítés at-least-once — a kurzor csak az Ön 2xx-ére lép tovább, kötegenként —, az idempotencia pedig a seq-en áll: minden sorszámot pontosan egyszer dolgozzon fel (#idempotence).

Az aláírás ellenőrzése

Minden kézbesítés az x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body) fejlécet hordozza. Számolja újra a v1-et a kapott nyers törzsből, és utasítson el minden 5 percnél régebbi t időbélyeget: ez a visszajátszás elleni védelem. Titokrotáció alatt a fejléc minden még érvényes titokhoz egy-egy v1-et hordoz (24 óra átfedés): fogadja el, ha bármelyik egyezik.

// Node — aláírás-ellenőrzés (függőség nélkül)
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; // visszajátszás elleni védelem
  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 — ugyanaz az ellenőrzés
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  # visszajátszás elleni védelem
    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

Átmenet: a régi sha256=HMAC(body) formátumot a már működő fogadók kedvéért továbbra is kibocsátjuk az x-vigilae-signature-legacy fejlécen; eltávolítása a webhookok v2-jével tervezett. Az új fogadók a fenti, időbélyeges sémát ellenőrizzék, ne a régit.

A rotáció a konzolból indítható (alkalmazásoldalon POST /connect/webhook/rotation): 24 órán át a régi titok is aláír még — idő arra, hogy hibaablak nélkül élesítse az újat a saját oldalán.

Tesztkörnyezet

Sandbox: kérésre.

Önkiszolgáló sandbox egyelőre nincs — inkább itt mondjuk el, mint hogy Ön fedezze fel. Írjon a contact@vigilae.org címre („API-hozzáférés” tárggyal): az integráció idejére fiktív adatokkal feltöltött próbairodát nyitunk, és elérhetők maradunk, amíg a munka halad.

Minden API-hibaosztálynak stabil címe van a hibareferencián: #authentification, #scopes, #cloisonnement, #debit, #signature… Az API hibaválaszai ezekre a horgonyokra fognak mutatni.

Az API felépítéséből adódóan sem gyanús ügyletek bejelentéseit, sem szó szerinti ügyféltartalmat nem tesz ki (a francia CMF art. L.561-18). Átvilágítási döntést az API nem hoz: eseményeket tesz ki és minősít; a szakember dönt.