Vigilae Connect

Un'API che puoi leggere prima di firmare.

La specifica è pubblica, le superfici sono neutre, la firma dei webhook si verifica in dieci righe dal tuo lato. Questa pagina documenta ciò che l'API espone oggi — niente di più, ed è una scelta: ciò che non è in produzione non è documentato.

Specifica OpenAPI leggibile senza chiave né account
Mai una segnalazione di operazione sospetta, mai il contenuto testuale dei clienti
Webhook firmati, verificabili fuori da Vigilae

Leggi la specifica Riferimento degli errori

Servita dall'API stessa: il contratto che leggi è quello in esecuzione.

Il perimetro

Superfici neutre, per costruzione.

L'API espone ciò che un integratore può consumare senza toccare il segreto delle pratiche: il registro di monitoraggio e i contatori. Il contenuto di una pratica di vigilanza, i documenti, le segnalazioni di operazione sospetta non transitano da questa API — non è un limite di piano, è l'architettura.

Registro di monitoraggio

Gli eventi pKYC dello studio — documento scaduto, cambio di titolare effettivo, ri-screening da esaminare — in forma neutra: sequenza, tipo, severità, data. Risposte sempre limitate a 500 eventi.

Aggregati di portafoglio

Contatori, mai una pratica: volumi per stato, ritardi, completezza. Quanto basta per disegnare una dashboard nel tuo strumento senza che vi entri un solo dato cliente.

Qualificazione

L'unica scrittura: qualificare un evento del registro (stato qualifie o clos, disposizione planifie, traite o ecarte). Richiede lo scope di scrittura — il privilegio minimo è la regola, non un'opzione.

L'API è pensata server-to-server: una chiave nel codice consegnato al browser è una chiave pubblicata. Fai custodire la chiave a un proxy lato server, mai alla pagina.

Chiavi

Chiavi con scope, mostrate una sola volta, revocabili all'istante.

Formato. Ogni chiave inizia con vgk_ e si invia come Authorization: Bearer vgk_…. Il segreto è mostrato solo alla creazione: non ne conserviamo che l'impronta SHA-256.
Scope. lecture (lettura, predefinito) e ecriture (scrittura). Una chiave senza lo scope richiesto riceve un 403 — vedi #scopes.
Scadenza. Un anno dalla creazione (visibile nella console dello studio). Una chiave scaduta riceve un 401 esplicito — vedi #cle-expiree.
Frequenza. 60 richieste/minuto per chiave (modificabile per singola chiave). Un 429 porta Retry-After e le intestazioni X-RateLimit-Limit / -Remaining / -Reset.
Revoca. Immediata, dalla console. La risoluzione avviene per impronta: le chiavi non si possono enumerare.

Quickstart

Tre chiamate curl e hai visto tutto.

# Stato di salute + autenticazione della chiave
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Registro di monitoraggio, dall'inizio, a pagine da 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Qualificare l'evento 42 (scope di scrittura)
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"}'

La paginazione, in una regola

Passa depuisSeq (0 alla prima chiamata) e limite (con tetto a 500): la risposta è ordinata per seq crescente e restituisce prochainSeq, da ripassare tale e quale alla chiamata successiva. Una pagina più corta di limite significa fine del registro — prochainSeq resta allora stabile e funge da cursore di polling. Senza depuisSeq, ottieni la vista "più recenti prima", limitata a 500.

Il portafoglio si interroga su /api/v1/portefeuille/agregats — contatori, una risposta, nessuna paginazione.

Webhook

Firmati, con marca temporale, consegnati almeno una volta.

Invece di interrogare il registro, ricevilo: Vigilae consegna gli eventi al tuo URL, in ordine, a lotti di al massimo 100. La consegna è at-least-once — il cursore avanza solo al tuo 2xx, lotto per lotto — e l'idempotenza passa dal seq: elabora ogni sequenza esattamente una volta (#idempotence).

Verificare la firma

Ogni consegna porta l'intestazione x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Ricalcola v1 dal corpo grezzo ricevuto e rifiuta ogni marca temporale t oltre i 5 min: è l'anti-replay. Durante una rotazione del segreto l'intestazione porta un v1 per ogni segreto ancora valido (sovrapposizione di 24 h): accetta se almeno uno corrisponde.

// Node — verifica della firma (nessuna dipendenza)
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 — stessa verifica
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

Transitorio: il vecchio formato sha256=HMAC(body) è ancora emesso su x-vigilae-signature-legacy per i ricevitori già in essere; la sua rimozione è prevista con i webhook v2. I nuovi ricevitori verificano lo schema con marca temporale qui sopra, non il vecchio.

La rotazione si attiva dalla console (POST /connect/webhook/rotation lato applicazione): per 24 h il vecchio segreto continua a firmare — il tempo di distribuire il nuovo dal tuo lato senza finestra di guasto.

Ambiente di test

Sandbox: su richiesta.

Non esiste ancora una sandbox self-service — preferiamo dirtelo qui piuttosto che lasciartelo scoprire. Scrivi a contact@vigilae.org (oggetto "API access"): apriamo uno studio di prova con dati fittizi per la durata della tua integrazione, e restiamo raggiungibili mentre procede.

Ogni classe di errore dell'API ha un indirizzo stabile nel riferimento degli errori: #authentification, #scopes, #cloisonnement, #debit, #signature… Le risposte di errore dell'API punteranno a queste ancore.

L'API non espone né segnalazioni di operazione sospetta né contenuti testuali dei clienti, per costruzione (art. L.561-18 del CMF francese). Nessuna decisione di vigilanza è presa dall'API: espone e qualifica eventi; il professionista decide.