Vigilae Connect

API, mida saab lugeda enne allkirjastamist.

Spetsifikatsioon on avalik, pinnad on neutraalsed, 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

Neutraalsed pinnad, juba ehituselt.

API avab selle, mida integreerija saab tarbida toimikute saladust puudutamata: seirepäeviku ja loendurid. Hoolsustoimiku sisu, dokumendid ja kahtlase tehingu teated ei liigu läbi selle API — see ei ole paketi piirang, vaid arhitektuur.

Seirepäevik

Büroo pKYC sündmused — aegunud dokument, tegeliku kasusaaja muutus, ülevaatamist ootav kordussõelumine — neutraalsel kujul: järjenumber, tüüp, raskusaste, kuupäev. Vastused on alati piiratud 500 sündmusega.

Portfelli koondnäitajad

Loendurid, mitte kunagi toimik: mahud staatuse kaupa, viivitused, täielikkus. Sellest piisab armatuurlaua kuvamiseks teie tööriistas, ilma et sinna siseneks ainsatki kliendiandmet.

Kvalifitseerimine

Ainus kirjutamine: päevikusündmuse kvalifitseerimine (staatus qualifie või clos, otsustus planifie, traite või ecarte). See nõuab kirjutamisskoopi — vähima õiguse põhimõte on reegel, mitte valik.

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. lecture (lugemine, vaikimisi) ja ecriture (kirjutamine). 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.
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.

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.