Vigilae Connect

API koji možete pročitati prije potpisa.

Specifikacija je javna, 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

Cijeli postupak i dva izuzeća koja se neće mijenjati.

Vaš softver može voditi spis od početka do kraja: kreirati stranku, otvoriti spis, predati dokumente, pokrenuti provjeru prema popisima, navesti stvarne vlasnike, očitati ocjenu rizika i preuzeti dokazni spis. Dvije stvari nikada neće proći tim putem, a nije riječ o ograničenju pretplate: nijedna prijava sumnjive transakcije i nijedna doslovna izjava vaše stranke. Prvo je radnja koju zakon zadržava za osobu koja prijavljuje; drugo nema što tražiti u integracijskom kanalu.

Spis od početka do kraja

Stranke, spisi, popratni dokumenti, provjera prema popisima, stvarni vlasnici, ocjena rizika, dokazni spis, provjera cjelovitosti. Svaki resurs ima svoj opseg: vaš ključ otvara samo ono što ste mu dali.

Dnevnik i zbirni pokazatelji

pKYC događaji ureda — istekao dokument, promjena stvarnog vlasnika, ponovna provjera koju treba obraditi — i brojači portfelja za vašu nadzornu ploču. Odgovor je uvijek ograničen, kursor stabilan.

Svaki upis ima ime

Predati, provjeriti, kvalificirati: svaki upis traži svoj opseg i bilježi operatera. Anonimna kvalifikacija se odbija — integracija bilježi ljudsku odluku, a sama je ne donosi.

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. Ključ nosi samo opsege označene pri njegovu stvaranju: opće lecture (čitanje, zadano) i ecriture (pisanje) ili fine opsege, resurs po resurs — clients:, dossiers:, pieces:, criblage: (u lecture ili ecriture), origine-fonds:lecture, journal:lecture.
Nasljeđivanje ide po sufiksu i samo u jednom smjeru: lecture pokriva svaki *:lecture, ecriture svaki *:ecriture; fini opseg ne otvara ništa izvan sebe.
Šest opsega izlazi iz tog para i stoga se ne nasljeđuje ni iz jednog općeg ključa: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Svaki se delegira zasebno, pri stvaranju ključa.
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.
Ključ se može prestati prihvaćati i prije tog datuma, kad API više nije dio pretplate ureda. Zaustavljanje tada nastupa najmanje 30 dana nakon prve e-poruke uredu, na datum koji navodi druga e-poruka, poslana najmanje 7 dana unaprijed. Čim se odredi, taj je datum vidljiv u konzoli ureda (polje coupure_le u GET /connect/cles), a svaki ga odgovor na prihvaćeni poziv najavljuje u zaglavlju Sunset dok ne nastupi. Nakon tog datuma poziv dobiva 401 opisan u #authentification, s "motif": "fin_option_api"; ako se API vrati u pretplatu, ključ se ponovno prihvaća, do isteka vlastitog roka valjanosti.
Opozvani ključ ne vraća se s API-jem. A kad se cijela pretplata suspendira ili završi, ključevi se odmah prestaju prihvaćati, bez tog roka.
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.

Ugrađeni widgeti

Stanje praćenja, u vašim zaslonima.

Vaš softver već stvara spise putem API-ja; widgeti mu daju površinu koja je nedostajala: prikaz stanja praćenja spisa u vašoj kartici klijenta, bez ponovne izgradnje sučelja za usklađenost. Tijek ima tri koraka — vaš poslužitelj izdaje kratkotrajni token, vraćeni URL smješta se u iframe, widget prikazuje. On samo prikazuje: nijedna odluka, nijedna kvalifikacija, nijedno pisanje nikada ne prolazi kroz widget. Klikom se otvara aplikacija Vigilae, gdje djeluje identificirana osoba.

1. Izdavanje tokena — na poslužiteljskoj strani, nikada u stranici

