Vigilae Connect

API is féidir leat a léamh sula síníonn tú.

Tá an tsonraíocht poiblí, agus is féidir síniú an webhook a fhíorú i ndeich líne ar do thaobh féin. Déanann an leathanach seo doiciméadú ar a nochtann an API inniu — sin uile, agus d'aon ghnó atá sé amhlaidh: an rud nach bhfuil seolta, níl sé doiciméadaithe.

Sonraíocht OpenAPI inléite gan eochair ná cuntas
Gan tuairisc ar idirbheart amhrasach riamh, gan athfhriotal cliaint riamh
Webhookanna sínithe, infhíoraithe lasmuigh de Vigilae

Léigh an tsonraíocht Tagairt earráidí

Arna sheirbheáil ag an API féin: an conradh a léann tú, sin an ceann a ritheann.

An raon feidhme

An próiseas iomlán, agus dhá eisiamh nach n-athróidh.

Is féidir le do bhogearraí comhad a stiúradh ó thús deireadh: an cliant a chruthú, an comhad a oscailt, na doiciméid a chur isteach, an scagadh a chur ar siúl, na húinéirí tairbhiúla a dhearbhú, an rátáil riosca a léamh agus an comhad cruthúnais a tharraingt anuas. Tá dhá rud nach rachaidh tríd sin riamh, agus ní teorainn shíntiúis é: tuairisc ar idirbheart amhrasach, agus athfhriotal focal ar fhocal ó do chliant. Gníomh is ea an chéad cheann a fhágann an dlí faoin duine a dhéanann an tuairisc; agus an dara ceann, níl aon ghnó aige i bpíblíne chomhtháthaithe.

An comhad, ó thús deireadh

Cliaint, comhaid, doiciméid tacaíochta, scagadh, úinéirí tairbhiúla, rátáil riosca, comhad cruthúnais, seiceáil sláine. Tá a scóip féin ag gach acmhainn: ní osclaíonn d'eochair ach an méid a thug tú di.

Logleabhar agus comhiomláin

Imeachtaí pKYC an ghnólachta — doiciméad as feidhm, athrú úinéara thairbhiúil, athscagadh le déanamh — agus áiritheoirí punainne do do phainéal stiúrtha. Bíonn teorainn i gcónaí leis an bhfreagra, agus bíonn an cúrsóir seasmhach.

Tá ainm le gach rud a scríobhann tú

Doiciméad a chur isteach, scagadh a dhéanamh, imeacht a cháiliú: éilíonn gach scríobh a scóip féin agus taifeadann sé an t-oibreoir. Diúltaítear do cháiliú gan ainm — coinníonn an comhtháthú taifead ar chinneadh daonna, ní dhéanann sé cinneadh ar bith é féin.

Freastalaí-go-freastalaí a dearadh an API: eochair i gcód a sheoltar chuig an mbrabhsálaí, is eochair fhoilsithe í. Cuir an eochair i seilbh seachfhreastalaí ar thaobh an fhreastalaí, ní sa leathanach go deo.

Eochracha

Eochracha scóipthe, a thaispeántar uair amháin, in-chúlghairthe láithreach.

