Vigilae Connect

Een API die u kunt lezen vóór u tekent.

De specificatie is publiek, de oppervlakken zijn neutraal, de webhookhandtekening is in tien regels aan uw kant te verifiëren. Deze pagina documenteert wat de API vandaag blootlegt — niets meer, en dat is bewust: wat niet is uitgeleverd, wordt niet gedocumenteerd.

OpenAPI-specificatie leesbaar zonder sleutel of account
Nooit een melding van een ongebruikelijke transactie, nooit letterlijke cliëntinhoud
Ondertekende webhooks, verifieerbaar buiten Vigilae

De specificatie lezen Foutenreferentie

Geserveerd door de API zelf: het contract dat u leest, is het contract dat draait.

De perimeter

Neutrale oppervlakken, door hun opzet.

De API legt bloot wat een integrator kan afnemen zonder aan het geheim van de dossiers te raken: het monitoringjournaal en tellers. De inhoud van een waakzaamheidsdossier, de documenten, de meldingen van ongebruikelijke transacties passeren niet via deze API — geen beperking van het abonnement, maar de architectuur.

Monitoringjournaal

De pKYC-gebeurtenissen van het kantoor — verlopen document, wijziging van uiteindelijk begunstigde (UBO), te beoordelen herscreening — in neutrale vorm: sequentie, type, ernst, datum. Antwoorden altijd begrensd tot 500 gebeurtenissen.

Portefeuilleaggregaten

Tellers, nooit een dossier: volumes per status, doorlooptijden, volledigheid. Genoeg om in uw tool een dashboard te tonen zonder dat er één cliëntgegeven in binnenkomt.

Kwalificatie

De enige schrijfactie: een journaalgebeurtenis kwalificeren (status qualifie of clos, dispositie planifie, traite of ecarte). Dit vereist de schrijfscope — least privilege is de regel, geen optie.

De API is ontworpen voor server-naar-server: een sleutel in code die naar de browser gaat, is een gepubliceerde sleutel. Laat een proxy aan serverzijde de sleutel bewaren, nooit de pagina.

Sleutels

Sleutels met scopes, één keer getoond, onmiddellijk intrekbaar.

Formaat. Elke sleutel begint met vgk_ en wordt verstuurd als Authorization: Bearer vgk_…. Het geheim wordt alleen bij de aanmaak getoond: wij bewaren niets anders dan de SHA-256-digest ervan.
Scopes. lecture (lezen, de standaard) en ecriture (schrijven). Een sleutel zonder de vereiste scope krijgt een 403 — zie #scopes.
Vervaldatum. Eén jaar na de aanmaak (zichtbaar in de console van het kantoor). Een verlopen sleutel krijgt een expliciete 401 — zie #cle-expiree.
Limiet. 60 verzoeken/minuut per sleutel (per sleutel aanpasbaar). Een 429 draagt Retry-After en de headers X-RateLimit-Limit / -Remaining / -Reset.
Intrekking. Onmiddellijk, vanuit de console. De resolutie verloopt via de digest: sleutels kunnen niet worden opgesomd.

Quickstart

Drie curl-aanroepen en u hebt alles gezien.

# Health + authenticatie met sleutel
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Monitoringjournaal, vanaf het begin, in pagina's van 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Gebeurtenis 42 kwalificeren (schrijfscope)
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"}'

Paginering, in één regel

Geef depuisSeq mee (0 bij de eerste aanroep) en limite (begrensd op 500): het antwoord is gesorteerd op oplopende seq en geeft prochainSeq terug, om bij de volgende aanroep ongewijzigd terug te sturen. Een pagina korter dan limite betekent het einde van het journaal — prochainSeq blijft dan stabiel en dient als pollingcursor. Zonder depuisSeq krijgt u de weergave "meest recent eerst", begrensd tot 500.

De portefeuille wordt bevraagd op /api/v1/portefeuille/agregats — tellers, één antwoord, geen paginering.

Webhooks

Ondertekend, tijdgestempeld, minstens één keer bezorgd.

Ontvang het journaal in plaats van het te pollen: Vigilae bezorgt gebeurtenissen op uw URL, in volgorde, in batches van hoogstens 100. De bezorging is at-least-once — de cursor schuift alleen op bij uw 2xx, batch per batch — en idempotentie loopt via seq: verwerk elke sequentie precies één keer (#idempotence).

De handtekening verifiëren

Elke bezorging draagt de header x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Herbereken v1 op basis van de ruwe body zoals ontvangen, en verwerp elke tijdstempel t voorbij 5 min: dat is de anti-replay. Tijdens een rotatie van het geheim draagt de header één v1 per nog geldig geheim (24 u overlap): aanvaard zodra er één overeenstemt.

// Node — verificatie van de handtekening (zonder dependency)
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 — dezelfde verificatie
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

Overgangsregeling: het oude formaat sha256=HMAC(body) wordt nog uitgezonden op x-vigilae-signature-legacy voor reeds bestaande ontvangers; de verwijdering ervan is gepland met webhooks v2. Nieuwe ontvangers verifiëren het tijdgestempelde schema hierboven, niet het oude.

De rotatie wordt gestart vanuit de console (POST /connect/webhook/rotation aan de applicatiekant): gedurende 24 u ondertekent het oude geheim nog — tijd om aan uw kant het nieuwe uit te rollen zonder venster van uitval.

Testomgeving

Sandbox: op aanvraag.

Er is nog geen selfservice-sandbox — wij zeggen het u liever hier dan het u te laten ontdekken. Schrijf naar contact@vigilae.org (onderwerp "API-toegang"): wij openen een proefkantoor met fictieve gegevens voor de duur van uw integratie, en we blijven bereikbaar terwijl die vordert.

Elke foutklasse van de API heeft een stabiel adres in de foutenreferentie: #authentification, #scopes, #cloisonnement, #debit, #signature… De foutantwoorden van de API zullen naar deze ankers verwijzen.

De API legt geen meldingen van ongebruikelijke transacties en geen letterlijke cliëntinhoud bloot, door haar opzet (art. L.561-18 van het Franse CMF). Geen enkele waakzaamheidsbeslissing wordt door de API genomen: zij legt gebeurtenissen bloot en kwalificeert ze; de professional beslist.