Ključ vgk_ nikada ne dodiruje preglednik. Vaš poslužitelj poziva mint s namjenskim opsegom embed:emettre (označenim pri stvaranju ključa, nikada naslijeđenim) i samo kratki token silazi do stranice: petnaest minuta prema zadanim postavkama, ograničeno na 5-60, vezano uz jedan spis, jednu komponentu, jedan deklarirani izvor. Putuje u fragmentu URL-a — ne dopire ni do naših dnevnika, ni do vaših.

# Token za Compliance Button, oznaka odabrana iz kataloga
curl -s -X POST https://vigilae.org/api/v1/embed/jetons \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"dossier_id":"D123","composant":"bouton",
       "audience":"https://your-software.example","libelle":"controler_client"}'

# 201 -> { "jeton": "…", "expire_le": "…",
#          "url": "https://vigilae.org/embarque/bouton?c=…#…" }

2. Postavljanje iframea — pokretač, u deset redaka

Pokretač vigilae-embed.js stvara sandboxirani iframe, obavlja handshake i prati veličinu widgeta (ograničenu — iframe nikada ne diktira svoju visinu vašoj stranici). Što se tiče CSP-a, vaša stranica otvara samo jednu direktivu: frame-src https://vigilae.org. Nije potreban nikakav inline skript, nikakva ovisnost. Ručno napisan iframe funkcionira jednako dobro.

<script src="https://vigilae.org/embarque/vigilae-embed.js" defer></script>
<div id="vigilance"></div>

// U vašoj skripti: url dolazi s VAŠEG poslužitelja, koji je pozvao mint
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // pri isteku: ponovno izdajte token na poslužiteljskoj strani
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) šalje svjež token; widget.demonter() uklanja sve.

3. Compliance Button: vaša oznaka, naše stanje

Oznaka gumba bira se iz zatvorenog kataloga — nikad slobodan tekst na površini koja govori o praćenju — shell te oznake prikazuje na francuskom ili engleskom (parametar ?lang=), još ne na vašem jeziku; popis niže objašnjava njihovo značenje:

controler_client — „Provjeri ovog klijenta” (zadano)
lancer_vigilance — „Pokreni dubinsku analizu”
verifier_be — „Provjeri stvarne vlasnike”
preparer_dossier — „Pripremi SPNFT spis”

Statusna točkica, međutim, prikazuje stanje koje izračunava Vigilae: a_jour (zeleno — provjera i ocjena ažurne), a_revoir (žuto — provjera ili ocjena zastarjele, ili je izvor otkazao u posljednjem prolazu), alerte (crveno — barem jedno upozorenje za obradu), inconnu (sivo — spis nikada nije provjeren). Oznaka se konfigurira, semantika nikad: boja je vezana uz stanje unutar samog shella, koji ignorira svaki pokušaj njezina nadjačavanja putem postMessagea. Spis u statusu upozorenja prikazuje upozorenje, bez obzira na stiliziranje.

Ugovor postMessage, u cijelosti

Widget emitira vigilae:pret, vigilae:taille (automatsko prilagođavanje veličine), vigilae:expire (ponovno izdajte token na poslužiteljskoj strani, zatim pošaljite vigilae:jeton) i vigilae:ouvrir. Nikada ime, rizik ili upozorenje unutar poruke: vaš softver već ima sve putem API-ja poslužitelj-poslužitelj, i ovaj kanal neće postati drugi takav kanal.

Deklaracija izvora: administrator vašeg ureda. Token za embed vezan je uz deklarirani izvor vašeg ureda — taj izvor pokreće CSP direktivu frame-ancestors shella. Administrator ga deklarira izravno u Vigilae, na zaslonu „Integracije i sigurnost”: najviše deset izvora https://, izričito naveden host, bez zamjenskih znakova; komponente koje aktivira; i masovni opoziv koji jednim potezom poništava sve već izdane tokene. http://localhost dopušten je samo na probnom uredu — pišite na contact@vigilae.org (predmet „Ugrađeni widgeti”) da se jedan otvori za trajanje vaše integracije. Nijedan izvor nije deklariran: mint odbija sa 400. Instanca čije spremište izvora nije povezano: izričit 501 — vidi #embed-indisponible.

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.