Vigilae Connect

API, mida saab lugeda enne allkirjastamist.

Spetsifikatsioon on avalik, webhook'i allkirja saab teie poolel kontrollida kümne reaga. See leht dokumenteerib selle, mida API täna avab — ei midagi enamat, ja see on taotluslik: mida ei ole tarnitud, seda ei dokumenteerita.

OpenAPI spetsifikatsioon loetav ilma võtme ja kontota
Mitte kunagi kahtlase tehingu teadet, mitte kunagi kliendi sõnasõnalist sisu
Allkirjastatud webhook'id, kontrollitavad väljaspool Vigilaed

Loe spetsifikatsiooni Vigade teatmik

Serveeritud API enda poolt: leping, mida loete, on seesama, mis töötab.

Ulatus

Kogu teekond — ja kaks välistust, mis paigast ei nihku.

Teie tarkvara suudab viia toimiku algusest lõpuni: luua kliendi, avada toimiku, laadida üles dokumendid, käivitada sõelumise, deklareerida tegelikud kasusaajad, lugeda riskihinnangut ja võtta välja tõenditoimiku. Kaks asja ei liigu sealt kunagi läbi ja see ei ole paketi piirang: ükski kahtlase tehingu teade ega teie kliendi sõnasõnaline sisu. Esimene on toiming, mille seadus jätab teate esitajale; teine ei kuulu integratsioonitorusse.

Toimik algusest lõpuni

Kliendid, toimikud, tõendavad dokumendid, sõelumine, tegelikud kasusaajad, riskihinnang, tõenditoimik, terviklikkuse kontroll. Igal ressursil on oma skoop: teie võti avab ainult selle, mille te sellele andsite.

Seirepäevik ja koondnäitajad

Büroo pKYC sündmused — aegunud dokument, tegeliku kasusaaja muutus, menetlemist ootav kordussõelumine — ja portfelli loendurid teie armatuurlaua jaoks. Vastus on alati piiratud, kursor püsiv.

Igal kirjutamisel on nimi

Üleslaadimine, sõelumine, kvalifitseerimine: iga kirjutamine nõuab oma skoopi ja jätab jälje operaatorist. Anonüümne kvalifitseerimine lükatakse tagasi — integratsioon salvestab inimese otsuse, ise ta otsuseid ei tee.

API on kavandatud serverist serverisse: võti brauserisse tarnitud koodis on avaldatud võti. Laske võtit hoida serveripoolsel puhverserveril, mitte kunagi lehel.

Võtmed

Piiritletud skoopidega võtmed, kuvatakse üks kord, tühistatavad kohe.

Vorming. Iga võti algab vgk_-ga ja saadetakse kujul Authorization: Bearer vgk_…. Saladust kuvatakse ainult loomisel: meie ei säilita muud kui selle SHA-256 räsi.
Skoobid. Võti kannab ainult neid skoope, mis loomisel märgiti: üldised lecture (lugemine, vaikimisi) ja ecriture (kirjutamine) või peeneteralised, ressurss ressursi haaval — clients:, dossiers:, pieces:, criblage: (kas lecture või ecriture), origine-fonds:lecture, journal:lecture.
Pärimine käib järelliite järgi ja ainult ühes suunas: lecture katab iga *:lecture, ecriture iga *:ecriture; peeneteraline skoop ei ava midagi endast väljaspool.
Kuus skoopi jäävad sellest paarist välja ega päri seetõttu ühestki üldisest võtmest: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Igaüks delegeeritakse eraldi, võtme loomisel.
Ilma nõutava skoobita võti saab 403 — vt #scopes.
Aegumine. Üks aasta pärast loomist (nähtav büroo konsoolis). Aegunud võti saab selgesõnalise 401 — vt #cle-expiree.
Võtme kehtivus võib lõppeda ka enne seda kuupäeva, kui API ei kuulu enam büroo tellimusse. Lõpp saabub siis vähemalt 30 päeva pärast esimest e-kirja büroole, kuupäeval, mille nimetab teine e-kiri, mis saadetakse vähemalt 7 päeva ette. Kui see kuupäev on määratud, on see nähtav büroo konsoolis (GET /connect/cles väli coupure_le) ja iga vastu võetud päringu vastus teatab sellest päises Sunset, kuni see kätte jõuab. Pärast seda kuupäeva saab päring #authentification all kirjeldatud 401, väljaga "motif": "fin_option_api"; kui API kuulub taas tellimusse, kehtib võti uuesti, kuni oma kehtivusaja lõpuni.
Tühistatud võti ei tule koos API-ga tagasi. Ja kui kogu tellimus peatatakse või see lõpeb, lakkavad võtmed kohe kehtimast, ilma selle tähtajata.
Määr. 60 päringut minutis võtme kohta (võtmekaupa muudetav). 429 kannab päist Retry-After ning päiseid X-RateLimit-Limit / -Remaining / -Reset.
Tühistamine. Kohene, konsoolist. Lahendamine käib räsi järgi: võtmeid ei saa loendada.

