Vigilae Connect

API koji možete pročitati prije potpisa.

Specifikacija je javna, površine su neutralne, potpis webhooka provjerava se u deset redaka na vašoj strani. Ova stranica dokumentira ono što API izlaže danas — ništa više, i to namjerno: što nije isporučeno, nije ni dokumentirano.

OpenAPI specifikacija čitljiva bez ključa i bez računa
Nikada prijava sumnjive transakcije, nikada doslovni sadržaj stranke
Potpisani webhookovi, provjerljivi izvan Vigilae

Pročitajte specifikaciju Referenca pogrešaka

Poslužuje je sam API: ugovor koji čitate onaj je koji se izvršava.

Doseg

Neutralne površine, po samoj izvedbi.

API izlaže ono što integrator može koristiti bez zadiranja u tajnost spisa: dnevnik praćenja i brojače. Sadržaj spisa dubinske analize, dokumenti i prijave sumnjivih transakcija ne prolaze kroz ovaj API — to nije ograničenje paketa, nego arhitektura.

Dnevnik praćenja

pKYC događaji ureda — istekli dokument, promjena stvarnog vlasnika, ponovna provjera za pregled — u neutralnom obliku: sekvenca, tip, ozbiljnost, datum. Odgovori su uvijek ograničeni na 500 događaja.

Agregati portfelja

Brojači, nikada spis: opsezi po statusu, kašnjenja, potpunost. Dovoljno da u svom alatu prikažete nadzornu ploču, a da u nju ne uđe nijedan podatak o stranci.

Kvalifikacija

Jedino pisanje: kvalificiranje događaja iz dnevnika (status qualifie ili clos, ishod planifie, traite ili ecarte). Zahtijeva opseg za pisanje — najmanja ovlast pravilo je, ne opcija.

API je zamišljen za komunikaciju poslužitelj – poslužitelj: ključ u kodu isporučenom pregledniku objavljeni je ključ. Neka ključ drži proxy na poslužiteljskoj strani, nikada stranica.

Ključevi

Ključevi s ograničenim opsegom, prikazani jednom, opozivi odmah.

Format. Svaki ključ počinje s vgk_ i šalje se kao Authorization: Bearer vgk_…. Tajna se prikazuje samo pri stvaranju: čuvamo isključivo njezin SHA-256 sažetak.
Opsezi. lecture (čitanje, zadano) i ecriture (pisanje). Ključ bez potrebnog opsega dobiva 403 — vidi #scopes.
Istek. Godinu dana nakon stvaranja (vidljivo u konzoli ureda). Istekli ključ dobiva izričit 401 — vidi #cle-expiree.
Ograničenje. 60 zahtjeva/minuti po ključu (podesivo po ključu). Odgovor 429 nosi Retry-After i zaglavlja X-RateLimit-Limit / -Remaining / -Reset.
Opoziv. Trenutačan, iz konzole. Razrješavanje ide preko sažetka: ključevi se ne mogu nabrajati.

Brzi početak

Tri curl poziva i vidjeli ste sve.

# Zdravlje + autentifikacija ključa
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Dnevnik praćenja, od početka, u stranicama od 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Kvalificiraj događaj 42 (opseg za pisanje)
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"}'

Straničenje, u jednom pravilu

Proslijedite depuisSeq (0 pri prvom pozivu) i limite (najviše 500): odgovor je sortiran po rastućem seq i vraća prochainSeq, koji pri sljedećem pozivu proslijedite nepromijenjen. Stranica kraća od limite znači kraj dnevnika — prochainSeq tada ostaje stabilan i služi kao kursor za periodično dohvaćanje. Bez depuisSeq dobivate prikaz „najnovije prvo”, ograničen na 500.

Portfelj se dohvaća na /api/v1/portefeuille/agregats — brojači, jedan odgovor, bez straničenja.

Webhookovi

Potpisani, vremenski označeni, isporučeni barem jednom.

Umjesto da dnevnik stalno prozivate, primajte ga: Vigilae isporučuje događaje na vaš URL, redom, u serijama od najviše 100. Isporuka je at-least-once — kursor napreduje samo na vaš 2xx, seriju po seriju — a idempotentnost ide po seq: svaku sekvencu obradite točno jednom (#idempotence).

Provjera potpisa

Svaka isporuka nosi zaglavlje x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Ponovno izračunajte v1 iz sirovog primljenog tijela i odbacite svaku vremensku oznaku t stariju od 5 min: to je zaštita od ponavljanja. Tijekom rotacije tajne zaglavlje nosi po jedan v1 za svaku još valjanu tajnu (preklapanje 24 h): prihvatite ako se bilo koji podudara.

// Node — provjera potpisa (bez ovisnosti)
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 — ista provjera
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

Prijelazno: stari format sha256=HMAC(body) i dalje se emitira na x-vigilae-signature-legacy za već postavljene prijamnike; uklanjanje je planirano s webhookovima v2. Novi prijamnici provjeravaju gornju shemu s vremenskom oznakom, ne staru.

Rotacija se pokreće iz konzole (POST /connect/webhook/rotation na aplikacijskoj strani): stara tajna potpisuje još 24 h — dovoljno da na svojoj strani postavite novu bez prozora ispada.

Testno okruženje

Sandbox: na zahtjev.

Samoposlužni sandbox još ne postoji — radije vam to kažemo ovdje nego da to sami otkrijete. Pišite na contact@vigilae.org (predmet „API pristup”): otvaramo probni ured s izmišljenim podacima za vrijeme trajanja vaše integracije i ostajemo dostupni dok ona napreduje.

Svaka klasa API pogrešaka ima stabilnu adresu u referenci pogrešaka: #authentification, #scopes, #cloisonnement, #debit, #signature… Odgovori API-ja s pogreškom upućivat će na ta sidra.

API ne izlaže ni prijave sumnjivih transakcija ni doslovne sadržaje stranaka, po samoj arhitekturi (čl. L.561-18 francuskog CMF-a). API ne donosi nijednu odluku dubinske analize: on izlaže i kvalificira događaje; profesionalac odlučuje.