Vigilae Connect

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

A specifikáció nyilvános, 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

A teljes ügymenet, és két kizárás, amely nem fog megváltozni.

Az Ön szoftvere végig tudja vinni az aktát az elejétől a végéig: ügyfelet hoz létre, aktát nyit, dokumentumokat tölt fel, szűrést indít, bejelenti a tényleges tulajdonosokat, kiolvassa a besorolást és lehívja a bizonyítékdossziét. Két dolog soha nem megy át ezen az úton, és ez nem előfizetési korlát: semmilyen gyanúbejelentés, és az ügyfele egyetlen szó szerinti kijelentése sem. Az első olyan cselekmény, amelyet a törvény a bejelentést tevő személynek tart fenn; a másodiknak pedig semmi keresnivalója egy integrációs csatornában.

Az akta, az elejétől a végéig

Ügyfelek, akták, igazoló dokumentumok, szűrés, tényleges tulajdonosok, kockázati besorolás, bizonyítékdosszié, sértetlenség-ellenőrzés. Minden erőforrásnak megvan a maga hatóköre: a kulcsa csak azt nyitja meg, amit Ön ráruházott.

Napló és összesítők

Az iroda pKYC-eseményei — lejárt dokumentum, tényleges tulajdonos változása, elvégzendő újraszűrés — és portfóliószintű számlálók az Ön irányítópultjához. A válasz mindig korlátozott terjedelmű, a kurzor stabil.

Amit beír, ahhoz név tartozik

Feltöltés, szűrés, minősítés: minden írási művelet megköveteli a saját hatókörét, és rögzíti, ki végezte. A névtelen minősítést a rendszer elutasítja — az integráció emberi döntést rögzít, maga egyetlen döntést sem hoz.

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. A kulcs csak a létrehozásakor bejelölt hatóköröket hordozza: az általános lecture (olvasás, az alapértelmezés) és ecriture (írás) hatókört, vagy finom, erőforrásonkénti hatóköröket — clients:, dossiers:, pieces:, criblage: (lecture vagy ecriture változatban), origine-fonds:lecture, journal:lecture.
Az öröklés az utótagot követi, és csak egy irányba működik: a lecture lefedi az összes *:lecture, az ecriture az összes *:ecriture hatókört; egy finom hatókör önmagán túl semmit sem nyit meg.
Hat hatókör kilóg ebből a párból, ezért egyetlen általános kulcsból sem öröklődik: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Mindegyiket külön kell átruházni, a kulcs létrehozásakor.
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.
Egy kulcs elfogadása ennél a dátumnál korábban is megszűnhet, ha az API már nem része az iroda előfizetésének. A leállítás ilyenkor legalább 30 nappal az irodának küldött első e-mail után következik be, azon a napon, amelyet egy legalább 7 nappal előre elküldött második e-mail közöl. Amint ez a dátum rögzül, látható az iroda konzoljában (a GET /connect/cles coupure_le mezője), és minden elfogadott hívásra adott válasz jelzi a Sunset fejlécben, amíg el nem érkezik. Ezt követően a hívás az #authentification pontban leírt 401-et kapja, a "motif": "fin_option_api" mezővel; ha az API visszakerül az előfizetésbe, a kulcsot a rendszer ismét elfogadja, saját lejáratáig.
A visszavont kulcs nem tér vissza az API-val. Ha pedig a teljes előfizetést felfüggesztik, vagy az véget ér, a kulcsok elfogadása azonnal megszűnik, e határidő nélkül.
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.

Beágyazott widgetek

Felügyeleti állapot, az Ön képernyőin.

Az Ön szoftvere már létrehozza a dossziékat az API-n keresztül; a widgetek megadják a hiányzó felületet: egy dosszié felügyeleti állapotának megjelenítését az ügyféllapon belül, anélkül hogy megfelelési felületet kellene újraépítenie. A folyamat három lépésből áll — az Ön szervere rövid élettartamú tokent bocsát ki, a kapott URL egy iframe-be kerül, a widget megjelenít. Kizárólag megjelenít: soha nem hoz döntést, nem minősít, és soha nem ír semmit egy widgeten keresztül. A kattintás megnyitja a Vigilae alkalmazást, ahol egy azonosított ember cselekszik.

1. A token kibocsátása — szerveroldalon, sosem az oldalon