Formáid. Tosaíonn gach eochair le vgk_ agus seoltar í mar Authorization: Bearer vgk_…. Ní thaispeántar an rún ach tráth a chruthaithe: ní choinnímid ach a achoimre SHA-256.
Scóipeanna. Ní iompraíonn eochair ach na scóipeanna a ticeáladh nuair a cruthaíodh í: na cinn ghinearálta lecture (léamh, an réamhshocrú) agus ecriture (scríobh), nó scóipeanna mionsonraithe, acmhainn ar acmhainn — clients:, dossiers:, pieces:, criblage: (i lecture nó ecriture), origine-fonds:lecture, journal:lecture.
Leanann an oidhreacht an iarmhír, agus ní théann sí ach i dtreo amháin: clúdaíonn lecture gach *:lecture, agus ecriture gach *:ecriture; ní osclaíonn scóip mhionsonraithe aon rud lasmuigh di féin.
Titeann sé scóip lasmuigh den phéire sin agus ní thagann siad le hoidhreacht ó aon eochair ghinearálta: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Tarmligtear ceann ar cheann iad, nuair a chruthaítear an eochair.
Faigheann eochair gan an scóip riachtanach 403 — féach #scopes.
Éag. Bliain amháin tar éis an chruthaithe (le feiceáil i gconsól an chomhlachta). Faigheann eochair éagtha 401 follasach — féach #cle-expiree.
Is féidir freisin stopadh ag glacadh le heochair roimh an dáta sin, nuair nach bhfuil an API mar chuid de shíntiús an chomhlachta a thuilleadh. Tagann an stopadh ansin 30 lá ar a laghad tar éis an chéad ríomhphoist chuig an gcomhlacht, ar an dáta a thugann an dara ríomhphost, a sheoltar 7 lá ar a laghad roimh ré. Chomh luath agus a shocraítear é, tá an dáta sin le feiceáil i gconsól an chomhlachta (réimse coupure_le de GET /connect/cles), agus fógraíonn gach freagra ar ghlao a glacadh é sa cheanntásc Sunset go dtí go dtagann sé. Ina dhiaidh sin, faigheann an glao an 401 a thuairiscítear faoi #authentification, le "motif": "fin_option_api"; má thagann an API ar ais sa síntiús, glactar leis an eochair arís, go dtí a dáta éaga féin.
Ní thagann eochair a cúlghaireadh ar ais leis an API. Agus nuair a chuirtear an síntiús ar fad ar fionraí nó nuair a thagann deireadh leis, stoptar ag glacadh leis na heochracha láithreach, gan an tréimhse sin.
Ráta. 60 iarratas/nóiméad in aghaidh na heochrach (in-sáraithe in aghaidh na heochrach). Iompraíonn 429 Retry-After agus na ceanntásca X-RateLimit-Limit / -Remaining / -Reset.
Cúlghairm. Láithreach, ón gconsól. De réir achoimre a réitítear: ní féidir eochracha a áireamh ceann ar cheann.

Tús tapa

Trí ghlao curl agus tá an t-iomlán feicthe agat.

# Sláinte + fíordheimhniú na heochrach
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# An dialann faire, ón tús, i leathanaigh de 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Imeacht 42 a cháiliú (scóip scríofa)
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"}'

An t-uimhriú leathanach, in aon riail amháin

Seachaid depuisSeq (0 ar an gcéad ghlao) agus limite (uasteorainn 500): sórtáiltear an freagra de réir seq in ord ardaitheach agus tugann sé prochainSeq ar ais, le seachadadh mar atá ar an gcéad ghlao eile. Leathanach níos giorra ná limite, sin deireadh na dialainne — fanann prochainSeq seasmhach ansin agus feidhmíonn sé mar chúrsóir don cheistiú rialta. Gan depuisSeq, faigheann tú an t-amharc « is déanaí ar dtús », teoranta do 500.

Ceistítear an phunann ar /api/v1/portefeuille/agregats — áiritheoirí, freagra amháin, gan uimhriú leathanach.

Webhookanna

Sínithe, stampáilte le ham, seachadta uair amháin ar a laghad.

