Vigilae Connect

API, jonka voit lukea ennen kuin allekirjoitat.

Määrittely on julkinen, pinnat ovat neutraaleja, 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

Neutraalit pinnat, rakenteellisesti.

API tarjoaa sen, minkä integraattori voi käyttää koskematta aineistojen salassapitoon: seurantalokin ja laskurit. Valvonta-aineiston sisältö, asiakirjat ja epäilyttäviä liiketoimia koskevat ilmoitukset eivät kulje tämän API:n kautta — kyse ei ole pakettirajoituksesta vaan arkkitehtuurista.

Seurantaloki

Toimiston pKYC-tapahtumat — vanhentunut asiakirja, tosiasiallisen edunsaajan muutos, tarkistettava uudelleenseulonta — neutraalissa muodossa: järjestysnumero, tyyppi, vakavuus, päivämäärä. Vastaukset on aina rajattu 500 tapahtumaan.

Salkkukoosteet

Laskureita, ei koskaan aineistoa: volyymit tiloittain, viiveet, täydellisyysaste. Riittävästi kojelaudan piirtämiseen omaan työkaluusi ilman, että yksikään asiakastieto päätyy siihen.

Kvalifiointi

Ainoa kirjoitusoperaatio: lokitapahtuman kvalifiointi (tila qualifie tai clos, käsittelytapa planifie, traite tai ecarte). Se vaatii kirjoitus-scopen — vähimpien oikeuksien periaate on sääntö, ei valinta.

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. lecture (luku, oletus) ja ecriture (kirjoitus). 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.
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.

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ää.