Vigilae Connect

API, ktoré si prečítate skôr, než podpíšete.

Špecifikácia je verejná, podpis webhoku si na svojej strane overíte v desiatich riadkoch. Táto stránka dokumentuje to, čo API vystavuje dnes — nič viac, a je to zámer: čo nie je nasadené, nie je zdokumentované.

Špecifikácia OpenAPI čitateľná bez kľúča aj bez účtu
Nikdy žiadne hlásenie neobvyklej obchodnej operácie, nikdy doslovný klientsky obsah
Podpísané webhooky, overiteľné mimo Vigilae

Prečítať špecifikáciu Referencia chýb

Servíruje ju samotné API: kontrakt, ktorý čítate, je ten, ktorý beží.

Rozsah

Celá cesta spisu a dve vylúčenia, na ktorých sa nič nezmení.

Váš softvér môže viesť spis od začiatku do konca: vytvoriť klienta, otvoriť spis, nahrať doklady, spustiť preverovanie, deklarovať konečných užívateľov výhod, prečítať klasifikáciu rizika a prevziať dôkazný spis. Dve veci tadiaľ nikdy neprejdú, a nejde o obmedzenie predplatného: žiadne oznámenie o podozrivej transakcii a žiadny doslovný výrok vášho klienta. Prvé je úkon, ktorý zákon vyhradzuje osobe, ktorá oznámenie podáva; druhé nemá v integračnom kanáli čo hľadať.

Spis od začiatku do konca

Klienti, spisy, podporné dokumenty, preverovanie, koneční užívatelia výhod, klasifikácia rizika, dôkazný spis, overenie integrity. Každý zdroj má svoj rozsah: váš kľúč otvára len to, čo ste mu dali.

Denník a súhrnné ukazovatele

Udalosti pKYC kancelárie — doklad po platnosti, zmena konečného užívateľa výhod, opätovné preverovanie na spracovanie — a počítadlá portfólia pre vašu nástenku. Odpoveď je vždy ohraničená, kurzor stabilný.

Čo zapíšete, nesie meno

Nahrať, preveriť, posúdiť: každý zápis vyžaduje svoj rozsah a zaznamenáva operátora. Anonymné posúdenie sa odmieta — integrácia zaznamenáva ľudské rozhodnutie, sama nijaké nevytvára.

API je navrhnuté server-server: kľúč v kóde odoslanom do prehliadača je zverejnený kľúč. Kľúč nech drží serverová proxy, nikdy stránka.

Kľúče

Kľúče s vymedzenými oprávneniami, zobrazené raz, okamžite odvolateľné.

Formát. Každý kľúč sa začína vgk_ a posiela sa ako Authorization: Bearer vgk_…. Tajomstvo sa zobrazí len pri vytvorení: neuchovávame nič okrem jeho odtlačku SHA-256.
Rozsahy oprávnení. Kľúč nesie len tie rozsahy, ktoré boli zaškrtnuté pri jeho vytvorení: všeobecné lecture (čítanie, predvolené) a ecriture (zápis) alebo jemné, zdroj po zdroji — clients:, dossiers:, pieces:, criblage: (v lecture alebo ecriture), origine-fonds:lecture, journal:lecture.
Dedenie sa riadi príponou a ide len jedným smerom: lecture pokrýva každé *:lecture, ecriture každé *:ecriture; jemný rozsah neotvára nič nad rámec seba samého.
Šesť rozsahov z tejto dvojice vybočuje, a preto sa nededí zo žiadneho všeobecného kľúča: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Každý sa deleguje samostatne, pri vytvorení kľúča.
Kľúč bez požadovaného rozsahu dostane 403 — pozri #scopes.
Platnosť. Jeden rok od vytvorenia (viditeľná v konzole kancelárie). Expirovaný kľúč dostane explicitnú 401 — pozri #cle-expiree.
Kľúč môže prestať byť prijímaný aj pred týmto dátumom, keď API už nie je súčasťou predplatného kancelárie. Zastavenie potom nastane najmenej 30 dní po prvom e-maile kancelárii, k dátumu, ktorý uvedie druhý e-mail, odoslaný najmenej 7 dní vopred. Len čo je stanovený, tento dátum je viditeľný v konzole kancelárie (pole coupure_le v GET /connect/cles) a každá odpoveď na prijaté volanie ho oznamuje v hlavičke Sunset, kým nenastane. Po tomto dátume volanie dostane 401 opísaný v #authentification, s "motif": "fin_option_api"; ak sa API vráti do predplatného, kľúč je opäť prijímaný, až do konca jeho vlastnej platnosti.
Odvolaný kľúč sa s API nevráti. A keď je celé predplatné pozastavené alebo skončí, kľúče prestanú byť prijímané okamžite, bez tejto lehoty.
Limit. 60 požiadaviek/minútu na kľúč (dá sa upraviť pre jednotlivý kľúč). Odpoveď 429 nesie Retry-After a hlavičky X-RateLimit-Limit / -Remaining / -Reset.
Odvolanie. Okamžité, z konzoly. Rozlíšenie prebieha podľa odtlačku: kľúče sa nedajú enumerovať.

