Vigilae Connect

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

Specifikacija je javna, 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

Celoten postopek in dve izključitvi, ki se ne bosta spremenili.

Vaša programska oprema lahko vodi zadevo od začetka do konca: ustvari stranko, odpre zadevo, naloži listine, sproži pregledovanje, navede dejanske lastnike, prebere oceno tveganja in prevzame dokazni spis. Dvoje po tej poti ne bo šlo nikoli, in ne gre za omejitev naročnine: nobena prijava suma in nobena dobesedna izjava vaše stranke. Prvo je dejanje, ki ga zakon pridržuje osebi, ki prijavlja; drugo v integracijskem kanalu nima kaj iskati.

Zadeva od začetka do konca

Stranke, zadeve, dokazila, pregledovanje, dejanski lastniki, ocena tveganja, dokazni spis, preverjanje integritete. Vsak vir ima svoj obseg: vaš ključ odpre le tisto, kar ste mu dali.

Dnevnik in zbirni podatki

Dogodki pKYC pisarne — listina s pretečeno veljavnostjo, sprememba dejanskega lastnika, ponovno pregledovanje za obdelavo — in števci portfelja za vašo nadzorno ploščo. Odgovor je vedno omejen, kazalec stabilen.

Vsak vpis ima ime

Naložiti, pregledati, opredeliti: vsak vpis zahteva svoj obseg in zabeleži upravljavca. Anonimna opredelitev je zavrnjena — integracija zabeleži človeško odločitev, sama pa je ne sprejme.

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. Ključ nosi le obsege, označene ob njegovem ustvarjanju: splošna lecture (branje, privzeto) in ecriture (pisanje) ali drobne, vir za virom — clients:, dossiers:, pieces:, criblage: (v lecture ali ecriture), origine-fonds:lecture, journal:lecture.
Dedovanje sledi priponi in poteka le v eno smer: lecture pokriva vsak *:lecture, ecriture vsak *:ecriture; droben obseg ne odpre ničesar zunaj sebe.
Šest obsegov izpade iz tega para in se zato ne deduje iz nobenega splošnega ključa: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Vsak se dodeli posebej, ob ustvarjanju ključa.
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.
Ključ lahko preneha veljati tudi pred tem datumom, kadar API ni več del naročnine pisarne. Ustavitev tedaj nastopi najmanj 30 dni po prvem e-poštnem sporočilu pisarni, na datum, ki ga navede drugo sporočilo, poslano najmanj 7 dni vnaprej. Ko je ta datum določen, je viden v konzoli pisarne (polje coupure_le v GET /connect/cles), vsak odgovor na sprejet klic pa ga napoveduje v glavi Sunset, dokler ne nastopi. Po tem datumu klic prejme 401, opisan v #authentification, z "motif": "fin_option_api"; če se API vrne v naročnino, ključ znova velja, do izteka lastne veljavnosti.
Preklican ključ se z API-jem ne vrne. Ko pa je celotna naročnina začasno ustavljena ali se konča, ključi takoj prenehajo veljati, brez tega roka.
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.

Vgrajeni gradniki

Stanje spremljanja — na vaših zaslonih.

Vaša programska oprema že ustvarja zadeve prek API-ja; gradniki ji dajo površino, ki je manjkala: prikaz stanja spremljanja zadeve v vaši kartici stranke, ne da bi znova zgradili vmesnik za skladnost. Potek ima tri korake — vaš strežnik izda kratkotrajen žeton, vrnjeni URL se namesti v iframe, gradnik se prikaže. Prikazovanje je vse, kar počne: nobena odločitev, nobena opredelitev, nobeno pisanje nikoli ne gre skozi gradnik. Klik odpre aplikacijo Vigilae, kjer ukrepa identificiran človek.

1. Izdajte žeton — na strežniku, nikoli na strani