In áit an dialann a cheistiú arís is arís eile, glac léi: seachadann Vigilae na himeachtaí chuig do URL, in ord, i mbaisceanna de 100 ar a mhéad. Is at-least-once an seachadadh — ní théann an cúrsóir chun cinn ach ar do 2xx, baisc ar bhaisc — agus is de réir seq an idempotence: próiseáil gach seicheamh díreach uair amháin (#idempotence).

An síniú a fhíorú

Iompraíonn gach seachadadh an ceanntásc x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Athríomh v1 ón gcorp amh a fuarthas, agus diúltaigh d'aon stampa ama t atá níos faide amach ná 5 nóim: sin an frith-athsheinm. Le linn rothlú rúin iompraíonn an ceanntásc v1 amháin in aghaidh gach rúin atá fós bailí (forluí 24 u): glac leis má mheaitseálann ceann ar bith díobh.

// Node — fíorú an tsínithe (gan spleáchas)
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; // frith-athsheinm
  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 — an fíorú céanna
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  # frith-athsheinm
    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

Idirthréimhseach: astaítear an seanfhormáid sha256=HMAC(body) fós ar x-vigilae-signature-legacy do ghlacadóirí atá i bhfeidhm cheana; tá a baint beartaithe le webhooks v2. Fíoraíonn glacadóirí nua an scéim stampáilte le ham thuas, ní an seancheann.

Truicearaítear an rothlú ón gconsól (POST /connect/webhook/rotation ar thaobh an fheidhmchláir): ar feadh 24 u síníonn an seanrún i gcónaí — am chun an ceann nua a imscaradh ar do thaobh féin gan fhuinneog teipe.

Giuirléidí leabaithe

Stádas an fhaireachais, i do scáileáin.

Cruthaíonn do bhogearra na comhaid cheana féin tríd an API; tugann na giuirléidí dó an dromchla a bhí in easnamh: stádas faireachais comhaid a thaispeáint i do thaifead cliaint, gan comhéadan comhlíontachta a atógáil. Tá an sreabhadh i dtrí chéim — eisíonn do fhreastalaí comhartha gairid, téann an URL a thugtar ar ais isteach in iframe, taispeánann an ghiuirléid. Ní dhéanann sí ach taispeáint: ní théann aon chinneadh, aon cháiliú ná aon scríobh trí ghiuirléid riamh. Osclaíonn an cliceáil feidhmchlár Vigilae, áit a ngníomhaíonn duine sainaitheanta.

1. Eisigh an comhartha — ar thaobh an fhreastalaí, ní sa leathanach riamh

Ní thagann an eochair vgk_ i dteagmháil leis an mbrabhsálaí riamh. Glaonn do fhreastalaí ar an mint leis an scóip thiomnaithe embed:emettre (ticeáilte ag am chruthú na heochrach, gan oidhreacht riamh), agus ní théann síos chuig an leathanach ach an comhartha gairid: cúig nóiméad déag mar réamhshocrú, faoi theorainn 5-60, ceangailte le comhad amháin, comhpháirt amháin, bunús dearbhaithe amháin. Taistealaíonn sé i mblúire an URL — ní shroicheann sé ár logaí ná do chuidse.

# Comhartha don Compliance Button, an lipéad roghnaithe ón gcatalóg
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. Socraigh an iframe — an lainseálaí, i ndeich líne

Cruthaíonn an lainseálaí vigilae-embed.js an iframe sandboxáilte, déanann sé an handshake agus leanann sé méid na giuirléide (faoi theorainn — ní fhorchuireann an iframe a airde féin ar do leathanach go deo). Ó thaobh CSP de, ní osclaíonn do leathanach ach treoir amháin: frame-src https://vigilae.org. Ní gá script inline ná spleáchas ar bith. Oibríonn iframe scríofa de láimh chomh maith céanna.

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

// I do script féin: tagann an url ó DO fhreastalaí féin, a ghlaoigh ar an mint
var widget = VigilaeEmbed.monter({
  conteneur: 'vigilance',
  url: urlReturnedByTheMint,
  renouvelerJeton: function () {   // ag am éaga: eisigh comhartha nua ar thaobh an fhreastalaí
    return fetch('/my-server/vigilae-token').then(function (r) { return r.text(); });
  },
});
// seolann widget.rafraichir(token) comhartha úr isteach; baineann widget.demonter() gach rud.

3. Compliance Button: do lipéad-sa, ár stádas-ne

Roghnaítear lipéad an chnaipe ó chatalóg dhúnta — ní théacs saor riamh ar dhromchla a labhraíonn faoin bhfaireachas — ní thaispeánann an shell na lipéid seo ach i bhFraincis nó i mBéarla (paraiméadar ?lang=), ní i do theanga féin go fóill; tugann an liosta thíos a mbrí:

controler_client — « Seiceáil an cliant seo » (réamhshocrú)
lancer_vigilance — « Cuir tús leis an bhfaireachas »
verifier_be — « Seiceáil na húinéirí tairbhiúla »
preparer_dossier — « Ullmhaigh an comhad FAS-CSA »

An spota stádais, áfach, léiríonn sé stádas a ríomhann Vigilae: a_jour (glas — scagadh agus rátáil suas chun dáta), a_revoir (ómra — scagadh nó rátáil as dáta, nó teip ar an bhfoinse ag an rith deireanach), alerte (dearg — foláireamh amháin ar a laghad le hathbhreithniú), inconnu (liath — comhad nár scagadh riamh). Is féidir an lipéad a chumrú; an bhrí féin, ní athraíonn sí choíche: tá an dath ceangailte leis an stádas laistigh den shell féin, a dhéanann neamhaird d'aon iarracht postMessage é a shárú. Taispeánann comhad atá i staid foláirimh foláireamh, cibé stíleáil a chuirtear air.

An conradh postMessage, ina iomláine

Astaíonn an ghiuirléid vigilae:pret, vigilae:taille (uath-athrú méide), vigilae:expire (eisigh comhartha nua ar thaobh an fhreastalaí, ansin postáil vigilae:jeton) agus vigilae:ouvrir. Ní bhíonn ainm, riosca ná foláireamh laistigh de theachtaireacht go deo: tá gach rud ag do bhogearra cheana féin tríd an API server-to-server, agus ní bheidh an cainéal seo ina dhara ceann riamh.

Dearbhú bunús: ag riarthóir do chomhlachta. Tá comhartha leabaithe ceangailte le bunús dearbhaithe de chuid do chomhlachta — is é an bunús sin a stiúrann CSP frame-ancestors an shell. Dearbhaíonn an riarthóir é go díreach i Vigilae, ar an scáileán « Comhtháthuithe agus slándáil »: deich mbunús https:// ar a mhéad, óstach follasach, gan saoróg riamh; na comhpháirteanna a chuireann sé ar siúl; agus cúlghairm iomlán a mharaíonn gach comhartha atá eisithe cheana féin, le gníomh amháin. Ní cheadaítear http://localhost ach ar chomhlacht sandbox — scríobh chuig contact@vigilae.org (ábhar « Giuirléidí leabaithe ») chun ceann a oscailt ar feadh do chomhtháthaithe. Gan aon bhunús dearbhaithe: diúltaíonn an mint le 400. Ásc nach bhfuil a stóras bunús ceangailte: 501 follasach — féach #embed-indisponible.

Timpeallacht tástála

Sandbox: ar iarratas.

Níl aon sandbox féinseirbhíse ann go fóill — b'fhearr linn é sin a rá leat anseo ná ligean duit teacht air. Scríobh chuig contact@vigilae.org (ábhar « Rochtain API »): osclaímid comhlacht trialach le sonraí bréige ar feadh do chomhtháthaithe, agus fanaimid insroichte fad a théann sé chun cinn.

Tá seoladh seasmhach ag gach aicme earráide API ar an tagairt earráidí: #authentification, #scopes, #cloisonnement, #debit, #signature… Díreoidh freagraí earráide an API ar na hancairí seo.

Ní nochtann an API tuairiscí ar idirbhearta amhrasacha ná athfhriotal cliaint, de bharr an dearaidh (art. L.561-18 de CMF na Fraince). Ní ghlacann an API aon chinneadh faireachais: nochtann agus cáilíonn sé imeachtaí; is é an gairmí a chinneann.