Eine API, die Sie lesen können, bevor Sie unterschreiben.
Die Spezifikation ist öffentlich, die Oberflächen sind neutral, die Webhook-Signatur lässt sich in zehn Zeilen auf Ihrer Seite prüfen. Diese Seite dokumentiert, was die API heute bereitstellt — nicht mehr, und das ist Absicht: Was nicht ausgeliefert ist, wird nicht dokumentiert.
- OpenAPI-Spezifikation lesbar ohne Schlüssel und ohne Konto
- Niemals eine Verdachtsmeldung, niemals Kundenwortlaut
- Signierte Webhooks, prüfbar außerhalb von Vigilae
Von der API selbst ausgeliefert: Der Vertrag, den Sie lesen, ist der, der läuft.
Neutrale Oberflächen, konstruktionsbedingt.
Die API stellt bereit, was ein Integrator konsumieren kann, ohne das Geheimnis der Dossiers zu berühren: das Überwachungsjournal und Zähler. Der Inhalt eines Sorgfaltsdossiers, die Unterlagen, die Verdachtsmeldungen laufen nicht über diese API — keine Tarifgrenze, sondern die Architektur.
Überwachungsjournal
Die pKYC-Ereignisse der Kanzlei — abgelaufenes Dokument, Wechsel des wirtschaftlich Berechtigten, zu prüfendes Re-Screening — in neutraler Form: Sequenz, Typ, Schweregrad, Datum. Antworten stets auf 500 Ereignisse begrenzt.
Portfolio-Aggregate
Zähler, nie ein Dossier: Volumina nach Status, Fristen, Vollständigkeit. Genug, um in Ihrem Werkzeug ein Dashboard zu rendern, ohne dass ein einziges Kundendatum hineingelangt.
Qualifizierung
Der einzige Schreibzugriff: das Qualifizieren eines Journalereignisses (Status qualifie oder clos, Disposition planifie, traite oder ecarte). Er erfordert den Schreib-Scope — die geringste Berechtigung ist die Regel, keine Option.
Die API ist Server-zu-Server ausgelegt: Ein Schlüssel in Code, der an den Browser ausgeliefert wird, ist ein veröffentlichter Schlüssel. Lassen Sie einen serverseitigen Proxy den Schlüssel halten, nie die Seite.
Schlüssel mit Scopes, einmal angezeigt, sofort widerrufbar.
- Format. Jeder Schlüssel beginnt mit
vgk_und wird alsAuthorization: Bearer vgk_…gesendet. Das Geheimnis wird nur bei der Erstellung angezeigt: Wir bewahren nichts als seinen SHA-256-Digest auf. - Scopes.
lecture(Lesen, der Standard) undecriture(Schreiben). Ein Schlüssel ohne den erforderlichen Scope erhält einen 403 — siehe #scopes. - Ablauf. Ein Jahr nach der Erstellung (sichtbar in der Konsole der Kanzlei). Ein abgelaufener Schlüssel erhält einen expliziten 401 — siehe #cle-expiree.
- Rate. 60 Anfragen/Minute je Schlüssel (je Schlüssel anpassbar). Ein 429 trägt
Retry-Afterund die HeaderX-RateLimit-Limit / -Remaining / -Reset. - Widerruf. Sofort, aus der Konsole. Die Auflösung erfolgt über den Digest: Schlüssel lassen sich nicht enumerieren.
Drei curl-Aufrufe, und Sie haben alles gesehen.
# Health-Check + Schlüssel-Authentifizierung
curl -s https://vigilae.org/api/v1/sante \
-H "Authorization: Bearer vgk_your_key"
# Überwachungsjournal, von Anfang an, in Seiten zu 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
-H "Authorization: Bearer vgk_your_key"
# Ereignis 42 qualifizieren (Schreib-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"}'Paginierung, in einer Regel
Übergeben Sie depuisSeq (0 beim ersten Aufruf) und limite (gedeckelt bei 500): Die Antwort ist nach aufsteigender seq sortiert und liefert prochainSeq, das beim nächsten Aufruf unverändert zurückzugeben ist. Eine Seite kürzer als limite bedeutet das Ende des Journals — prochainSeq bleibt dann stabil und dient als Polling-Cursor. Ohne depuisSeq erhalten Sie die Ansicht „Neueste zuerst“, begrenzt auf 500.
Das Portfolio wird über /api/v1/portefeuille/agregats abgefragt — Zähler, eine Antwort, keine Paginierung.
Signiert, zeitgestempelt, mindestens einmal zugestellt.
Statt das Journal zu pollen, empfangen Sie es: Vigilae stellt Ereignisse an Ihre URL zu, in Reihenfolge, in Batches von höchstens 100. Die Zustellung ist at-least-once — der Cursor rückt nur auf Ihr 2xx vor, Batch für Batch — und die Idempotenz läuft über seq: Verarbeiten Sie jede Sequenz genau einmal (#idempotence).
Die Signatur prüfen
Jede Zustellung trägt den Header x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Berechnen Sie v1 aus dem rohen empfangenen Body neu und verwerfen Sie jeden Zeitstempel t jenseits von 5 min: Das ist der Anti-Replay. Während einer Secret-Rotation trägt der Header ein v1 je noch gültigem Secret (24 h Überlappung): Akzeptieren Sie, wenn eines davon passt.
// Node — Signaturprüfung (ohne Abhängigkeit)
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 — dieselbe Prüfung
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Übergangsweise: Das alte Format sha256=HMAC(body) wird für bereits bestehende Empfänger weiterhin auf x-vigilae-signature-legacy ausgegeben; seine Entfernung ist mit den Webhooks v2 geplant. Neue Empfänger prüfen das zeitgestempelte Schema oben, nicht das alte.
Die Rotation wird aus der Konsole ausgelöst (POST /connect/webhook/rotation auf Anwendungsseite): 24 h lang signiert das alte Secret weiter — Zeit, das neue auf Ihrer Seite auszurollen, ohne Ausfallfenster.
Sandbox: auf Anfrage.
Jede Fehlerklasse der API hat eine stabile Adresse in der Fehlerreferenz: #authentification, #scopes, #cloisonnement, #debit, #signature… Die Fehlerantworten der API werden auf diese Anker verweisen.
Die API stellt konstruktionsbedingt weder Verdachtsmeldungen noch Kundenwortlaut bereit (Art. L.561-18 CMF). Keine Sorgfaltsentscheidung wird von der API getroffen: Sie stellt Ereignisse bereit und qualifiziert sie; der Berufsträger entscheidet.