Vigilae Connect

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

Tá an tsonraíocht poiblí, tá na dromchlaí neodrach, 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

Dromchlaí neodracha, de bharr an dearaidh.

Nochtann an API an méid is féidir le comhtháthaitheoir a ídiú gan baint le rúndacht na gcomhad: an dialann faire agus na háiritheoirí. Ní ghabhann ábhar comhaid faireachais, na cáipéisí ná na tuairiscí ar idirbhearta amhrasacha tríd an API seo — ní teorainn phlean é sin, ach an ailtireacht.

Dialann faire

Imeachtaí pKYC an chomhlachta — cáipéis éagtha, athrú ar úinéir tairbhiúil, ath-scagadh le hathbhreithniú — i bhfoirm neodrach: seicheamh, cineál, déine, dáta. Freagraí teoranta do 500 imeacht i gcónaí.

Comhiomláin phunainne

Áiritheoirí, ní comhad go deo: toirteanna de réir stádais, moilleanna, iomláine. A dhóthain le deais a rindreáil i d'uirlis féin gan oiread agus sonra cliaint amháin a ligean isteach inti.

Cáiliú

An t-aon scríobh: imeacht dialainne a cháiliú (stádas qualifie nó clos, diúscairt planifie, traite nó ecarte). Éilíonn sé an scóip scríofa — an phribhléid is lú an riail, ní rogha.

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. lecture (léamh, an réamhshocrú) agus ecriture (scríobh). 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.
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.

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.