Vigilae Connect

API, kurią galite perskaityti prieš pasirašydami.

Specifikacija vieša, webhook parašą galite patikrinti dešimčia eilučių savo pusėje. Šiame puslapyje dokumentuota tai, ką API pateikia šiandien — nieko daugiau, ir tai sąmoninga: kas nepateikta, tas nedokumentuota.

OpenAPI specifikacija skaitoma be rakto ir be paskyros
Niekada jokio pranešimo apie įtartiną sandorį, niekada pažodinio klientų turinio
Pasirašyti webhook'ai, patikrinami už „Vigilae“ ribų

Skaityti specifikaciją Klaidų žinynas

Ją pateikia pati API: kontraktas, kurį skaitote, yra tas, kuris veikia.

Perimetras

Visas procesas ir dvi ribos, kurios nesikeis.

Jūsų programinė įranga gali nuvesti bylą nuo pradžios iki pabaigos: sukurti klientą, atverti bylą, įkelti dokumentus, paleisti patikrą, nurodyti tikruosius savininkus, perskaityti rizikos vertinimą ir atsiimti įrodymų bylą. Du dalykai per ją niekada nepereis, ir tai ne prenumeratos apribojimas: joks pranešimas apie įtartiną operaciją ir joks pažodinis jūsų kliento pasakymas. Pirmasis yra veiksmas, kurį įstatymas palieka pranešančiam asmeniui; antrajam ne vieta integracijos kanale.

Byla nuo pradžios iki pabaigos

Klientai, bylos, patvirtinamieji dokumentai, patikra, tikrieji savininkai, rizikos vertinimas, įrodymų byla, vientisumo patikra. Kiekvienas išteklius turi savo apimtį: jūsų raktas atveria tik tai, ką jam suteikėte.

Žurnalas ir suvestiniai rodikliai

Biuro pKYC įvykiai — pasibaigusio galiojimo dokumentas, tikrojo savininko pasikeitimas, neapdorota pakartotinė patikra — ir portfelio skaitikliai jūsų valdymo skydui. Atsakymas visada ribotas, žymeklis stabilus.

Kiekvienas įrašas turi vardą

Įkelti, atlikti patikrą, kvalifikuoti: kiekvienas įrašas reikalauja savo apimties ir užfiksuoja operatorių. Anoniminis kvalifikavimas atmetamas — integracija užregistruoja žmogaus sprendimą, bet pati jokio nepriima.

API sukurta veikti tarp serverių: raktas kode, kuris pasiekia naršyklę, yra paskelbtas raktas. Raktą laikykite serverio pusės tarpiniame sluoksnyje, niekada puslapyje.

Raktai

Apribotos aprėpties raktai, rodomi vieną kartą, atšaukiami akimirksniu.

Formatas. Kiekvienas raktas prasideda vgk_ ir siunčiamas kaip Authorization: Bearer vgk_…. Paslaptis parodoma tik kuriant: mes saugome tik jos SHA-256 maišos reikšmę.
Aprėptys. Raktas turi tik tas aprėptis, kurios buvo pažymėtos jį kuriant: bendrąsias lecture (skaitymas, numatytoji) ir ecriture (rašymas) arba smulkias, išteklius po ištekliaus — clients:, dossiers:, pieces:, criblage: (su lecture arba ecriture), origine-fonds:lecture, journal:lecture.
Paveldėjimas remiasi priesaga ir veikia tik viena kryptimi: lecture apima kiekvieną *:lecture, ecriture — kiekvieną *:ecriture; smulki aprėptis neatveria nieko, išskyrus save.
Šešios aprėptys iškrenta iš šios poros, todėl nepaveldimos iš jokio bendrojo rakto: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kiekviena deleguojama atskirai, kuriant raktą.
Raktas be reikiamos aprėpties gauna 403 — žr. #scopes.
Galiojimas. Metai nuo sukūrimo (matoma biuro konsolėje). Pasibaigusio galiojimo raktas gauna aiškų 401 — žr. #cle-expiree.
Raktas gali nustoti būti priimamas ir prieš šią datą, kai API nebėra biuro prenumeratos dalis. Tada jis išjungiamas ne anksčiau kaip po 30 dienų nuo pirmojo el. laiško biurui, tą dieną, kurią nurodo antrasis el. laiškas, išsiųstas ne vėliau kaip prieš 7 dienas. Kai tik ši data nustatoma, ji matoma biuro konsolėje (GET /connect/cles laukas coupure_le), o kiekvienas atsakymas į priimtą užklausą ją skelbia antraštėje Sunset, kol ji ateina. Po šios datos užklausa gauna 401, aprašytą skyriuje #authentification, su "motif": "fin_option_api"; jei API vėl įtraukiama į prenumeratą, raktas vėl priimamas, iki jo paties galiojimo pabaigos.
Atšauktas raktas kartu su API negrįžta. O kai visa prenumerata sustabdoma arba baigiasi, raktai iš karto nustoja būti priimami, be šio termino.
Sparta. 60 užklausų per minutę vienam raktui (galima keisti kiekvienam raktui atskirai). 429 atsakymas neša Retry-After ir antraštes X-RateLimit-Limit / -Remaining / -Reset.
Atšaukimas. Akimirksniu, iš konsolės. Raktai atpažįstami pagal maišos reikšmę: jų neįmanoma išvardyti.