Ključ vgk_ nikoli ne pride do brskalnika. Vaš strežnik pokliče izdajo žetona z namenskim obsegom embed:emettre (obkljukanim ob ustvarjanju ključa, nikoli podedovanim), do strani pa pride le kratek žeton: privzeto petnajst minut, omejeno na 5-60, vezan na eno zadevo, eno komponento, en naveden izvor. Potuje v fragmentu URL-ja — ne doseže ne naših dnevnikov ne vaših.

# Žeton za Compliance Button, napis izbran iz kataloga
curl -s -X POST https://vigilae.org/api/v1/embed/jetons \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"dossier_id":"D123","composant":"bouton",
       "audience":"https://your-software.example","libelle":"controler_client"}'

# 201 -> { "jeton": "…", "expire_le": "…",
#          "url": "https://vigilae.org/embarque/bouton?c=…#…" }

2. Namestite iframe — zaganjalnik, v desetih vrsticah

Zaganjalnik vigilae-embed.js ustvari peskovniški iframe, izvede rokovanje in sledi velikosti gradnika (omejena — iframe nikoli ne narekuje svoje višine vaši strani). Pri CSP vaša stran odpre le eno direktivo: frame-src https://vigilae.org. Ni potreben vgrajen skript, ni odvisnosti. Ročno napisan iframe deluje prav tako dobro.

<script src="https://vigilae.org/embarque/vigilae-embed.js" defer></script>
<div id="vigilance"></div>

// V vašem skriptu: URL prihaja iz VAŠEGA strežnika, ki je poklical izdajo žetona
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // ob poteku: ponovna izdaja žetona na strežniku
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) potisne svež žeton; widget.demonter() odstrani vse.

3. Compliance Button: vaš napis, naše stanje

Napis gumba se izbere iz zaprtega kataloga — nikoli prosto besedilo na površini, ki govori o spremljanju. Lupina jih prikaže v francoščini ali angleščini (parameter ?lang=), še ne v vašem jeziku; spodnji seznam pojasni pomen vsakega:

controler_client — »Preveri to stranko« (privzeto)
lancer_vigilance — »Začni skrbni pregled«
verifier_be — »Preveri dejanske lastnike«
preparer_dossier — »Pripravi zadevo PPDFT«

Pika stanja pa prikazuje stanje, ki ga izračuna Vigilae: a_jour (zelena — pregledovanje in ocena sta ažurna), a_revoir (jantarna — pregledovanje ali ocena zastarela, ali je vir ob zadnjem zagonu odpovedal), alerte (rdeča — vsaj eno opozorilo za presojo), inconnu (siva — zadeva nikoli pregledana). Napis se konfigurira, semantika nikoli: barva je vezana na stanje znotraj same lupine, ki prezre vsak poskus preglasitve prek postMessage. Zadeva v opozorilu prikazuje opozorilo, ne glede na oblikovanje.

Pogodba postMessage, v celoti

Gradnik sproži dogodke vigilae:pret, vigilae:taille (samodejno prilagajanje velikosti), vigilae:expire (ponovna izdaja žetona na strežniku, nato pošiljanje vigilae:jeton) in vigilae:ouvrir. Nikoli ime, tveganje ali opozorilo znotraj sporočila: vaša programska oprema ima že vse prek API-ja od strežnika do strežnika; ta kanal ne bo postal še en tak.

Navedba izvorov: administrator vaše pisarne. Žeton za vgrajeni gradnik je vezan na naveden izvor vaše pisarne — prav ta poganja CSP direktivo frame-ancestors v lupini. Administrator ga navede neposredno v Vigilae, na zaslonu »Integracije in varnost«: največ deset izvorov https://, izrecno naveden gostitelj, brez nadomestnih znakov; komponente, ki jih vklopi; in množičen preklic, ki z enim dejanjem prekliče vse že izdane žetone. http://localhost je dovoljen le pri poskusni pisarni — pišite na contact@vigilae.org (zadeva »Embedded widgets«), da vam jo odprejo za čas vaše integracije. Brez navedenega izvora: izdaja zavrne z 400. Instanca, katere shramba izvorov ni povezana: izrecen 501 — glejte #embed-indisponible.

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.