Vigilae Connect

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

Špecifikácia je verejná, plochy sú neutrálne, 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

Neutrálne plochy, už z konštrukcie.

API vystavuje to, čo môže integrátor konzumovať bez dotyku s tajomstvom spisov: monitorovací denník a počítadlá. Obsah spisu obozretnosti, doklady ani hlásenia neobvyklých obchodných operácií týmto API neprechádzajú — nejde o obmedzenie cenového plánu, ale o architektúru.

Monitorovací denník

Udalosti pKYC kancelárie — doklad po platnosti, zmena konečného užívateľa výhod, opätovné preverenie na posúdenie — v neutrálnej podobe: sekvencia, typ, závažnosť, dátum. Odpovede vždy ohraničené na 500 udalostí.

Agregáty portfólia

Počítadlá, nikdy spis: objemy podľa stavu, omeškania, úplnosť. Dosť na vykreslenie prehľadu vo vašom nástroji bez toho, aby doň vstúpil čo i len jeden klientsky údaj.

Kvalifikácia

Jediný zápis: kvalifikácia udalosti denníka (stav qualifie alebo clos, dispozícia planifie, traite alebo ecarte). Vyžaduje zapisovací rozsah — najmenšie oprávnenie je pravidlo, nie možnosť.

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í. lecture (čítanie, predvolené) a ecriture (zápis). 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.
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.

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.