Vigilae Connect

API, ko var izlasīt pirms parakstīšanas.

Specifikācija ir publiska, webhook parakstu jūsu pusē var pārbaudīt desmit rindās. Šī lapa dokumentē to, ko API atklāj šodien — neko vairāk, un tas ir apzināti: kas nav piegādāts, tas netiek dokumentēts.

OpenAPI specifikācija lasāma bez atslēgas un bez konta
Nekad neviens aizdomīga darījuma ziņojums, nekad klienta saturs vārds vārdā
Parakstīti webhooki, pārbaudāmi ārpus Vigilae

Lasīt specifikāciju Kļūdu uzziņa

To pasniedz pats API: līgums, ko lasāt, ir tas, kas darbojas.

Perimetrs

Viss process un divas robežas, kas nemainīsies.

Jūsu programmatūra var novest lietu no sākuma līdz beigām: izveidot klientu, atvērt lietu, augšupielādēt dokumentus, palaist pārbaudi, norādīt patiesos labuma guvējus, nolasīt riska novērtējumu un izgūt pierādījumu lietu. Divas robežas paliek nemainīgas, un tas nav abonementa ierobežojums: caur šo kanālu nenonāk neviens ziņojums par aizdomīgu darījumu un neviens jūsu klienta teiktais vārds pa vārdam. Pirmais ir darbība, ko likums atstāj ziņotājam; otrajam nav vietas integrācijas kanālā.

Lieta no sākuma līdz beigām

Klienti, lietas, apliecinošie dokumenti, pārbaude, patiesie labuma guvēji, riska novērtējums, pierādījumu lieta, integritātes pārbaude. Katram resursam ir savs tvērums: jūsu atslēga atver tikai to, ko esat tai piešķīris.

Žurnāls un apkopotie rādītāji

Biroja pKYC notikumi — dokuments ar beigušos derīguma termiņu, patiesā labuma guvēja maiņa, apstrādājama atkārtota pārbaude — un portfeļa skaitītāji jūsu vadības panelim. Atbilde vienmēr ir ierobežota, kursors stabils.

Katram ierakstam ir vārds

Augšupielādēt, pārbaudīt, kvalificēt: katrs ieraksts prasa savu tvērumu un fiksē operatoru. Anonīma kvalificēšana tiek noraidīta — integrācija reģistrē cilvēka lēmumu, bet pati nevienu nepieņem.

API ir veidots darbam serveris–serveris: atslēga kodā, kas tiek piegādāts pārlūkam, ir publicēta atslēga. Lai atslēgu tur servera puses starpnieks, nekad — lapa.

Atslēgas

Atslēgas ar ierobežotu tvērumu, parādītas vienreiz, atsaucamas nekavējoties.

Formāts. Katra atslēga sākas ar vgk_ un tiek sūtīta kā Authorization: Bearer vgk_…. Noslēpums tiek parādīts tikai izveides brīdī: mēs glabājam vienīgi tā SHA-256 nospiedumu.
Tvērumi. Atslēga nes tikai tos tvērumus, kas atzīmēti tās izveidē: vispārīgos lecture (lasīšana, noklusējums) un ecriture (rakstīšana) vai smalkos, resursu pēc resursa — clients:, dossiers:, pieces:, criblage: (lecture vai ecriture variantā), origine-fonds:lecture, journal:lecture.
Mantošana balstās uz piedēkli un darbojas tikai vienā virzienā: lecture aptver katru *:lecture, ecriture — katru *:ecriture; smalks tvērums neatver neko ārpus sevis.
Seši tvērumi iziet ārpus šī pāra un tāpēc netiek mantoti ne no vienas vispārīgas atslēgas: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Katrs tiek deleģēts atsevišķi, atslēgas izveidē.
Atslēga bez vajadzīgā tvēruma saņem 403 — sk. #scopes.
Derīguma termiņš. Viens gads pēc izveides (redzams biroja konsolē). Atslēga ar beigušos termiņu saņem nepārprotamu 401 — sk. #cle-expiree.
Atslēgu var pārstāt pieņemt arī pirms šī datuma, ja API vairs nav iekļauta biroja abonementā. Pārtraukšana tad notiek vismaz 30 dienas pēc pirmā e-pasta ziņojuma birojam, datumā, ko norāda otrs e-pasta ziņojums, kas nosūtīts vismaz 7 dienas iepriekš. Tiklīdz šis datums ir noteikts, tas redzams biroja konsolē (GET /connect/cles lauks coupure_le), un katra atbilde uz pieņemtu izsaukumu to paziņo galvenē Sunset, līdz tas pienāk. Pēc šī datuma izsaukums saņem 401, kas aprakstīts sadaļā #authentification, ar "motif": "fin_option_api"; ja API atkal tiek iekļauta abonementā, atslēga atkal tiek pieņemta līdz tās pašas derīguma termiņa beigām.
Atsaukta atslēga kopā ar API neatgriežas. Un, ja viss abonements tiek apturēts vai beidzas, atslēgas nekavējoties vairs netiek pieņemtas, bez šī termiņa.
Limits. 60 pieprasījumi minūtē uz atslēgu (pielāgojams katrai atslēgai). 429 atbilde nes Retry-After un galvenes X-RateLimit-Limit / -Remaining / -Reset.
Atsaukšana. Tūlītēja, no konsoles. Atpazīšana notiek pēc nospieduma: atslēgas nevar uzskaitīt.