Kiirstart

Kolm curl-päringut ja olete kõike näinud.

# Tervis + võtme autentimine
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Seirepäevik, algusest peale, 100 kaupa lehtedel
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalifitseeri sündmus 42 (kirjutamisskoop)
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"}'

Lehekülgedeks jaotamine, ühe reegliga

Edastage depuisSeq (esimesel päringul 0) ja limite (ülempiir 500): vastus on sorditud kasvava seq järgi ja tagastab prochainSeq, mis tuleb järgmisel päringul muutmata kujul tagasi anda. Lehekülg, mis on lühem kui limite, tähendab päeviku lõppu — prochainSeq jääb siis stabiilseks ja toimib pollimiskursorina. Ilma depuisSeq-ta saate vaate „uusimad enne“, piiratud 500-ga.

Portfelli päritakse aadressilt /api/v1/portefeuille/agregats — loendurid, üks vastus, ilma lehekülgedeks jaotamiseta.

Webhook'id

Allkirjastatud, ajatempliga, kohale toimetatud vähemalt üks kord.

Selle asemel et päevikut pollida, võtke see vastu: Vigilae toimetab sündmused teie URL-ile, järjekorras, kuni 100 kaupa partiides. Kohaletoimetamine on at-least-once — kursor liigub edasi ainult teie 2xx peale, partii kaupa — ja idempotentsus käib seq järgi: töödelge iga järjenumber täpselt üks kord (#idempotence).

Allkirja kontrollimine

Iga saadetis kannab päist x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Arvutage v1 uuesti saadud toorest kehast ja lükake tagasi iga ajatempel t, mis on vanem kui 5 min: see ongi kordusrünnete tõke. Saladuse rotatsiooni ajal kannab päis üht v1 iga veel kehtiva saladuse kohta (24 t kattumine): aktsepteerige, kui mõni neist klapib.

// Node — allkirja kontroll (ilma sõltuvuseta)
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; // kordusrünnete tõke
  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 — sama kontroll
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  # kordusrünnete tõke
    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

Üleminekuks: vana vorming sha256=HMAC(body) väljastatakse endiselt päises x-vigilae-signature-legacy juba töötavate vastuvõtjate jaoks; selle eemaldamine on kavas koos webhook'ide v2-ga. Uued vastuvõtjad kontrollivad ülaltoodud ajatempliga skeemi, mitte vana.

Rotatsioon käivitatakse konsoolist (rakenduse poolel POST /connect/webhook/rotation): 24 t jooksul allkirjastab vana saladus endiselt — aega juurutada uus teie poolel ilma tõrkeaknata.

Manustatud vidinad

Valvsuse olek, otse teie ekraanidel.

Teie tarkvara loob toimikuid juba API kaudu; vidinad annavad sellele puuduva pinna: toimiku valvsuse oleku näitamise teie kliendikaardil, ilma vastavuse kasutajaliidest uuesti üles ehitamata. Voog koosneb kolmest sammust — teie server väljastab lühiajalise tokeni, tagastatud URL läheb iframe'i, vidin kuvab. Kuvamine ongi kõik, mida ta teeb: ühtegi otsust, ühtegi kvalifitseerimist, ühtegi kirjutamist ei liigu kunagi vidina kaudu. Klõps avab Vigilae rakenduse, kus tegutseb tuvastatud inimene.

1. Tokeni väljastamine — serveri poolel, mitte kunagi lehel

Võti vgk_ ei puuduta kunagi brauserit. Teie server kutsub väljastajat dedikeeritud embed:emettre skoobiga (märgitud võtme loomisel, mitte kunagi pärandatud) ja lehele jõuab ainult lühiajaline token: vaikimisi viisteist minutit, piiratud vahemikuga 5-60, seotud ühe toimiku, ühe komponendi, ühe deklareeritud päritoluga. See liigub URL-i fragmendis — see ei jõua ei meie ega teie logidesse.

# Token Compliance Buttoni jaoks, silt valitud kataloogist
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. Iframe'i paigutamine — käivitaja, kümne reaga

Käivitaja vigilae-embed.js loob sandboxitud iframe'i, teeb handshake'i ja jälgib vidina suurust (piiratud — iframe ei dikteeri kunagi oma kõrgust teie lehele). CSP poolel avab teie leht vaid ühe direktiivi: frame-src https://vigilae.org. Ühtegi inline-skripti pole vaja, ühtegi sõltuvust. Käsitsi kirjutatud iframe töötab sama hästi.

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

// Teie skriptis: url tuleb TEIE serverist, mis kutsus väljastajat
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // aegumisel: väljasta uuesti serveri poolel
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) saadab värske tokeni; widget.demonter() eemaldab kõik.

