Vigilae Connect

API li tista' taqraha qabel ma tiffirma.

L-ispeċifikazzjoni hija pubblika, is-superfiċji huma newtrali, 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

Superfiċji newtrali, bil-kostruzzjoni.

L-API tesponi dak li integratur jista' jikkonsma mingħajr ma jmiss is-segretezza tal-fajls: il-ġurnal tal-monitoraġġ u l-kontaturi. Il-kontenut ta' fajl ta' viġilanza, id-dokumenti, ir-rapporti ta' tranżazzjonijiet suspettużi ma jgħaddux minn din l-API — mhux limitazzjoni tal-pjan, iżda l-arkitettura.

Ġurnal tal-monitoraġġ

L-avvenimenti pKYC tal-uffiċċju — dokument skadut, bidla fis-sid benefiċjarju, skrinjar mill-ġdid x'jiġi rivedut — f'forma newtrali: sekwenza, tip, severità, data. It-tweġibiet dejjem limitati għal 500 avveniment.

Aggregati tal-portafoll

Kontaturi, qatt fajl: volumi skont l-istatus, dewmien, kompletezza. Biżżejjed biex turi dashboard fl-għodda tiegħek mingħajr ma tidħol fiha l-ebda data ta' klijent.

Kwalifikazzjoni

L-unika kitba: il-kwalifikazzjoni ta' avveniment tal-ġurnal (status qualifie jew clos, dispożizzjoni planifie, traite jew ecarte). Teħtieġ l-iskop tal-kitba — l-inqas privileġġ huwa r-regola, mhux għażla.

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. lecture (qari, l-issettjar awtomatiku) u ecriture (kitba). Ċ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.
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.

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.