Ātrā uzsākšana

Trīs curl izsaukumi — un jūs esat redzējuši visu.

# Veselības pārbaude + atslēgas autentifikācija
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Uzraudzības žurnāls no sākuma, pa 100 lapā
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificēt notikumu 42 (rakstīšanas tvērums)
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"}'

Lapošana vienā noteikumā

Nododiet depuisSeq (0 pirmajā izsaukumā) un limite (ne vairāk kā 500): atbilde ir kārtota pēc augoša seq un atgriež prochainSeq, ko nākamajā izsaukumā nodod tālāk nemainītu. Lapa, kas īsāka par limite, nozīmē žurnāla beigas — prochainSeq tad paliek stabils un kalpo kā aptaujas kursors. Bez depuisSeq jūs saņemat skatu „jaunākie vispirms”, ierobežotu līdz 500.

Portfeli vaicā ar /api/v1/portefeuille/agregats — skaitītāji, viena atbilde, bez lapošanas.

Webhooki

Parakstīti, ar laikspiedolu, piegādāti vismaz vienreiz.

Tā vietā, lai žurnālu aptaujātu, saņemiet to: Vigilae piegādā notikumus uz jūsu URL, secībā, partijās pa ne vairāk kā 100. Piegāde ir at-least-once — kursors virzās uz priekšu tikai pēc jūsu 2xx, partiju pa partijai — un idempotence ir pēc seq: apstrādājiet katru secību tieši vienu reizi (#idempotence).

Paraksta pārbaude

Katra piegāde nes galveni x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Pārrēķiniet v1 no saņemtā neapstrādātā ķermeņa un noraidiet jebkuru laikspiedolu t, kas vecāks par 5 min: tā ir aizsardzība pret atkārtošanu. Noslēpuma rotācijas laikā galvene nes vienu v1 katram vēl derīgajam noslēpumam (24 h pārklāšanās): pieņemiet, ja sakrīt jebkurš no tiem.

// Node — paraksta pārbaude (bez atkarībām)
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 — tā pati pārbaude
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

Pārejas posmā: vecais formāts sha256=HMAC(body) jau esošajiem saņēmējiem joprojām tiek izsūtīts galvenē x-vigilae-signature-legacy; tā izņemšana ir plānota kopā ar webhooks v2. Jauni saņēmēji pārbauda augstāk aprakstīto laikspiedola shēmu, nevis veco.

Rotāciju iedarbina no konsoles (lietojumprogrammas pusē POST /connect/webhook/rotation): 24 h vecais noslēpums vēl paraksta — laiks izvietot jauno jūsu pusē bez atteices loga.

Iegultie logrīki

Uzraudzības statuss jūsu ekrānos.

Jūsu programmatūra jau izveido lietas caur API; logrīki tai dod trūkstošo virsmu: rādīt lietas uzraudzības statusu jūsu klienta profilā, nerekonstruējot atbilstības saskarni. Process notiek trīs soļos — jūsu serveris izsniedz īslaicīgu marķieri, atgrieztais URL nonāk iframe, logrīks to attēlo. Tas tikai attēlo — ne vairāk: ne lēmums, ne kvalificēšana, ne ieraksts nekad nenotiek caur logrīku. Klikšķis atver Vigilae lietotni, kur rīkojas identificēts cilvēks.

1. Izsniegt marķieri — servera pusē, nekad lapā

Atslēga vgk_ nekad nesasniedz pārlūkprogrammu. Jūsu serveris izsauc mint ar tam paredzēto tvērumu embed:emettre (atzīmēts atslēgas izveides brīdī, nekad nemantots), un uz lapu nonāk tikai īsais marķieris: piecpadsmit minūtes pēc noklusējuma, robežās 5-60, piesaistīts vienai lietai, vienam komponentam, vienai deklarētai izcelsmei. Tas ceļo URL fragmentā — tas nesasniedz ne mūsu, ne jūsu žurnālus.

# Marķieris pogai Compliance Button, etiķete izvēlēta no 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. Ievietot iframe — palaidējs, desmit rindās

Palaidējs vigilae-embed.js izveido smilškastes iframe, veic handshake un seko logrīka izmēram (ierobežots — iframe nekad nediktē savu augstumu jūsu lapai). CSP ziņā jūsu lapa atver tikai vienu direktīvu: frame-src https://vigilae.org. Nav vajadzīgs neviens inline skripts, nav atkarību. Ar roku rakstīts iframe darbojas tikpat labi.

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

// Jūsu skriptā: url nāk no JŪSU servera, kas izsauca mint
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // pēc termiņa beigām: atkārtoti izsniegt servera pusē
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) nodod jaunu marķieri; widget.demonter() noņem visu.