3. Compliance Button: teie silt, meie olek

Nupu silt valitakse suletud kataloogist — mitte kunagi vaba tekst pinnal, mis räägib valvsusest — shell kuvab sildid prantsuse või inglise keeles (parameeter ?lang=), veel mitte teie keeles; allolev loend annab nende tähenduse:

controler_client — „Kontrolli seda klienti“ (vaikimisi)
lancer_vigilance — „Alusta hoolsusmeetmeid“
verifier_be — „Kontrolli tegelikke kasusaajaid“
preparer_dossier — „Valmista ette AML/CFT toimik“

Olekupunkt seevastu näitab Vigilae arvutatud olekut: a_jour (roheline — sõelumine ja hinnang on ajakohased), a_revoir (kollane — sõelumine või hinnang on aegunud, või allikas ebaõnnestus viimasel käivitamisel), alerte (punane — vähemalt üks hoiatus, mida läbi vaadata), inconnu (hall — toimikut pole kunagi sõelutud). Silt on seadistatav, semantika ei ole seda kunagi: värv on seotud olekuga shelli enda sees, mis eirab iga postMessage'i katset seda üle kirjutada. Hoiatusolekus toimik kuvab hoiatuse, olenemata kujundusest.

postMessage leping, tervikuna

Vidin väljastab sündmused vigilae:pret, vigilae:taille (automaatne suuruse kohandamine), vigilae:expire (väljasta uuesti serveri poolel, seejärel postita vigilae:jeton) ja vigilae:ouvrir. Mitte kunagi nime, riski ega hoiatust sõnumi sees: teie tarkvaral on juba kõik olemas server-server API kaudu, ja see kanal ei muutu kunagi teiseks API-ks.

Päritolu deklareerimine: büroo administraatori poolt. Manustatud vidina token on seotud teie büroo deklareeritud päritoluga — just see juhib shelli frame-ancestors CSP-d. Administraator deklareerib selle otse Vigilaes, ekraanil „Integratsioonid ja turvalisus“: kuni kümme https:// päritolu, selgesõnaline host, mitte kunagi metamärki; komponendid, mida ta sisse lülitab; ja massiline tühistamine, mis kustutab ühe toiminguga kõik juba väljastatud tokenid. http://localhost on lubatud ainult proovibüroo puhul — kirjutage aadressile contact@vigilae.org (teema „Embedded widgets“), et see avataks teie liidestuse ajaks. Ühtegi päritolu deklareerimata: väljastaja keeldub 400-ga. Instants, mille päritolude hoidla ei ole ühendatud: selgesõnaline 501 — vt #embed-indisponible.

Testkeskkond

Liivakast: taotluse peale.

Iseteeninduslikku liivakasti veel ei ole — eelistame seda siin öelda, mitte lasta teil seda ise avastada. Kirjutage aadressile contact@vigilae.org (teema „API access“): avame teie liidestuse ajaks fiktiivsete andmetega proovibüroo ja jääme selle edenemise ajal kättesaadavaks.

Igal API veaklassil on püsiv aadress vigade teatmikus: #authentification, #scopes, #cloisonnement, #debit, #signature… API veavastused osutavad nendele ankrutele.

API ei ava kahtlase tehingu teateid ega kliendi sõnasõnalist sisu, juba ehituselt (Prantsuse CMF art. L.561-18). API ei tee ühtegi hoolsusotsust: see avab ja kvalifitseerib sündmusi; otsustab professionaal.