A vgk_ kulcs sosem éri el a böngészőt. Az Ön szervere a dedikált embed:emettre hatókörrel hívja meg a kibocsátó végpontot (a kulcs létrehozásakor jelölendő be, sosem öröklődik), és csak a rövid token jut le az oldalra: alapértelmezésben tizenöt perc, 5–60 közé korlátozva, egy dossziéhoz, egy összetevőhöz és egy deklarált eredethez kötve. Az URL töredékében utazik — sem a mi naplóinkat, sem az Önökét nem éri el.

# Egy token a Compliance Button számára, katalógusból választott címkével
curl -s -X POST https://vigilae.org/api/v1/embed/jetons \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"dossier_id":"D123","composant":"bouton",
       "audience":"https://your-software.example","libelle":"controler_client"}'

# 201 -> { "jeton": "…", "expire_le": "…",
#          "url": "https://vigilae.org/embarque/bouton?c=…#…" }

2. Az iframe elhelyezése — az indítószkript, tíz sorban

A vigilae-embed.js indítószkript létrehozza a sandboxolt iframe-et, elvégzi a kézfogást, és követi a widget méretét (korlátozva — az iframe sosem diktálja a magasságát az Ön oldalának). CSP szempontjából az Ön oldala egyetlen direktívát nyit meg: frame-src https://vigilae.org. Nincs szükség inline szkriptre, sem függőségre. Egy kézzel írt iframe ugyanúgy működik.

<script src="https://vigilae.org/embarque/vigilae-embed.js" defer></script>
<div id="vigilance"></div>

// Az Ön szkriptjében: az url a SAJÁT szerveréről érkezik, amely meghívta a kibocsátó végpontot
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // lejáratkor: új token kibocsátása szerveroldalon
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) friss tokent küld; widget.demonter() mindent eltávolít.

3. A Compliance Button: az Ön címkéje, a mi állapotunk

A gomb címkéje egy zárt katalógusból választható ki — sosem szabad szöveg egy olyan felületen, amely felügyeletről beszél — a beágyazott shell ezeket franciául vagy angolul jeleníti meg (?lang= paraméter), az Ön nyelvén egyelőre nem; az alábbi lista a jelentésüket adja meg:

controler_client — „Az ügyfél ellenőrzése” (alapértelmezett)
lancer_vigilance — „Átvilágítás indítása”
verifier_be — „Tényleges tulajdonosok ellenőrzése”
preparer_dossier — „Az AML-dosszié előkészítése”

Az állapotjelző pont azonban egy, a Vigilae által számított állapotot jelenít meg: a_jour (zöld — a szűrés és a kockázati besorolás naprakész), a_revoir (borostyán — a szűrés vagy a kockázati besorolás elavult, vagy a forrás hibázott az utolsó lefutáskor), alerte (piros — legalább egy minősítendő riasztás), inconnu (szürke — a dossziét sosem szűrték). A címke konfigurálható, a szemantika sosem: a szín magához az állapothoz van kötve a shellen belül, amely figyelmen kívül hagy minden postMessage-en keresztüli felülírási kísérletet. A riasztás alatt álló dosszié riasztást mutat, bármilyen is a megjelenés.

A postMessage-szerződés, teljes egészében

A widget a következőket bocsátja ki: vigilae:pret, vigilae:taille (automatikus méretezés), vigilae:expire (szerveroldali újrakibocsátás, majd a vigilae:jeton elküldése) és vigilae:ouvrir. Soha egy nevet, egy kockázatot vagy egy riasztást egy üzeneten belül: az Ön szoftvere már mindent megkap a szerver–szerver API-n keresztül, és ez a csatorna nem válik egy második ilyenné.

Eredetek deklarálása: az Ön irodájának adminisztrátora által. Egy embed token az Ön irodájának egy deklarált eredetéhez van kötve — ez vezérli a shell frame-ancestors CSP-jét. Az adminisztrátor közvetlenül a Vigilae-ban deklarálja, az „Integrációk és biztonság” képernyőn: legfeljebb tíz https:// eredet, kifejtett gazdanév, sosem helyettesítő karakter; az általa bekapcsolt összetevők; és egy tömeges visszavonás, amely egyetlen gesztussal érvényteleníti az összes már kibocsátott tokent. http://localhost csak egy próbairodán engedélyezett — írjon a contact@vigilae.org címre („Beágyazott widgetek” tárggyal), hogy nyissunk egyet az integrációja idejére. Nincs deklarált eredet: a kibocsátó végpont 400-zal utasítja el. Egy olyan példány, amelynek eredettárolása nincs bekötve: kifejezett 501 — lásd #embed-indisponible.

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.