Vigilae Connect

API, jonka voit lukea ennen kuin allekirjoitat.

Määrittely on julkinen, webhook-allekirjoituksen voi todentaa kymmenellä rivillä omalla puolellasi. Tämä sivu dokumentoi sen, minkä API tarjoaa tänään — ei enempää, ja se on tarkoituksellista: mitä ei ole toimitettu, sitä ei ole dokumentoitu.

OpenAPI-määrittely luettavissa ilman avainta tai tiliä
Ei koskaan epäilyttävää liiketoimea koskevaa ilmoitusta, ei koskaan asiakkaan sanatarkkaa sisältöä
Allekirjoitetut webhookit, todennettavissa Vigilaen ulkopuolella

Lue määrittely Virheviitteistö

API itse tarjoilee sen: sopimus, jonka luet, on sama joka ajetaan.

Rajaus

Koko kulku alusta loppuun — ja kaksi poissulkemista, jotka pysyvät.

Ohjelmistosi voi hoitaa aineiston alusta loppuun: luoda asiakkaan, avata aineiston, tallentaa asiakirjat, käynnistää seulonnan, ilmoittaa tosiasialliset edunsaajat, lukea riskiluokituksen ja noutaa todisteasiakirjan. Kaksi asiaa ei kulje koskaan sitä kautta, eikä kyse ole tilauksen rajoituksesta: ei yhtään epäilyttävää liiketointa koskevaa ilmoitusta eikä asiakkaasi sanatarkkaa sisältöä. Ensimmäinen on toimi, jonka laki varaa ilmoituksen tekijälle; jälkimmäisellä ei ole mitään tekemistä integraatioputkessa.

Aineisto alusta loppuun

Asiakkaat, aineistot, todentavat asiakirjat, seulonta, tosiasialliset edunsaajat, riskiluokitus, todisteasiakirja, eheystarkistus. Jokaisella resurssilla on oma scopensa: avaimesi avaa vain sen, minkä olet sille antanut.

Seurantaloki ja koosteet

Toimiston pKYC-tapahtumat — vanhentunut asiakirja, tosiasiallisen edunsaajan muutos, käsiteltävä uudelleenseulonta — ja salkkulaskurit kojelautaasi varten. Vastaus on aina rajattu, kursori vakaa.

Kirjoituksellasi on aina nimi

Tallennus, seulonta, kvalifiointi: jokainen kirjoitus vaatii oman scopensa ja kirjaa tekijän. Nimetön kvalifiointi hylätään — integraatio kirjaa ihmisen päätöksen, se ei tee päätöksiä itse.

API on suunniteltu palvelinten väliseksi: selaimeen toimitetussa koodissa oleva avain on julkaistu avain. Anna avain palvelinpuolen välityspalvelimen haltuun, ei koskaan sivun.

Avaimet

Rajatut avaimet, näytetään kerran, peruttavissa heti.

Muoto. Jokainen avain alkaa etuliitteellä vgk_ ja lähetetään muodossa Authorization: Bearer vgk_…. Salaisuus näytetään vain luontihetkellä: säilytämme siitä ainoastaan SHA-256-tiivisteen.
Scopet. Avain kantaa vain ne scopet, jotka valittiin sen luonnissa: yleiset lecture (luku, oletus) ja ecriture (kirjoitus) tai hienojakoiset, resurssi kerrallaan — clients:, dossiers:, pieces:, criblage: (joko lecture tai ecriture), origine-fonds:lecture, journal:lecture.
Periytyminen seuraa päätettä ja kulkee vain yhteen suuntaan: lecture kattaa jokaisen *:lecture-scopen, ecriture jokaisen *:ecriture-scopen; hienojakoinen scope ei avaa mitään itsensä ulkopuolelta.
Kuusi scopea jää tämän parin ulkopuolelle eikä siksi periydy mistään yleisestä avaimesta: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kukin delegoidaan erikseen, avainta luotaessa.
Avain ilman vaadittua scopea saa 403-vastauksen — katso #scopes.
Vanheneminen. Vuosi luonnista (näkyy toimiston konsolissa). Vanhentunut avain saa yksiselitteisen 401-vastauksen — katso #cle-expiree.
Avainta voidaan lakata hyväksymästä myös ennen tätä päivämäärää, kun API ei enää kuulu toimiston tilaukseen. Pysäytys tapahtuu silloin vähintään 30 päivää ensimmäisen toimistolle lähetetyn sähköpostin jälkeen, päivänä, jonka toinen, vähintään 7 päivää etukäteen lähetetty sähköposti ilmoittaa. Kun päivämäärä on asetettu, se näkyy toimiston konsolissa (GET /connect/cles -kenttä coupure_le), ja jokainen hyväksyttyyn kutsuun annettu vastaus ilmoittaa sen Sunset-otsakkeessa, kunnes se koittaa. Sen jälkeen kutsu saa kohdassa #authentification kuvatun 401:n, kentällä "motif": "fin_option_api"; jos API palaa tilaukseen, avain hyväksytään taas, oman voimassaolonsa päättymiseen asti.
Peruttu avain ei palaa API:n mukana. Ja kun koko tilaus keskeytetään tai se päättyy, avaimia lakataan hyväksymästä heti, ilman tätä määräaikaa.
Kutsuraja. 60 pyyntöä minuutissa avainta kohti (yliajettavissa avainkohtaisesti). 429-vastaus kantaa Retry-After-otsakkeen sekä otsakkeet X-RateLimit-Limit / -Remaining / -Reset.
Peruminen. Välitön, konsolista. Avain tunnistetaan tiivisteen perusteella: avaimia ei voi luetella.

