Vigilae Connect

Ett API du kan läsa innan du skriver under.

Specifikationen är publik, ytorna är neutrala, webhooksignaturen kan verifieras på tio rader på din sida. Den här sidan dokumenterar vad API:t exponerar i dag — inget mer, och det är avsiktligt: det som inte är levererat är inte dokumenterat.

OpenAPI-specifikation som kan läsas utan nyckel och utan konto
Aldrig en rapport om misstänkt transaktion, aldrig ordagrant kundinnehåll
Signerade webhookar, verifierbara utanför Vigilae

Läs specifikationen Felreferensen

Serveras av API:t självt: kontraktet du läser är det som körs.

Omfattningen

Neutrala ytor, genom själva konstruktionen.

API:t exponerar det en integratör kan konsumera utan att röra ärendenas sekretess: övervakningsjournalen och räknare. Innehållet i ett vaksamhetsärende, handlingarna, rapporterna om misstänkta transaktioner passerar inte genom detta API — inte en planbegränsning, utan arkitekturen.

Övervakningsjournal

Byråns pKYC-händelser — utgången handling, byte av verklig huvudman, omscreening att granska — i neutral form: sekvens, typ, allvarlighetsgrad, datum. Svaren är alltid begränsade till 500 händelser.

Portföljaggregat

Räknare, aldrig ett ärende: volymer per status, ledtider, fullständighet. Tillräckligt för att rendera en instrumentpanel i ditt verktyg utan att en enda kunduppgift kommer in i det.

Kvalificering

Den enda skrivoperationen: att kvalificera en journalhändelse (status qualifie eller clos, disposition planifie, traite eller ecarte). Den kräver skrivscopet — minsta möjliga behörighet är regeln, inte ett tillval.

API:t är utformat för server-till-server: en nyckel i kod som skickas till webbläsaren är en publicerad nyckel. Låt en proxy på serversidan hålla nyckeln, aldrig sidan.

Nycklar

Nycklar med avgränsat scope, visade en gång, omedelbart återkallbara.

Format. Varje nyckel börjar med vgk_ och skickas som Authorization: Bearer vgk_…. Hemligheten visas bara när nyckeln skapas: vi behåller inget annat än dess SHA-256-hash.
Scope. lecture (läsning, standard) och ecriture (skrivning). En nyckel utan det scope som krävs får 403 — se #scopes.
Utgång. Ett år efter skapandet (syns i byråns konsol). En utgången nyckel får en uttrycklig 401 — se #cle-expiree.
Anropstakt. 60 anrop/minut per nyckel (kan justeras per nyckel). En 429 bär Retry-After och huvudena X-RateLimit-Limit / -Remaining / -Reset.
Återkallelse. Omedelbar, från konsolen. Uppslagningen sker via hash: nycklar kan inte räknas upp.

Snabbstart

Tre curl-anrop och du har sett allt.

# Hälsa + nyckelautentisering
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Övervakningsjournalen, från början, i sidor om 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificera händelse 42 (skrivscope)
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 en regel

Skicka depuisSeq (0 vid första anropet) och limite (högst 500): svaret sorteras efter stigande seq och returnerar prochainSeq, som skickas tillbaka oförändrad vid nästa anrop. En sida kortare än limite betyder journalens slut — prochainSeq förblir då stabil och fungerar som pollningsmarkör. Utan depuisSeq får du vyn ”senaste först”, begränsad till 500.

Portföljen frågas på /api/v1/portefeuille/agregats — räknare, ett svar, ingen paginering.

Webhookar

Signerade, tidsstämplade, levererade minst en gång.

I stället för att polla journalen kan du ta emot den: Vigilae levererar händelser till din URL, i ordning, i omgångar om högst 100. Leveransen är at-least-once — markören flyttas bara fram vid din 2xx, omgång för omgång — och idempotensen bygger på seq: behandla varje sekvens exakt en gång (#idempotence).

Verifiera signaturen

Varje leverans bär huvudet x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Räkna om v1 från den råa kropp som togs emot, och avvisa varje tidsstämpel t äldre än 5 min: det är anti-replay-skyddet. Under en hemlighetsrotation bär huvudet ett v1 per ännu giltig hemlighet (24 h överlappning): acceptera om någon av dem stämmer.

// Node — signaturverifiering (utan beroenden)
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 — samma verifiering
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

Övergångsvis: det gamla formatet sha256=HMAC(body) sänds fortfarande på x-vigilae-signature-legacy för mottagare som redan är på plats; borttagningen planeras till webhooks v2. Nya mottagare verifierar det tidsstämplade schemat ovan, inte det gamla.

Rotationen utlöses från konsolen (POST /connect/webhook/rotation på applikationssidan): i 24 h signerar den gamla hemligheten fortfarande — tid att driftsätta den nya på din sida utan ett felfönster.

Testmiljö

Sandbox: på begäran.

Det finns ännu ingen självbetjäningssandbox — vi säger det hellre här än låter dig upptäcka det själv. Skriv till contact@vigilae.org (ämne ”API-åtkomst”): vi öppnar en testbyrå med fiktiva data under hela din integration, och vi förblir nåbara medan den fortskrider.

Varje felklass i API:t har en stabil adress i felreferensen: #authentification, #scopes, #cloisonnement, #debit, #signature… API:ts felsvar kommer att peka på dessa ankare.

API:t exponerar varken rapporter om misstänkta transaktioner eller ordagrant kundinnehåll, genom själva konstruktionen (art. L.561-18 i den franska CMF). Inget vaksamhetsbeslut fattas av API:t: det exponerar och kvalificerar händelser; yrkesutövaren beslutar.