Vigilae Connect

API li tista' taqraha qabel ma tiffirma.

L-ispeċifikazzjoni hija pubblika, il-firma tal-webhooks tista' tiġi vverifikata f'għaxar linji min-naħa tiegħek. Din il-paġna tiddokumenta dak li l-API tesponi llum — xejn aktar, u dan apposta: dak li mhux imwassal mhux dokumentat.

Speċifikazzjoni OpenAPI li tinqara mingħajr ċavetta u mingħajr kont
Qatt rapport ta' tranżazzjoni suspettuża, qatt verbatim ta' klijent
Webhooks iffirmati, verifikabbli barra minn Vigilae

Aqra l-ispeċifikazzjoni Referenza tal-iżbalji

Servuta mill-API stess: il-kuntratt li taqra huwa dak li jaħdem.

Il-perimetru

Il-perkors sħiħ, u żewġ esklużjonijiet li mhumiex se jinbidlu.

Is-softwer tiegħek jista' jmexxi fajl mill-bidu sat-tmiem: joħloq il-klijent, jiftaħ il-fajl, itella' d-dokumenti, iniedi l-iskrinjar, jiddikjara s-sidien benefiċjarji, jaqra l-klassifikazzjoni tar-riskju u jniżżel il-fajl ta' prova. Żewġ affarijiet qatt mhumiex se jgħaddu minn hemm, u din mhijiex limitazzjoni tal-abbonament: l-ebda rapport ta' tranżazzjoni suspettuża, u l-ebda kliem tal-klijent tiegħek riprodott kelma b'kelma. L-ewwel waħda hija att li l-liġi tirriżerva għall-persuna li tagħmel ir-rapport; it-tieni waħda m'għandhiex postha f'kanal ta' integrazzjoni.

Il-fajl, mill-bidu sat-tmiem

Klijenti, fajls, dokumenti ta' sostenn, skrinjar, sidien benefiċjarji, klassifikazzjoni tar-riskju, fajl ta' prova, verifika tal-integrità. Kull riżorsa għandha l-ambitu tagħha: iċ-ċavetta tiegħek tiftaħ biss dak li tajtha int.

Reġistru tal-avvenimenti u aggregati

L-avvenimenti pKYC tad-ditta — dokument skadut, bidla fis-sid benefiċjarju, skrinjar mill-ġdid li għad irid isir — u kontaturi tal-portafoll għall-pannell ta' kontroll tiegħek. Ir-risposta dejjem limitata fid-daqs, il-kursur stabbli.

Dak li tikteb iġorr isem

Tella' dokument, skrinja, ikkwalifika: kull kitba titlob l-ambitu tagħha u tirreġistra l-operatur. Kwalifikazzjoni anonima tiġi rifjutata — l-integrazzjoni tirreġistra deċiżjoni umana, hi stess ma tieħu l-ebda deċiżjoni.

L-API hija maħsuba server-to-server: ċavetta f'kodiċi mibgħut lill-browser hija ċavetta ppubblikata. Ħalli proxy fuq is-server iżomm iċ-ċavetta, qatt il-paġna.

Ċwievet

Ċwievet bi skopijiet definiti, murija darba, revokabbli immedjatament.