Pika-aloitus

Kolme curl-kutsua, ja olet nähnyt kaiken.

# Kunto + avaimen todennus
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_avaimesi"

# Seurantaloki alusta alkaen, 100 tapahtuman sivuina
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_avaimesi"

# Kvalifioi tapahtuma 42 (kirjoitus-scope)
curl -s -X POST https://vigilae.org/api/v1/evenements/42/qualifier \
  -H "Authorization: Bearer vgk_avaimesi" \
  -H "Content-Type: application/json" \
  -d '{"statut":"qualifie","disposition":"traite"}'

Sivutus yhdellä säännöllä

Anna depuisSeq (ensimmäisellä kutsulla 0) ja limite (enintään 500): vastaus on lajiteltu nousevan seq-arvon mukaan ja palauttaa prochainSeq-arvon, joka annetaan sellaisenaan seuraavalla kutsulla. limite-arvoa lyhyempi sivu tarkoittaa lokin loppua — prochainSeq pysyy silloin vakaana ja toimii pollauskursorina. Ilman depuisSeq-parametria saat ”uusimmat ensin” -näkymän, rajattuna 500 tapahtumaan.

Salkkua kysytään osoitteesta /api/v1/portefeuille/agregats — laskureita, yksi vastaus, ei sivutusta.

Webhookit

Allekirjoitettu, aikaleimattu, toimitettu vähintään kerran.

