Vigilae Connect

API, ki ga lahko preberete, preden podpišete.

Specifikacija je javna, površine so nevtralne, podpis webhooka lahko na svoji strani preverite v desetih vrsticah. Ta stran dokumentira, kar API izpostavlja danes — nič več, in to namerno: kar ni dostavljeno, ni dokumentirano.

Specifikacija OpenAPI, berljiva brez ključa ali računa
Nikoli prijava suma, nikoli dobesedna vsebina stranke
Podpisani webhooki, preverljivi zunaj Vigilae

Preberite specifikacijo Referenca napak

Streže jo API sam: pogodba, ki jo berete, je tista, ki teče.

Obseg

Nevtralne površine, po zasnovi.

API izpostavlja tisto, kar lahko integrator uporablja, ne da bi se dotaknil tajnosti zadev: dnevnik spremljanja in števce. Vsebina zadeve skrbnosti, listine in prijave suma ne potujejo prek tega API-ja — to ni omejitev paketa, to je arhitektura.

Dnevnik spremljanja

Dogodki pKYC pisarne — potekla listina, sprememba dejanskega lastnika, ponovno pregledovanje za pregled — v nevtralni obliki: zaporedje, tip, resnost, datum. Odgovori so vedno omejeni na 500 dogodkov.

Agregati portfelja

Števci, nikoli zadeva: obsegi po statusu, zamude, popolnost. Dovolj, da v svojem orodju izrišete nadzorno ploščo, ne da bi vanjo vstopil en sam podatek o stranki.

Kvalifikacija

Edino pisanje: kvalificiranje dogodka iz dnevnika (status qualifie ali clos, razrešitev planifie, traite ali ecarte). Zahteva obseg za pisanje — najmanjši privilegij je pravilo, ne možnost.

API je zasnovan za komunikacijo strežnik–strežnik: ključ v kodi, poslani brskalniku, je objavljen ključ. Ključ naj hrani strežniški posrednik, nikoli stran.

Ključi

Ključi z omejenim obsegom, prikazani enkrat, takoj preklicljivi.

Format. Vsak ključ se začne z vgk_ in se pošlje kot Authorization: Bearer vgk_…. Skrivnost se prikaže le ob ustvarjanju: hranimo samo njen povzetek SHA-256.
Obsegi. lecture (branje, privzeto) in ecriture (pisanje). Ključ brez zahtevanega obsega prejme 403 — glejte #scopes.
Potek. Eno leto po ustvarjanju (vidno v konzoli pisarne). Potekli ključ prejme izrecen 401 — glejte #cle-expiree.
Omejitev. 60 zahtev/minuto na ključ (nastavljivo po ključu). Odgovor 429 nosi Retry-After in glave X-RateLimit-Limit / -Remaining / -Reset.
Preklic. Takojšen, iz konzole. Razrešitev poteka po povzetku: ključev ni mogoče naštevati.

Hitri začetek

Trije klici curl in videli ste vse.

# Stanje + avtentikacija ključa
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Dnevnik spremljanja, od začetka, po straneh po 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificiraj dogodek 42 (obseg za pisanje)
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"}'

Paginacija, v enem pravilu

Podajte depuisSeq (0 ob prvem klicu) in limite (omejeno na 500): odgovor je urejen po naraščajočem seq in vrne prochainSeq, ki ga ob naslednjem klicu podate nespremenjenega. Stran, krajša od limite, pomeni konec dnevnika — prochainSeq takrat ostane stabilen in služi kot kazalec za poizvedovanje. Brez depuisSeq dobite pogled »najnovejši najprej«, omejen na 500.

Portfelj se poizveduje na /api/v1/portefeuille/agregats — števci, en odgovor, brez paginacije.

Webhooki

Podpisani, časovno žigosani, dostavljeni vsaj enkrat.

Namesto da dnevnik poizvedujete, ga prejemajte: Vigilae dostavlja dogodke na vaš URL, po vrstnem redu, v paketih po največ 100. Dostava je at-least-once — kazalec napreduje šele ob vašem 2xx, paket za paketom — idempotentnost pa je po seq: vsako zaporedje obdelajte natanko enkrat (#idempotence).

Preverjanje podpisa

Vsaka dostava nosi glavo x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Znova izračunajte v1 iz surovega prejetega telesa in zavrnite vsak časovni žig t, ki odstopa za več kot 5 min: to je zaščita pred ponovnim predvajanjem. Med rotacijo skrivnosti glava nosi po en v1 za vsako še veljavno skrivnost (24 ur prekrivanja): sprejmite, če se ujema katera koli.

// Node — preverjanje podpisa (brez odvisnosti)
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; // zaščita pred ponovitvijo
  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 — enako preverjanje
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  # zaščita pred ponovitvijo
    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

Prehodno: stari format sha256=HMAC(body) se za že postavljene prejemnike še vedno oddaja v glavi x-vigilae-signature-legacy; njegova odstranitev je načrtovana z webhooki v2. Novi prejemniki preverjajo zgornjo časovno žigosano shemo, ne stare.

Rotacija se sproži iz konzole (POST /connect/webhook/rotation na strani aplikacije): 24 ur stara skrivnost še podpisuje — dovolj časa, da na svoji strani uvedete novo brez okna izpadov.

Testno okolje

Peskovnik: na zahtevo.

Samopostrežnega peskovnika še ni — raje vam to povemo tukaj, kot da bi to odkrili sami. Pišite na contact@vigilae.org (zadeva »API access«): za čas vaše integracije odpremo poskusno pisarno z izmišljenimi podatki in ostanemo dosegljivi, medtem ko napreduje.

Vsak razred napak API ima stalen naslov v referenci napak: #authentification, #scopes, #cloisonnement, #debit, #signature… Odgovori API z napako bodo kazali na ta sidra.

API po zasnovi ne izpostavlja niti prijav suma niti dobesedne vsebine strank (čl. L.561-18 francoskega CMF). API ne sprejema nobene odločitve o skrbnosti: dogodke izpostavlja in kvalificira; odloča strokovnjak.