Rýchly štart

Tri volania curl a videli ste všetko.

# Stav + autentifikácia kľúčom
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Monitorovací denník, od začiatku, po stránkach po 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalifikácia udalosti 42 (zapisovací rozsah)
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"}'

Stránkovanie v jednom pravidle

Odovzdajte depuisSeq (pri prvom volaní 0) a limite (strop 500): odpoveď je zoradená vzostupne podľa seq a vracia prochainSeq, ktorý pri ďalšom volaní odovzdáte bezo zmeny. Stránka kratšia než limite znamená koniec denníka — prochainSeq vtedy zostáva stabilný a slúži ako kurzor na periodické dopytovanie. Bez depuisSeq dostanete pohľad „najnovšie najprv“, ohraničený na 500.

Portfólio sa dopytuje na /api/v1/portefeuille/agregats — počítadlá, jedna odpoveď, žiadne stránkovanie.

Webhooky

Podpísané, s časovou pečiatkou, doručené aspoň raz.

Namiesto dopytovania denníka ho prijímajte: Vigilae doručuje udalosti na vašu URL, v poradí, v dávkach najviac po 100. Doručovanie je at-least-once — kurzor sa posúva len po vašej 2xx, dávku po dávke — a idempotencia je podľa seq: každú sekvenciu spracujte práve raz (#idempotence).

Overenie podpisu

Každé doručenie nesie hlavičku x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Prepočítajte v1 zo surového prijatého tela a odmietnite každú časovú pečiatku t staršiu než 5 min: to je ochrana proti opakovanému prehratiu. Počas rotácie tajomstva nesie hlavička jedno v1 za každé ešte platné tajomstvo (prekrytie 24 h): prijmite, ak sa zhoduje ktorékoľvek z nich.

// Node — overenie podpisu (bez závislostí)
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; // anti-replay
  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 — rovnaké overenie
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  # anti-replay
    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

Prechodné obdobie: starý formát sha256=HMAC(body) sa pre už nasadené prijímače stále emituje v hlavičke x-vigilae-signature-legacy; jeho odstránenie je plánované s webhookmi v2. Nové prijímače overujú vyššie uvedenú schému s časovou pečiatkou, nie tú starú.

Rotácia sa spúšťa z konzoly (POST /connect/webhook/rotation na strane aplikácie): počas 24 h staré tajomstvo stále podpisuje — čas na nasadenie nového na vašej strane bez okna výpadku.

Vložené widgety

Stav dohľadu, vo vašich obrazovkách.

Váš softvér už vytvára spisy cez API; widgety mu dávajú plochu, ktorá chýbala: ukázať stav dohľadu nad spisom priamo v karte vášho klienta, bez toho, aby ste stavali vlastné rozhranie súladu. Postup má tri kroky — váš server vydá krátkodobý token, vrátená URL sa vloží do iframe, widget zobrazí. Nič iné nerobí: žiadne rozhodnutie, žiadna kvalifikácia, žiadny zápis cez widget nikdy neprejde. Klik otvorí aplikáciu Vigilae, kde koná identifikovaný človek.

1. Vydanie tokenu — na strane servera, nikdy v stránke

Kľúč vgk_ sa nikdy nedotkne prehliadača. Váš server zavolá vydanie tokenu s vyhradeným rozsahom embed:emettre (zaškrtnutým pri vytváraní kľúča, nikdy nededeným) a k stránke zostúpi len krátky token: pätnásť minút predvolene, ohraničený na 5 až 60, viazaný na jeden spis, jednu komponentu, jeden deklarovaný origin. Cestuje vo fragmente URL — nedosiahne ani naše, ani vaše logy.

# Token pre Compliance Button, text vybraný z katalógu
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. Umiestnenie iframe — spúšťač, v desiatich riadkoch

Spúšťač vigilae-embed.js vytvorí sandboxovaný iframe, vykoná handshake a sleduje veľkosť widgetu (ohraničenú — iframe nikdy nediktuje svoju výšku vašej stránke). Pokiaľ ide o CSP, vaša stránka otvára jedinú direktívu: frame-src https://vigilae.org. Nie je potrebný žiadny inline skript ani žiadna závislosť. Rovnako dobre funguje aj ručne napísaná iframe.

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

// Vo vašom skripte: url prichádza z VÁŠHO servera, ktorý zavolal vydanie tokenu
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // pri vypršaní: znovu vydať token na serveri
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) vloží nový token; widget.demonter() odstráni všetko.