Greitas startas

Trys curl iškvietimai — ir pamatėte viską.

# Būsena + rakto autentifikavimas
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Stebėsenos žurnalas, nuo pradžios, puslapiais po 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalifikuoti 42 įvykį (rašymo aprėptis)
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"}'

Puslapiavimas viena taisykle

Perduokite depuisSeq (0 pirmame iškvietime) ir limite (ne daugiau kaip 500): atsakymas surikiuotas didėjančia seq tvarka ir grąžina prochainSeq, kurį kitame iškvietime perduodate nepakeistą. Puslapis, trumpesnis už limite, reiškia žurnalo pabaigą — prochainSeq tada lieka stabilus ir tarnauja kaip apklausos žymeklis. Be depuisSeq gaunate rodinį „naujausi pirmiausia“, apribotą iki 500.

Portfelis užklausiamas per /api/v1/portefeuille/agregats — skaitikliai, vienas atsakymas, jokio puslapiavimo.

Webhook'ai

Pasirašyti, pažymėti laiko žyma, pristatomi bent vieną kartą.

Užuot apklausinėję žurnalą, gaukite jį: „Vigilae“ pristato įvykius į jūsų URL, eilės tvarka, paketais ne didesniais kaip 100. Pristatymas yra at-least-once — žymeklis pasislenka tik gavus jūsų 2xx, paketas po paketo — o idempotencija remiasi seq: kiekvieną seką apdorokite lygiai vieną kartą (#idempotence).

Parašo tikrinimas

Kiekvienas pristatymas neša antraštę x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Perskaičiuokite v1 iš gauto neapdoroto kūno ir atmeskite bet kokią laiko žymą t, senesnę nei 5 min.: tai apsauga nuo pakartojimo. Paslapties rotacijos metu antraštėje yra po vieną v1 kiekvienai dar galiojančiai paslapčiai (24 val. persidengimas): priimkite, jei sutampa bent viena.

// Node — parašo tikrinimas (be priklausomybių)
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; // apsauga nuo pakartojimo
  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 — tas pats tikrinimas
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  # apsauga nuo pakartojimo
    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

Pereinamuoju laikotarpiu: senasis formatas sha256=HMAC(body) jau veikiantiems gavėjams vis dar siunčiamas antraštėje x-vigilae-signature-legacy; jį pašalinti numatyta kartu su webhook'ų v2. Nauji gavėjai tikrina aukščiau aprašytą schemą su laiko žyma, o ne senąją.

Rotacija paleidžiama iš konsolės (programos pusėje — POST /connect/webhook/rotation): 24 val. senoji paslaptis dar pasirašo — laiko užtenka įdiegti naująją jūsų pusėje be gedimų lango.

Įterptieji valdikliai

Budrumo būsena, jūsų ekranuose.

Jūsų programinė įranga jau kuria bylas per API; valdikliai suteikia trūkstamą paviršių: parodyti bylos budrumo būseną jūsų kliento kortelėje, nekuriant naujos atitikties sąsajos. Procesas vyksta trimis žingsniais — jūsų serveris išduoda trumpai galiojantį ženklą, grąžintas URL patenka į iframe, valdiklis rodo. Jis tik rodo: jokio sprendimo, jokio vertinimo, jokio įrašymo per valdiklį niekada nevyksta. Paspaudus atsidaro Vigilae programa, kurioje veikia identifikuotas žmogus.

1. Išduoti ženklą — serverio pusėje, niekada puslapyje

Raktas vgk_ niekada nepasiekia naršyklės. Jūsų serveris kreipiasi į išdavimo paslaugą su specialia embed:emettre aprėptimi (pažymima kuriant raktą, niekada nepaveldima), ir į puslapį nukeliauja tik trumpas ženklas: penkiolika minučių pagal numatytuosius nustatymus, ribojama 5–60, susietas su viena byla, vienu komponentu, viena deklaruota kilme. Jis keliauja URL fragmente — jis nepasiekia nei mūsų, nei jūsų žurnalų.

# Ženklas, skirtas Compliance Button, užrašas parinktas iš katalogo
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. Įdėti iframe — paleidiklis, per dešimt eilučių

Paleidiklis vigilae-embed.js sukuria izoliuotą iframe, atlieka handshake ir seka valdiklio dydį (ribojamą — iframe niekada nediktuoja savo aukščio jūsų puslapiui). CSP atžvilgiu jūsų puslapis atveria tik vieną direktyvą: frame-src https://vigilae.org. Nereikia jokio inline skripto, jokios priklausomybės. Ranka parašyta iframe veikia lygiai taip pat gerai.

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

// Jūsų skripte: url ateina iš JŪSŲ serverio, kuris išdavė ženklą
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // pasibaigus galiojimui: išduoti iš naujo serverio pusėje
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) įkelia naują ženklą; widget.demonter() pašalina viską.