Lokin pollaamisen sijaan voit vastaanottaa sen: Vigilae toimittaa tapahtumat URL-osoitteeseesi järjestyksessä, enintään 100 tapahtuman erissä. Toimitus on at-least-once — kursori etenee vain 2xx-vastauksestasi, erä kerrallaan — ja idempotenssi perustuu seq-arvoon: käsittele jokainen järjestysnumero täsmälleen kerran (#idempotence).

Allekirjoituksen todentaminen

Jokainen toimitus kantaa otsakkeen x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Laske v1 uudelleen vastaanotetusta raa'asta rungosta ja hylkää jokainen yli 5 min vanha aikaleima t: se on toistohyökkäyssuoja. Salaisuuden kierrätyksen aikana otsake kantaa yhden v1-arvon kutakin yhä voimassa olevaa salaisuutta kohti (24 h limitys): hyväksy, jos yksikin täsmää.

// Node — allekirjoituksen todennus (ei riippuvuuksia)
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; // toistohyökkäyssuoja
  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 todennus
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  # toistohyökkäyssuoja
    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

Siirtymävaihe: vanha sha256=HMAC(body)-muoto lähetetään yhä otsakkeessa x-vigilae-signature-legacy jo käytössä oleville vastaanottimille; sen poisto on suunniteltu webhookien v2:n yhteyteen. Uudet vastaanottimet todentavat yllä olevan aikaleimatun mallin, eivät vanhaa.

Kierrätys käynnistetään konsolista (POST /connect/webhook/rotation sovelluksen puolella): 24 h ajan vanha salaisuus allekirjoittaa yhä — aikaa ottaa uusi käyttöön omalla puolellasi ilman katkoikkunaa.

Upotetut widgetit

Valvonnan tila, näytöissäsi.

Ohjelmistosi luo jo aineistot API:n kautta; widgetit antavat sille puuttuneen pinnan: aineiston valvontatilan näyttämisen asiakastiedoissasi, ilman että rakennat omaa vaatimustenmukaisuuskäyttöliittymää. Kulku etenee kolmessa vaiheessa — palvelimesi myöntää lyhytikäisen tunnisteen, palautettu URL-osoite asetetaan iframeen, widget näyttää. Se ei tee muuta kuin näyttää: ei päätöstä, ei luokittelua, ei koskaan kirjoitusta widgetin kautta. Klikkaus avaa Vigilae-sovelluksen, jossa tunnistettu ihminen toimii.

1. Myönnä tunniste — palvelinpuolella, ei koskaan sivulla

Avain vgk_ ei koskaan kosketa selainta. Palvelimesi kutsuu myöntöä erillisellä embed:emettre-scopella (rastitaan avaimen luonnissa, ei koskaan periydy), ja sivulle kulkeutuu vain lyhyt tunniste: viisitoista minuuttia oletuksena, rajattuna 5–60 minuuttiin, sidottuna yhteen aineistoon, yhteen komponenttiin, yhteen ilmoitettuun alkuperään. Se kulkee URL-osoitteen fragmentissa — se ei tavoita meidän lokejamme eikä sinun lokejasi.

# Tunniste Compliance Buttonille, nimike valittu luettelosta
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. Sijoita iframe — käynnistin, kymmenessä rivissä

vigilae-embed.js-käynnistin luo hiekkalaatikoidun iframen, hoitaa kättelyn ja seuraa widgetin kokoa (rajattuna — iframe ei koskaan sanele korkeuttaan sivullesi). CSP:n osalta sivusi avaa vain yhden direktiivin: frame-src https://vigilae.org. Inline-skriptejä ei vaadita, ei riippuvuuksia. Käsin kirjoitettu iframe toimii yhtä hyvin.

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

// Skriptissäsi: url tulee OMALTA palvelimeltasi, joka kutsui tunnisteen myöntöä
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // vanhenemisen jälkeen: myönnä uusi tunniste palvelinpuolella
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// widget.rafraichir(token) työntää tuoreen tunnisteen; widget.demonter() poistaa kaiken.

3. Compliance Button: nimike sinulta, tila meiltä

Painikkeen nimike valitaan suljetusta luettelosta — ei koskaan vapaata tekstiä valvonnasta kertovalla pinnalla — shell näyttää nimikkeet vain ranskaksi tai englanniksi (parametri ?lang=), ei vielä omalla kielelläsi; alla oleva luettelo kertoo niiden merkityksen:

controler_client — ”Tarkista tämä asiakas” (oletus)
lancer_vigilance — ”Aloita valvonta”
verifier_be — ”Tarkista tosiasialliset edunsaajat”
preparer_dossier — ”Valmistele rahanpesunvastainen aineisto”

Tilapallo sen sijaan näyttää Vigilaen laskeman tilan: a_jour (vihreä — seulonta ja luokitus ajan tasalla), a_revoir (keltainen — seulonta tai luokitus vanhentunut, tai lähde epäonnistui viimeisimmällä ajolla), alerte (punainen — vähintään yksi hälytys tarkistettavana), inconnu (harmaa — aineistoa ei ole koskaan seulottu). Nimike on muokattavissa, merkitys ei koskaan: väri on sidottu tilaan itse shellin sisällä, joka ohittaa jokaisen yrityksen ylikirjoittaa sen postMessagella. Hälytystilassa oleva aineisto näyttää hälytyksen, oli ulkoasu mikä tahansa.

postMessage-sopimus kokonaisuudessaan

Widget lähettää tapahtumat vigilae:pret, vigilae:taille (automaattinen koon mukautus), vigilae:expire (myönnä uusi tunniste palvelinpuolella, posta sitten vigilae:jeton) ja vigilae:ouvrir. Ei koskaan nimeä, riskiä tai hälytystä viestin sisällä: ohjelmistollasi on jo kaikki server-to-server-API:n kautta, eikä tästä kanavasta tule toista sellaista.

Alkuperien ilmoittaminen: toimiston pääkäyttäjä. Upotetun widgetin tunniste on sidottu toimiston ilmoittamaan alkuperään — se ohjaa shellin frame-ancestors-CSP:tä. Pääkäyttäjä ilmoittaa sen suoraan Vigilaessa, näytöllä ”Integraatiot ja tietoturva”: enintään kymmenen https://-alkuperää, isäntänimi kokonaisuudessaan, ei koskaan jokerimerkkiä; komponentit, jotka hän ottaa käyttöön; sekä kaikkien tunnisteiden kumoaminen, joka tappaa yhdellä eleellä jokaisen jo myönnetyn tunnisteen. http://localhost sallitaan vain hiekkalaatikkotoimistossa — kirjoita osoitteeseen contact@vigilae.org (aiheena ”Embedded widgets”) saadaksesi sellaisen avattua integraatiosi ajaksi. Jos alkuperää ei ole ilmoitettu: myöntö kieltäytyy 400-vastauksella. Instanssi, jonka alkuperien tallennus ei ole kytketty: yksiselitteinen 501 — katso #embed-indisponible.

Testiympäristö

Hiekkalaatikko: pyynnöstä.

Itsepalveluhiekkalaatikkoa ei vielä ole — kerromme sen mieluummin tässä kuin annamme sinun huomata sen itse. Kirjoita osoitteeseen contact@vigilae.org (aiheena ”API-pääsy”): avaamme kokeilutoimiston kuvitteellisilla tiedoilla integraatiosi ajaksi ja pysymme tavoitettavissa sen edetessä.

Jokaisella API:n virheluokalla on pysyvä osoite virheviitteistössä: #authentification, #scopes, #cloisonnement, #debit, #signature… API:n virhevastaukset osoittavat näihin ankkureihin.

API ei tarjoa epäilyttäviä liiketoimia koskevia ilmoituksia eikä asiakkaan sanatarkkaa sisältöä, jo rakenteensa vuoksi (art. L.561-18, Ranskan CMF). API ei tee yhtäkään valvontapäätöstä: se tarjoaa ja kvalifioi tapahtumia; ammattilainen päättää.