3. Compliance Button: váš text, náš stav

Text tlačidla sa vyberá z uzavretého katalógu — nikdy voľný text na ploche, ktorá hovorí o dohľade. Shell ho zobrazuje len po francúzsky alebo po anglicky (parameter ?lang=), zatiaľ nie vo vašom jazyku; zoznam nižšie uvádza jeho význam:

controler_client — „Skontrolovať tohto klienta“ (predvolené)
lancer_vigilance — „Spustiť povinnú starostlivosť“
verifier_be — „Overiť konečných užívateľov výhod“
preparer_dossier — „Pripraviť spis AML/CFT“

Stavová bodka však vykresľuje stav vypočítaný Vigilae: a_jour (zelená — preverovanie a hodnotenie sú aktuálne), a_revoir (oranžová — preverovanie alebo hodnotenie sú neaktuálne, alebo zdroj zlyhal pri poslednom behu), alerte (červená — aspoň jedno upozornenie na posúdenie), inconnu (sivá — spis nikdy nepreverený). Text je konfigurovateľný, sémantika nikdy: farba je viazaná na stav priamo v shelli, ktorý ignoruje akýkoľvek pokus prepísať ju cez postMessage. Spis v stave upozornenia zobrazuje upozornenie, nech je štylizácia akákoľvek.

Kontrakt postMessage, v plnom rozsahu

Widget vysiela vigilae:pret, vigilae:taille (automatické prispôsobenie veľkosti), vigilae:expire (znova vydajte token na strane servera a pošlite vigilae:jeton) a vigilae:ouvrir. Nikdy meno, riziko či upozornenie v správe: váš softvér má všetko už cez server-server API a tento kanál sa druhým nestane.

Deklarácia originov: robí ju administrátor vašej kancelárie. Token widgetu je viazaný na deklarovaný origin vašej kancelárie — práve ten riadi CSP frame-ancestors shellu. Administrátor ho deklaruje priamo vo Vigilae, na obrazovke „Integrácie a bezpečnosť“: najviac desať originov https://, výslovne uvedený host, nikdy zástupný znak; komponenty, ktoré aktivuje; a hromadné odvolanie, ktoré jedným gestom zruší platnosť všetkých už vydaných tokenov. http://localhost je povolený len na skúšobnej kancelárii (sandbox) — napíšte na contact@vigilae.org (predmet „Embedded widgets“), aby vám ju otvorili na čas vašej integrácie. Bez deklarovaného originu: vydanie tokenu vráti chybu 400. Inštancia, ktorej úložisko originov nie je zapojené: explicitná 501 — pozri #embed-indisponible.

Testovacie prostredie

Sandbox: na požiadanie.

Samoobslužný sandbox zatiaľ neexistuje — radšej vám to povieme tu, než aby ste na to prišli sami. Napíšte na contact@vigilae.org (predmet „API access“): otvoríme skúšobnú kanceláriu s fiktívnymi údajmi na čas vašej integrácie a zostaneme na príjme, kým postupuje.

Každá trieda chýb API má stálu adresu v referencii chýb: #authentification, #scopes, #cloisonnement, #debit, #signature… Chybové odpovede API budú na tieto kotvy odkazovať.

API nevystavuje hlásenia neobvyklých obchodných operácií ani doslovný klientsky obsah, už z konštrukcie (čl. L.561-18 francúzskeho CMF). API neprijíma žiadne rozhodnutie o obozretnosti: vystavuje a kvalifikuje udalosti; rozhoduje profesionál.