Vigilae Connect

API, které si přečtete dřív, než podepíšete.

Specifikace je veřejná, plochy jsou neutrální, podpis webhooku lze na vaší straně ověřit na deset řádků. Tato stránka dokumentuje, co API vystavuje dnes — nic víc, a je to záměr: co není dodáno, není zdokumentováno.

Specifikace OpenAPI čitelná bez klíče i bez účtu
Nikdy oznámení podezřelého obchodu, nikdy doslovný klientský obsah
Podepsané webhooky, ověřitelné mimo Vigilae

Přečíst specifikaci Referenční přehled chyb

Servíruje ji samo API: kontrakt, který čtete, je ten, který běží.

Rozsah

Neutrální plochy, už z konstrukce.

API vystavuje to, co integrátor může konzumovat, aniž by se dotkl tajemství spisů: deník sledování a čítače. Obsah spisu obezřetnosti, doklady ani oznámení podezřelého obchodu tímto API neprocházejí — není to omezení tarifu, je to architektura.

Deník sledování

Události pKYC kanceláře — prošlý doklad, změna skutečného majitele, opětovné prověření k posouzení — v neutrální podobě: sekvence, typ, závažnost, datum. Odpovědi vždy omezené na 500 událostí.

Agregáty portfolia

Čítače, nikdy spis: objemy podle stavu, prodlevy, úplnost. Dost na vykreslení dashboardu ve vašem nástroji, aniž by do něj vstoupil jediný klientský údaj.

Kvalifikace

Jediný zápis: kvalifikace události deníku (stav qualifie nebo clos, vyřízení planifie, traite nebo ecarte). Vyžaduje scope zápisu — zásada nejmenších oprávnění je pravidlem, ne volbou.

API je navrženo pro komunikaci server–server: klíč v kódu odeslaném do prohlížeče je zveřejněný klíč. Klíč ať drží proxy na straně serveru, nikdy stránka.

Klíče

Klíče s vymezenými scopes, zobrazené jednou, okamžitě odvolatelné.

Formát. Každý klíč začíná vgk_ a posílá se jako Authorization: Bearer vgk_…. Tajemství se zobrazuje pouze při vytvoření: neuchováváme nic než jeho otisk SHA-256.
Scopes. lecture (čtení, výchozí) a ecriture (zápis). Klíč bez požadovaného scopu dostane 403 — viz #scopes.
Platnost. Jeden rok od vytvoření (viditelné v konzoli kanceláře). Prošlý klíč dostane explicitní 401 — viz #cle-expiree.
Limit. 60 požadavků/minutu na klíč (lze upravit pro jednotlivý klíč). Odpověď 429 nese Retry-After a hlavičky X-RateLimit-Limit / -Remaining / -Reset.
Odvolání. Okamžité, z konzole. Vyhledání probíhá podle otisku: klíče nelze enumerovat.

Rychlý start

Tři volání curl a viděli jste všechno.

# Stav služby + ověření klíče
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Deník sledování, od začátku, po stránkách po 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalifikovat událost 42 (scope zápisu)
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"}'

Stránkování v jednom pravidle

Předejte depuisSeq (při prvním volání 0) a limite (strop 500): odpověď je seřazena vzestupně podle seq a vrací prochainSeq, který při dalším volání předáte beze změny. Stránka kratší než limite znamená konec deníku — prochainSeq pak zůstává stabilní a slouží jako kurzor pro polling. Bez depuisSeq dostanete pohled „nejnovější napřed“, omezený na 500.

Portfolio se dotazuje na /api/v1/portefeuille/agregats — čítače, jedna odpověď, žádné stránkování.

Webhooky

Podepsané, s časovým razítkem, doručené alespoň jednou.

Místo dotazování na deník jej přijímejte: Vigilae doručuje události na vaši URL, v pořadí, v dávkách po nejvýše 100. Doručení je at-least-once — kurzor se posouvá jen po vašem 2xx, dávku po dávce — a idempotence se řídí seq: každou sekvenci zpracujte právě jednou (#idempotence).

Ověření podpisu

Každé doručení nese hlavičku x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Přepočítejte v1 ze surového přijatého těla a odmítněte každé časové razítko t starší než 5 minut: to je ochrana proti replay útoku. Během rotace tajemství nese hlavička jedno v1 za každé dosud platné tajemství (překryv 24 hodin): přijměte, pokud kterékoli z nich odpovídá.

// Node — ověření podpisu (bez závislostí)
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; // ochrana proti 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 — stejné ověření
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  # ochrana proti 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

Přechodné: starý formát sha256=HMAC(body) se stále emituje v hlavičce x-vigilae-signature-legacy pro už zavedené příjemce; jeho odstranění je plánováno s webhooky v2. Noví příjemci ověřují výše uvedené schéma s časovým razítkem, ne to staré.

Rotace se spouští z konzole (POST /connect/webhook/rotation na straně aplikace): po 24 hodin staré tajemství stále podepisuje — čas na nasazení nového na vaší straně bez okna výpadku.

Testovací prostředí

Sandbox: na vyžádání.

Samoobslužný sandbox zatím neexistuje — raději vám to řekneme tady, než abyste na to přišli sami. Napište na contact@vigilae.org (předmět „API access“): otevřeme zkušební kancelář s fiktivními daty na dobu vaší integrace a zůstáváme na příjmu, dokud postupuje.

Každá třída chyb API má stabilní adresu v referenčním přehledu chyb: #authentification, #scopes, #cloisonnement, #debit, #signature… Chybové odpovědi API budou na tyto kotvy odkazovat.

API nevystavuje oznámení podezřelého obchodu ani doslovný klientský obsah, už z konstrukce (čl. L.561-18 francouzského CMF). Žádné rozhodnutí v rámci obezřetnosti nečiní API: vystavuje a kvalifikuje události; rozhoduje profesionál.