3. Compliance Button: jūsu etiķete, mūsu statuss

Pogas etiķete tiek izvēlēta no slēgta kataloga — nekad brīvs teksts virsmā, kas runā par uzraudzību. Apvalks tās rāda tikai franču vai angļu valodā (parametrs ?lang=), vēl ne jūsu valodā — saraksts zemāk sniedz to nozīmi:

controler_client — „Pārbaudīt šo klientu” (noklusējums)
lancer_vigilance — „Sākt uzticamības pārbaudi”
verifier_be — „Pārbaudīt patiesos labuma guvējus”
preparer_dossier — „Sagatavot NILLTPF lietu”

Savukārt statusa punkts rāda Vigilae aprēķinātu statusu: a_jour (zaļš — pārbaude un vērtējums ir aktuāli), a_revoir (dzeltens — pārbaude vai vērtējums novecojuši, vai avots pēdējā reizē neizdevās), alerte (sarkans — vismaz viens brīdinājums jāizskata), inconnu (pelēks — lieta nekad nav pārbaudīta). Etiķete ir konfigurējama, semantika — nekad: krāsa ir piesaistīta statusam pašā apvalkā, kas ignorē jebkuru mēģinājumu to pārrakstīt ar postMessage. Lieta ar brīdinājumu rāda brīdinājumu neatkarīgi no noformējuma.

postMessage līgums pilnā apjomā

Logrīks izsūta vigilae:pret, vigilae:taille (automātiska pielāgošana), vigilae:expire (izsniedziet atkārtoti servera pusē, tad nosūtiet vigilae:jeton) un vigilae:ouvrir. Nekad vārds, risks vai brīdinājums ziņojumā: jūsu programmatūrai jau ir viss, izmantojot server-to-server API, un šis kanāls nekad nekļūs par otru tādu.

Izcelsmes deklarēšana: to dara jūsu biroja administrators. Iegultā logrīka marķieris ir piesaistīts jūsu biroja deklarētajai izcelsmei — tieši tā vada apvalka frame-ancestors CSP direktīvu. Administrators to deklarē tieši Vigilae, ekrānā „Integrācijas un drošība”: ne vairāk kā desmit https:// izcelsmes, skaidri norādīts saimnieks, nekad aizstājējzīme; komponenti, ko viņš ieslēdz; un masveida atsaukšana, kas vienā solī iznīcina visus jau izsniegtos marķierus. http://localhost ir atļauts tikai smilškastes birojā — rakstiet uz contact@vigilae.org (temats „Iegultie logrīki”), lai to atvērtu jūsu integrācijas laikam. Neviena deklarēta izcelsme: mint atsakās ar 400. Instance, kuras izcelsmju krātuve nav pieslēgta: nepārprotams 501 — sk. #embed-indisponible.

Testa vide

Smilškaste: pēc pieprasījuma.

Pašapkalpošanās smilškastes vēl nav — mēs to labāk pasakām šeit, nekā ļaujam jums to atklāt pašiem. Rakstiet uz contact@vigilae.org (temats „API piekļuve”): mēs atveram izmēģinājuma biroju ar fiktīviem datiem uz visu jūsu integrācijas laiku un paliekam sasniedzami, kamēr tā virzās uz priekšu.

Katrai API kļūdu klasei ir stabila adrese kļūdu uzziņā: #authentification, #scopes, #cloisonnement, #debit, #signature… API kļūdu atbildes norādīs uz šiem enkuriem.

API pēc uzbūves neatklāj ne aizdomīgu darījumu ziņojumus, ne klientu saturu vārds vārdā (Francijas CMF L.561-18. pants). API nepieņem nevienu uzraudzības lēmumu: tas atklāj un kvalificē notikumus; lemj profesionālis.