Vigilae Connect

API, kurią galite perskaityti prieš pasirašydami.

Specifikacija vieša, sąsajos neutralios, webhook parašą galite patikrinti dešimčia eilučių savo pusėje. Šiame puslapyje dokumentuota tai, ką API pateikia šiandien — nieko daugiau, ir tai sąmoninga: kas nepateikta, tas nedokumentuota.

OpenAPI specifikacija skaitoma be rakto ir be paskyros
Niekada jokio pranešimo apie įtartiną sandorį, niekada pažodinio klientų turinio
Pasirašyti webhook'ai, patikrinami už „Vigilae“ ribų

Skaityti specifikaciją Klaidų žinynas

Ją pateikia pati API: kontraktas, kurį skaitote, yra tas, kuris veikia.

Perimetras

Neutralios sąsajos — pagal konstrukciją.

API pateikia tai, ką integratorius gali naudoti neliesdamas bylų paslapties: stebėsenos žurnalą ir skaitiklius. Budrumo bylos turinys, dokumentai, pranešimai apie įtartinus sandorius per šią API nekeliauja — tai ne plano apribojimas, o architektūra.

Stebėsenos žurnalas

Biuro pKYC įvykiai — pasibaigusio galiojimo dokumentas, tikrojo savininko pasikeitimas, peržiūrėtina pakartotinė patikra — neutralia forma: seka, tipas, svarba, data. Atsakymai visada apriboti iki 500 įvykių.

Portfelio suvestinės

Skaitikliai, niekada byla: apimtys pagal būseną, vėlavimai, užbaigtumas. Pakanka jūsų įrankyje atvaizduoti prietaisų skydelį taip, kad į jį nepatektų nė vienas kliento duomuo.

Kvalifikavimas

Vienintelis rašymo veiksmas: žurnalo įvykio kvalifikavimas (būsena qualifie arba clos, sprendimas planifie, traite arba ecarte). Jam reikia rašymo aprėpties — mažiausių privilegijų principas čia taisyklė, o ne parinktis.

API sukurta veikti tarp serverių: raktas kode, kuris pasiekia naršyklę, yra paskelbtas raktas. Raktą laikykite serverio pusės tarpiniame sluoksnyje, niekada puslapyje.

Raktai

Apribotos aprėpties raktai, rodomi vieną kartą, atšaukiami akimirksniu.

Formatas. Kiekvienas raktas prasideda vgk_ ir siunčiamas kaip Authorization: Bearer vgk_…. Paslaptis parodoma tik kuriant: mes saugome tik jos SHA-256 maišos reikšmę.
Aprėptys. lecture (skaitymas, numatytoji) ir ecriture (rašymas). Raktas be reikiamos aprėpties gauna 403 — žr. #scopes.
Galiojimas. Metai nuo sukūrimo (matoma biuro konsolėje). Pasibaigusio galiojimo raktas gauna aiškų 401 — žr. #cle-expiree.
Sparta. 60 užklausų per minutę vienam raktui (galima keisti kiekvienam raktui atskirai). 429 atsakymas neša Retry-After ir antraštes X-RateLimit-Limit / -Remaining / -Reset.
Atšaukimas. Akimirksniu, iš konsolės. Raktai atpažįstami pagal maišos reikšmę: jų neįmanoma išvardyti.

Greitas startas

Trys curl iškvietimai — ir pamatėte viską.

# Būsena + rakto autentifikavimas
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Stebėsenos žurnalas, nuo pradžios, puslapiais po 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalifikuoti 42 įvykį (rašymo aprėptis)
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"}'

Puslapiavimas viena taisykle

Perduokite depuisSeq (0 pirmame iškvietime) ir limite (ne daugiau kaip 500): atsakymas surikiuotas didėjančia seq tvarka ir grąžina prochainSeq, kurį kitame iškvietime perduodate nepakeistą. Puslapis, trumpesnis už limite, reiškia žurnalo pabaigą — prochainSeq tada lieka stabilus ir tarnauja kaip apklausos žymeklis. Be depuisSeq gaunate rodinį „naujausi pirmiausia“, apribotą iki 500.

Portfelis užklausiamas per /api/v1/portefeuille/agregats — skaitikliai, vienas atsakymas, jokio puslapiavimo.

Webhook'ai

Pasirašyti, pažymėti laiko žyma, pristatomi bent vieną kartą.

Užuot apklausinėję žurnalą, gaukite jį: „Vigilae“ pristato įvykius į jūsų URL, eilės tvarka, paketais ne didesniais kaip 100. Pristatymas yra at-least-once — žymeklis pasislenka tik gavus jūsų 2xx, paketas po paketo — o idempotencija remiasi seq: kiekvieną seką apdorokite lygiai vieną kartą (#idempotence).

Parašo tikrinimas

Kiekvienas pristatymas neša antraštę x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Perskaičiuokite v1 iš gauto neapdoroto kūno ir atmeskite bet kokią laiko žymą t, senesnę nei 5 min.: tai apsauga nuo pakartojimo. Paslapties rotacijos metu antraštėje yra po vieną v1 kiekvienai dar galiojančiai paslapčiai (24 val. persidengimas): priimkite, jei sutampa bent viena.

// Node — parašo tikrinimas (be priklausomybių)
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; // apsauga nuo pakartojimo
  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 — tas pats tikrinimas
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  # apsauga nuo pakartojimo
    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

Pereinamuoju laikotarpiu: senasis formatas sha256=HMAC(body) jau veikiantiems gavėjams vis dar siunčiamas antraštėje x-vigilae-signature-legacy; jį pašalinti numatyta kartu su webhook'ų v2. Nauji gavėjai tikrina aukščiau aprašytą schemą su laiko žyma, o ne senąją.

Rotacija paleidžiama iš konsolės (programos pusėje — POST /connect/webhook/rotation): 24 val. senoji paslaptis dar pasirašo — laiko užtenka įdiegti naująją jūsų pusėje be gedimų lango.

Testavimo aplinka

Smėlio dėžė: pagal užklausą.

Savitarnos smėlio dėžės kol kas nėra — verčiau pasakome tai čia, nei leidžiame jums tai atrasti patiems. Parašykite adresu contact@vigilae.org (tema „API prieiga“): jūsų integracijos laikotarpiui atveriame bandomąjį biurą su fiktyviais duomenimis ir liekame pasiekiami, kol darbas juda į priekį.

Kiekviena API klaidų klasė turi stabilų adresą klaidų žinyne: #authentification, #scopes, #cloisonnement, #debit, #signature… API klaidų atsakymai rodys būtent į šiuos inkarus.

API pagal konstrukciją nepateikia nei pranešimų apie įtartinus sandorius, nei pažodinio klientų turinio (Prancūzijos CMF L.561-18 str.). API nepriima jokio budrumo sprendimo: ji pateikia ir kvalifikuoja įvykius; sprendžia profesionalas.