Vigilae Connect

API, ko var izlasīt pirms parakstīšanas.

Specifikācija ir publiska, virsmas ir neitrālas, webhook parakstu jūsu pusē var pārbaudīt desmit rindās. Šī lapa dokumentē to, ko API atklāj šodien — neko vairāk, un tas ir apzināti: kas nav piegādāts, tas netiek dokumentēts.

OpenAPI specifikācija lasāma bez atslēgas un bez konta
Nekad neviens aizdomīga darījuma ziņojums, nekad klienta saturs vārds vārdā
Parakstīti webhooki, pārbaudāmi ārpus Vigilae

Lasīt specifikāciju Kļūdu uzziņa

To pasniedz pats API: līgums, ko lasāt, ir tas, kas darbojas.

Perimetrs

Neitrālas virsmas — pēc uzbūves.

API atklāj to, ko integrētājs var patērēt, neskarot lietu noslēpumu: uzraudzības žurnālu un skaitītājus. Uzraudzības lietas saturs, dokumenti, aizdomīgu darījumu ziņojumi caur šo API neplūst — tas nav plāna ierobežojums, tā ir arhitektūra.

Uzraudzības žurnāls

Biroja pKYC notikumi — dokuments ar beigušos termiņu, patiesā labuma guvēja maiņa, izskatāma atkārtota pārbaude — neitrālā formā: secība, tips, smaguma pakāpe, datums. Atbildes vienmēr ierobežotas līdz 500 notikumiem.

Portfeļa agregāti

Skaitītāji, nekad lieta: apjomi pa statusiem, kavējumi, pilnīgums. Pietiek, lai jūsu rīkā attēlotu infopaneli, tajā neienākot ne vienam vienīgam klienta datam.

Kvalificēšana

Vienīgā rakstīšanas darbība: žurnāla notikuma kvalificēšana (statuss qualifie vai clos, risinājums planifie, traite vai ecarte). Tai vajadzīgs rakstīšanas tvērums — mazāko privilēģiju princips ir noteikums, nevis izvēles iespēja.

API ir veidots darbam serveris–serveris: atslēga kodā, kas tiek piegādāts pārlūkam, ir publicēta atslēga. Lai atslēgu tur servera puses starpnieks, nekad — lapa.

Atslēgas

Atslēgas ar ierobežotu tvērumu, parādītas vienreiz, atsaucamas nekavējoties.

Formāts. Katra atslēga sākas ar vgk_ un tiek sūtīta kā Authorization: Bearer vgk_…. Noslēpums tiek parādīts tikai izveides brīdī: mēs glabājam vienīgi tā SHA-256 nospiedumu.
Tvērumi. lecture (lasīšana, noklusējums) un ecriture (rakstīšana). Atslēga bez vajadzīgā tvēruma saņem 403 — sk. #scopes.
Derīguma termiņš. Viens gads pēc izveides (redzams biroja konsolē). Atslēga ar beigušos termiņu saņem nepārprotamu 401 — sk. #cle-expiree.
Limits. 60 pieprasījumi minūtē uz atslēgu (pielāgojams katrai atslēgai). 429 atbilde nes Retry-After un galvenes X-RateLimit-Limit / -Remaining / -Reset.
Atsaukšana. Tūlītēja, no konsoles. Atpazīšana notiek pēc nospieduma: atslēgas nevar uzskaitīt.

Ātrā uzsākšana

Trīs curl izsaukumi — un jūs esat redzējuši visu.

# Veselības pārbaude + atslēgas autentifikācija
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Uzraudzības žurnāls no sākuma, pa 100 lapā
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificēt notikumu 42 (rakstīšanas tvērums)
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"}'

Lapošana vienā noteikumā

Nododiet depuisSeq (0 pirmajā izsaukumā) un limite (ne vairāk kā 500): atbilde ir kārtota pēc augoša seq un atgriež prochainSeq, ko nākamajā izsaukumā nodod tālāk nemainītu. Lapa, kas īsāka par limite, nozīmē žurnāla beigas — prochainSeq tad paliek stabils un kalpo kā aptaujas kursors. Bez depuisSeq jūs saņemat skatu „jaunākie vispirms”, ierobežotu līdz 500.

Portfeli vaicā ar /api/v1/portefeuille/agregats — skaitītāji, viena atbilde, bez lapošanas.

Webhooki

Parakstīti, ar laikspiedolu, piegādāti vismaz vienreiz.

Tā vietā, lai žurnālu aptaujātu, saņemiet to: Vigilae piegādā notikumus uz jūsu URL, secībā, partijās pa ne vairāk kā 100. Piegāde ir at-least-once — kursors virzās uz priekšu tikai pēc jūsu 2xx, partiju pa partijai — un idempotence ir pēc seq: apstrādājiet katru secību tieši vienu reizi (#idempotence).

Paraksta pārbaude

Katra piegāde nes galveni x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Pārrēķiniet v1 no saņemtā neapstrādātā ķermeņa un noraidiet jebkuru laikspiedolu t, kas vecāks par 5 min: tā ir aizsardzība pret atkārtošanu. Noslēpuma rotācijas laikā galvene nes vienu v1 katram vēl derīgajam noslēpumam (24 h pārklāšanās): pieņemiet, ja sakrīt jebkurš no tiem.

// Node — paraksta pārbaude (bez atkarībām)
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 — tā pati pārbaude
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

Pārejas posmā: vecais formāts sha256=HMAC(body) jau esošajiem saņēmējiem joprojām tiek izsūtīts galvenē x-vigilae-signature-legacy; tā izņemšana ir plānota kopā ar webhooks v2. Jauni saņēmēji pārbauda augstāk aprakstīto laikspiedola shēmu, nevis veco.

Rotāciju iedarbina no konsoles (lietojumprogrammas pusē POST /connect/webhook/rotation): 24 h vecais noslēpums vēl paraksta — laiks izvietot jauno jūsu pusē bez atteices loga.

Testa vide

Smilškaste: pēc pieprasījuma.

Pašapkalpošanās smilškastes vēl nav — mēs to labāk pasakām šeit, nekā ļaujam jums to atklāt pašiem. Rakstiet uz contact@vigilae.org (temats „API piekļuve”): mēs atveram izmēģinājuma biroju ar fiktīviem datiem uz visu jūsu integrācijas laiku un paliekam sasniedzami, kamēr tā virzās uz priekšu.

Katrai API kļūdu klasei ir stabila adrese kļūdu uzziņā: #authentification, #scopes, #cloisonnement, #debit, #signature… API kļūdu atbildes norādīs uz šiem enkuriem.

API pēc uzbūves neatklāj ne aizdomīgu darījumu ziņojumus, ne klientu saturu vārds vārdā (Francijas CMF L.561-18. pants). API nepieņem nevienu uzraudzības lēmumu: tas atklāj un kvalificē notikumus; lemj profesionālis.