Format. Kull ċavetta tibda b'vgk_ u tintbagħat bħala Authorization: Bearer vgk_…. Is-sigriet jintwera biss mal-ħolqien: aħna ma nżommu xejn ħlief id-digest SHA-256 tiegħu.
Skopijiet. Ċavetta ġġorr biss l-iskopijiet immarkati meta nħolqot: dawk ġenerali lecture (qari, l-issettjar awtomatiku) u ecriture (kitba), jew skopijiet fini, riżorsa b'riżorsa — clients:, dossiers:, pieces:, criblage: (f'lecture jew ecriture), origine-fonds:lecture, journal:lecture.
Il-wirt isegwi s-suffiss, u jimxi f'direzzjoni waħda biss: lecture ikopri kull *:lecture, u ecriture kull *:ecriture; skop fini ma jiftaħ xejn lil hinn minnu nnifsu.
Sitt skopijiet joħorġu minn din il-koppja u għalhekk ma jintirtu minn ebda ċavetta ġenerali: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kull wieħed jiġi ddelegat għalih, meta tinħoloq iċ-ċavetta.
Ċavetta mingħajr l-iskop meħtieġ tirċievi 403 — ara #scopes.
Skadenza. Sena wara l-ħolqien (viżibbli fil-console tal-uffiċċju). Ċavetta skaduta tirċievi 401 espliċitu — ara #cle-expiree.
Ċavetta tista' wkoll tieqaf tiġi aċċettata qabel din id-data, meta l-API m'għadhiex parti mill-abbonament tal-uffiċċju. Il-waqfien imbagħad jasal mill-inqas 30 jum wara l-ewwel email lill-uffiċċju, fid-data mogħtija mit-tieni email, mibgħuta mill-inqas 7 ijiem qabel. Hekk kif tiġi ffissata, din id-data tidher fil-console tal-uffiċċju (il-qasam coupure_le ta' GET /connect/cles), u kull tweġiba għal sejħa aċċettata tħabbarha fil-header Sunset sakemm tasal. Wara din id-data, is-sejħa tirċievi l-401 deskritt taħt #authentification, b'"motif": "fin_option_api"; jekk l-API terġa' tiddaħħal fl-abbonament, iċ-ċavetta terġa' tiġi aċċettata, sal-iskadenza tagħha stess.
Ċavetta revokata ma terġax lura mal-API. U meta l-abbonament kollu jiġi sospiż jew jintemm, iċ-ċwievet jieqfu jiġu aċċettati minnufih, mingħajr dan il-perjodu.
Rata. 60 talba/minuta għal kull ċavetta (tista' tinbidel għal kull ċavetta). Risposta 429 iġġorr Retry-After u l-headers X-RateLimit-Limit / -Remaining / -Reset.
Revoka. Immedjata, mill-console. Ir-riżoluzzjoni ssir bid-digest: iċ-ċwievet ma jistgħux jiġu enumerati.

Bidu rapidu

Tliet sejħiet curl u tkun rajt kollox.

# Saħħa + awtentikazzjoni taċ-ċavetta
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Ġurnal tal-monitoraġġ, mill-bidu, f'paġni ta' 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Ikkwalifika l-avveniment 42 (skop tal-kitba)
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"}'

Paġnazzjoni, f'regola waħda

Għaddi depuisSeq (0 fl-ewwel sejħa) u limite (limitat għal 500): it-tweġiba tiġi ordnata skont seq tiela' u tirritorna prochainSeq, x'terġa' tgħaddi kif inhu fis-sejħa li jmiss. Paġna iqsar minn limite tfisser tmiem il-ġurnal — prochainSeq imbagħad jibqa' stabbli u jservi bħala kursur tal-polling. Mingħajr depuisSeq, tikseb il-veduta "l-aktar riċenti l-ewwel", limitata għal 500.

Il-portafoll jiġi kkonsultat fuq /api/v1/portefeuille/agregats — kontaturi, tweġiba waħda, l-ebda paġnazzjoni.

Webhooks

Iffirmati, bit-timbru tal-ħin, imwassla mill-inqas darba.

Minflok ma tistaqsi l-ġurnal bil-polling, irċevih: Vigilae iwassal l-avvenimenti fl-URL tiegħek, fl-ordni, f'lottijiet ta' mhux aktar minn 100. Il-kunsinna hija at-least-once — il-kursur jimxi 'l quddiem biss mat-2xx tiegħek, lott b'lott — u l-idempotenza hija skont seq: ipproċessa kull sekwenza eżattament darba (#idempotence).

Il-verifika tal-firma

Kull kunsinna ġġorr il-header x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Erġa' ikkalkula v1 mill-body mhux ipproċessat (raw) li rċevejt, u irrifjuta kull timbru tal-ħin t lil hinn minn 5 min: dan huwa l-anti-replay. Waqt rotazzjoni tas-sigriet il-header iġorr v1 waħda għal kull sigriet għadu validu (sovrapożizzjoni ta' 24 h): aċċetta jekk taqbel kwalunkwe waħda minnhom.

// Node — verifika tal-firma (mingħajr dipendenzi)
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 — l-istess verifika
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

Tranżitorju: il-format il-qadim sha256=HMAC(body) għadu jinħareġ fuq x-vigilae-signature-legacy għar-riċevituri diġà fis-seħħ; it-tneħħija tiegħu hija ppjanata mal-webhooks v2. Riċevituri ġodda jivverifikaw l-iskema bit-timbru tal-ħin ta' hawn fuq, mhux dik il-qadima.

Ir-rotazzjoni tinbeda mill-console (POST /connect/webhook/rotation fuq in-naħa tal-applikazzjoni): għal 24 h is-sigriet il-qadim jibqa' jiffirma — żmien biżżejjed biex tiskjera l-ġdid min-naħa tiegħek mingħajr tieqa ta' falliment.

Widgets inkorporati

L-istat tal-viġilanza, fl-iskrins tiegħek.

Is-softwer tiegħek diġà joħloq il-fajls permezz tal-API; il-widgets jagħtuh is-superfiċje li kienet nieqsa: turi l-istat ta' viġilanza ta' fajl fl-iskeda tal-klijent tiegħek, mingħajr ma terġa' tibni interfaċċja ta' konformità. Il-fluss isir fi tliet passi — is-server tiegħek joħroġ token qasir, l-URL li tirritorna tidħol f'iframe, il-widget juri. Ma jagħmel xejn ħlief juri: l-ebda deċiżjoni, l-ebda kwalifikazzjoni, l-ebda kitba ma tgħaddi minn widget. Il-klikk jiftaħ l-applikazzjoni Vigilae, fejn jaġixxi bniedem identifikat.

1. Toħroġ it-token — min-naħa tas-server, qatt fil-paġna

Iċ-ċavetta vgk_ qatt ma tmiss il-browser. Is-server tiegħek isejjaħ il-mint bl-iskop dedikat embed:emettre (immarkat mal-ħolqien tal-ċavetta, qatt ma tiġi trażmessa awtomatikament) u lejn il-paġna jinżel biss it-token qasir: ħmistax-il minuta b'mod prestabbilit, limitat 5-60, marbut ma' fajl wieħed, komponent wieħed, oriġini ddikjarata waħda. Jivvjaġġa fil-fragment tal-URL — ma jilħaqx la l-logs tagħna u lanqas tiegħek.

# Token għall-Compliance Button, tikketta magħżula mill-katalgu
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. Poġġi l-iframe — il-launcher, f'għaxar linji

Il-launcher vigilae-embed.js joħloq l-iframe sandboxjata, jagħmel il-handshake u jsegwi d-daqs tal-widget (limitat — l-iframe qatt ma tordna l-għoli tagħha lill-paġna tiegħek). Fuq in-naħa tas-CSP, il-paġna tiegħek tiftaħ direttiva waħda biss: frame-src https://vigilae.org. L-ebda skript inline meħtieġ, l-ebda dipendenza. Iframe miktuba bl-idejn taħdem daqstant tajjeb.

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

// Fl-iskript tiegħek: l-url ġejja mis-SERVER TIEGĦEK, li sejjaħ il-mint
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // mal-iskadenza: erġa' toħroġ token min-naħa tas-server
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) idaħħal token frisk; widget.demonter() ineħħi kollox.

3. Il-Compliance Button: it-tikketta tiegħek, l-istat tagħna

It-tikketta tal-buttuna tintgħażel minn katalgu magħluq — qatt test ħieles f'superfiċje li titkellem dwar il-viġilanza. Ix-shell juri dawn it-tikketti bil-Franċiż jew bl-Ingliż biss (parametru ?lang=), għadhom mhux fil-lingwa tiegħek; il-lista hawn taħt tagħti t-tifsira tagħhom:

controler_client — "Ikkontrolla dan il-klijent" (prestabbilit)
lancer_vigilance — "Ibda d-diliġenza dovuta"
verifier_be — "Ivverifika s-sidien benefiċjarji"
preparer_dossier — "Ipprepara l-fajl AML"

Il-punt tal-istatus, min-naħa tiegħu, juri stat ikkalkulat minn Vigilae: a_jour (aħdar — skrinjar u punteġġ aġġornati), a_revoir (oranġjo — skrinjar jew punteġġ skaduti, jew is-sors falla fl-aħħar tmexxija), alerte (aħmar — mill-inqas allert wieħed x'jiġi eżaminat), inconnu (griż — fajl li qatt ma ġie skrinjat). It-tikketta tikkonfigura ruħha, is-semantika qatt: il-kulur huwa marbut mal-istat ġewwa x-shell innifsu, li jinjora kull tentattiv ta' postMessage biex jissostitwixxih. Fajl f'allert juri allert, ikun xi jkun l-istil.

Il-kuntratt postMessage, kollu kemm hu

Il-widget joħroġ vigilae:pret, vigilae:taille (tibdil awtomatiku tad-daqs), vigilae:expire (erġa' toħroġ token min-naħa tas-server, imbagħad ibgħat vigilae:jeton) u vigilae:ouvrir. Qatt isem, riskju jew allert ġewwa messaġġ: is-softwer tiegħek diġà għandu kollox permezz tal-API server-to-server, u dan il-kanal mhux se jsir tieni wieħed.

Id-dikjarazzjoni tal-oriġini: mill-amministratur tal-uffiċċju tiegħek. Token ta' widget inkorporat huwa marbut ma' oriġini ddikjarata tal-uffiċċju tiegħek — hija dik li tmexxi l-CSP frame-ancestors tax-shell. L-amministratur jiddikjaraha direttament fi Vigilae, fuq l-iskrin "Integrazzjonijiet u sigurtà": sa għaxar oriġini https://, ospitu espliċitu, qatt wildcard; il-komponenti li jixgħel; u revoka bil-massa li toqtol, b'ġest wieħed, it-tokens kollha diġà maħruġa. http://localhost huwa permess biss fuq uffiċċju sandbox — ikteb lil contact@vigilae.org (suġġett "Widgets inkorporati") biex jinfetaħ wieħed għat-tul tal-integrazzjoni tiegħek. L-ebda oriġini ddikjarata: il-mint jirrifjuta b'400. Istanza fejn il-ħażna tal-oriġini mhix imqabbda: 501 espliċitu — ara #embed-indisponible.

Ambjent tat-test

Sandbox: fuq talba.

Għad m'hemmx sandbox self-service — nippreferu ngħiduhulek hawn milli nħalluk tiskoprih. Ikteb lil contact@vigilae.org (suġġett "Aċċess API"): niftħu uffiċċju ta' prova b'data fittizja għat-tul tal-integrazzjoni tiegħek, u nibqgħu raġġunġibbli waqt li timxi 'l quddiem.

Kull klassi ta' żball tal-API għandha indirizz stabbli fuq ir-referenza tal-iżbalji: #authentification, #scopes, #cloisonnement, #debit, #signature… It-tweġibiet ta' żball tal-API se jippuntaw lejn dawn l-ankri.

L-API la tesponi rapporti ta' tranżazzjonijiet suspettużi u lanqas verbatim ta' klijenti, bil-kostruzzjoni (art. L.561-18 tal-CMF Franċiż). L-ebda deċiżjoni ta' viġilanza ma tittieħed mill-API: hija tesponi u tikkwalifika l-avvenimenti; il-professjonist jiddeċiedi.