3. Compliance Button: jūsų užrašas, mūsų būsena

Mygtuko užrašas renkamas iš uždaro katalogo — niekada laisvas tekstas paviršiuje, kuriame kalbama apie budrumą. Apvalkalas juos rodo tik prancūzų arba anglų kalba (parametras ?lang=), dar ne jūsų kalba — toliau pateiktas sąrašas paaiškina jų reikšmę:

controler_client — „Patikrinti šį klientą“ (numatytoji)
lancer_vigilance — „Pradėti budrumą“
verifier_be — „Patikrinti tikruosius savininkus“
preparer_dossier — „Parengti PPTFP bylą“

Tuo tarpu būsenos taškas rodo Vigilae apskaičiuotą būseną: a_jour (žalia — atranka ir rizikos vertinimas atnaujinti), a_revoir (gintarinė — atranka arba rizikos vertinimas pasenę, arba šaltinis paskutinio vykdymo metu neatsakė), alerte (raudona — bent vienas įspėjimas, kurį reikia įvertinti), inconnu (pilka — byla niekada netikrinta). Užrašas konfigūruojamas, semantika — niekada: spalva susieta su būsena pačiame apvalkale, kuris ignoruoja bet kokį bandymą ją perrašyti per postMessage. Byla, esanti įspėjimo būsenoje, rodo įspėjimą, kad ir koks būtų apipavidalinimas.

Visas postMessage kontraktas

Valdiklis siunčia vigilae:pret, vigilae:taille (automatinis dydžio koregavimas), vigilae:expire (išduokite iš naujo serverio pusėje, tada išsiųskite vigilae:jeton) ir vigilae:ouvrir. Niekada jokio vardo, rizikos ar įspėjimo pranešime: jūsų programinė įranga jau turi viską per tiesiogiai tarp serverių veikiančią API, ir šis kanalas antru netaps.

Kilmes deklaruoja biuro administratorius. Įterptasis ženklas susietas su deklaruota jūsų biuro kilme — būtent ji valdo apvalkalo frame-ancestors CSP. Administratorius ją deklaruoja tiesiai Vigilae, ekrane „Integracijos ir saugumas“: ne daugiau kaip dešimt https:// kilmių, aiškiai nurodytas šeimininkas, niekada pakaitos simbolio; komponentai, kuriuos jis įjungia; ir masinis atšaukimas, vienu veiksmu iškart sustabdantis visus jau išduotus ženklus. http://localhost leidžiamas tik bandomajame biure — parašykite adresu contact@vigilae.org (tema „Įterptieji valdikliai“), kad jį atidarytų jūsų integracijos laikotarpiui. Jei kilmė nedeklaruota: išdavimas atmetamas su 400. Instancija, kurios kilmių saugykla neprijungta: aiškus 501 — žr. #embed-indisponible.

Testavimo aplinka

Smėlio dėžė: pagal užklausą.

Savitarnos smėlio dėžės kol kas nėra — verčiau pasakome tai čia, nei leidžiame jums tai atrasti patiems. Parašykite adresu contact@vigilae.org (tema „API prieiga“): jūsų integracijos laikotarpiui atveriame bandomąjį biurą su fiktyviais duomenimis ir liekame pasiekiami, kol darbas juda į priekį.

Kiekviena API klaidų klasė turi stabilų adresą klaidų žinyne: #authentification, #scopes, #cloisonnement, #debit, #signature… API klaidų atsakymai rodys būtent į šiuos inkarus.

API pagal konstrukciją nepateikia nei pranešimų apie įtartinus sandorius, nei pažodinio klientų turinio (Prancūzijos CMF L.561-18 str.). API nepriima jokio budrumo sprendimo: ji pateikia ir kvalifikuoja įvykius; sprendžia profesionalas.