Vigilae Connect

Et API, De kan læse, før De skriver under.

Specifikationen er offentlig, fladerne er neutrale, webhook-signaturen kan verificeres på ti linjer hos Dem. Denne side dokumenterer, hvad API'et eksponerer i dag — intet mere, og det er med vilje: hvad der ikke er leveret, er ikke dokumenteret.

OpenAPI-specifikation, der kan læses uden nøgle eller konto
Aldrig en underretning om mistænkelig transaktion, aldrig ordret kundeindhold
Signerede webhooks, der kan verificeres uden for Vigilae

Læs specifikationen Fejlreference

Serveret af API'et selv: den kontrakt, De læser, er den, der kører.

Omfanget

Neutrale flader, i selve konstruktionen.

API'et eksponerer det, en integrator kan konsumere uden at røre sagernes fortrolighed: overvågningsjournalen og tællere. Indholdet af en vigilanssag, bilagene, underretningerne om mistænkelige transaktioner passerer ikke gennem dette API — ikke en planbegrænsning, men arkitekturen.

Overvågningsjournal

Kontorets pKYC-hændelser — udløbet dokument, ændring af reel ejer, re-screening til gennemgang — i neutral form: sekvens, type, alvorlighed, dato. Svar altid begrænset til 500 hændelser.

Porteføljeaggregater

Tællere, aldrig en sag: volumener pr. status, frister, fuldstændighed. Nok til at tegne et dashboard i Deres værktøj, uden at en eneste kundeoplysning kommer ind i det.

Kvalificering

Den eneste skrivning: at kvalificere en journalhændelse (status qualifie eller clos, disposition planifie, traite eller ecarte). Det kræver skrive-scopet — mindste privilegium er reglen, ikke en valgmulighed.

API'et er designet server-til-server: en nøgle i kode, der sendes til browseren, er en offentliggjort nøgle. Lad en server-side proxy holde nøglen, aldrig siden.

Nøgler

Nøgler med scopes, vist én gang, kan tilbagekaldes øjeblikkeligt.

Format. Hver nøgle begynder med vgk_ og sendes som Authorization: Bearer vgk_…. Hemmeligheden vises kun ved oprettelsen: vi opbevarer intet andet end dens SHA-256-digest.
Scopes. lecture (læsning, standard) og ecriture (skrivning). En nøgle uden det krævede scope modtager en 403 — se #scopes.
Udløb. Ét år efter oprettelsen (synligt i kontorets konsol). En udløbet nøgle modtager en eksplicit 401 — se #cle-expiree.
Rategrænse. 60 forespørgsler/minut pr. nøgle (kan tilpasses pr. nøgle). En 429 bærer Retry-After og headerne X-RateLimit-Limit / -Remaining / -Reset.
Tilbagekaldelse. Øjeblikkelig, fra konsollen. Opslag sker via digest: nøgler kan ikke opregnes.

Quickstart

Tre curl-kald, og De har set det hele.

# Sundhedstjek + nøgleautentificering
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Overvågningsjournal, fra begyndelsen, i sider af 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificer hændelse 42 (skrive-scope)
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, i én regel

Send depuisSeq (0 ved første kald) og limite (loft på 500): svaret er sorteret efter stigende seq og returnerer prochainSeq, som sendes tilbage uændret ved næste kald. En side kortere end limite betyder journalens slutning — prochainSeq forbliver da stabil og fungerer som polling-cursor. Uden depuisSeq får De visningen "nyeste først", begrænset til 500.

Porteføljen forespørges på /api/v1/portefeuille/agregats — tællere, ét svar, ingen paginering.

Webhooks

Signerede, tidsstemplede, leveret mindst én gang.

I stedet for at polle journalen: modtag den. Vigilae leverer hændelser til Deres URL, i rækkefølge, i batches på højst 100. Leveringen er at-least-once — cursoren rykker kun frem ved Deres 2xx, batch for batch — og idempotens sker pr. seq: behandl hver sekvens præcis én gang (#idempotence).

Verificering af signaturen

Hver levering bærer headeren x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Genberegn v1 ud fra den rå body, De har modtaget, og afvis ethvert tidsstempel t ud over 5 min.: det er anti-replay-værnet. Under en rotation af hemmeligheden bærer headeren én v1 pr. stadig gyldig hemmelighed (24 timers overlap): acceptér, hvis blot én af dem matcher.

// Node — signaturverificering (ingen afhængigheder)
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 — samme verificering
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

Overgangsordning: det gamle format sha256=HMAC(body) udsendes stadig på x-vigilae-signature-legacy til allerede etablerede modtagere; fjernelsen er planlagt sammen med webhooks v2. Nye modtagere verificerer det tidsstemplede skema ovenfor, ikke det gamle.

Rotationen udløses fra konsollen (POST /connect/webhook/rotation på applikationssiden): i 24 timer signerer den gamle hemmelighed stadig — tid til at udrulle den nye hos Dem uden et fejlvindue.

Testmiljø

Sandbox: på forespørgsel.

Der findes endnu ingen selvbetjenings-sandbox — vi vil hellere sige det her end lade Dem opdage det. Skriv til contact@vigilae.org (emne "API-adgang"): vi opretter et prøvekontor med fiktive data, så længe Deres integration varer, og vi er til at få fat på, mens den skrider frem.

Hver fejlklasse i API'et har en stabil adresse i fejlreferencen: #authentification, #scopes, #cloisonnement, #debit, #signature… API'ets fejlsvar vil pege på disse ankre.

API'et eksponerer hverken underretninger om mistænkelige transaktioner eller ordret kundeindhold, i selve konstruktionen (art. L.561-18 i den franske CMF). Ingen vigilansbeslutning træffes af API'et: det eksponerer og kvalificerer hændelser; fagpersonen beslutter.