Erinvia Partner API

Az Erinvia mérőmotorjának külső, verziózott API-ja: a vállalat saját rendszeréből (például ATS vagy HR-rendszer) listázhatod a kampányokat és a méréseket, résztvevőt vehetsz fel és hívhatsz meg egy beállított mérésbe, követheted az állapotot, és lekérheted az eredményt úgy, ahogy a Manager látja. A kérdésbank tartalma soha nem jön ki az API-n.

OpenAPI-leírás (JSON)

Azonosítás

Minden híváshoz API-kulcs kell az Authorization: Bearer fejlécben (vagy az X-API-Key fejlécben). A kulcsot a vállalat Managere hozza létre a Beállítások → Partner API lapon; a kulcs csak a létrehozáskor látszik, utána csak az eleje. A kulcs visszavonható.

Az éles kulcs ev_live_, a teszt kulcs ev_test_ kezdetű. Jogosultságok: read (listák, állapot), invite (résztvevő felvétele és meghívása), results (eredmények és PDF).

curl -H "Authorization: Bearer ev_test_…" /api/partner/v1/campaigns

Hozzáférés és korlátok

A Partner API a K100 és a K250 kreditcsomag része (a csomagonkénti beállítást az árlista is jelzi). Amíg a vállalatnak van kreditje, a hozzáférés teljes; ha elfogyott, csak olvasás: az eredmények lekérhetők, új meghívás nem küldhető. Az Erinvia a hozzáférést indokolt esetben kikapcsolhatja.

Híváskorlát: kulcsonként legfeljebb 120 hívás percenként (túllépésnél 429 és Retry-After fejléc). Minden hívás naplózódik, a napló 90 napig marad meg.

Végpontok

MódszerÚtvonalMit adJogosultság
GET/api/partner/v1/meA kulcs és a hozzáférés adatairead
GET/api/partner/v1/campaignsKampányok listájaread
GET/api/partner/v1/campaigns/{campaign}/measurementsA kampány méréseinek listájaread
GET/api/partner/v1/measurements/{measurement}Egy mérés adatairead
GET/api/partner/v1/measurements/{measurement}/participantsA mérés résztvevői és állapotukread
POST/api/partner/v1/measurements/{measurement}/participantsRésztvevő felvétele és meghívásainvite
GET/api/partner/v1/measurements/{measurement}/resultsA mérés eredményeresults
GET/api/partner/v1/measurements/{measurement}/report.pdfVezetői összefoglaló (PDF)results
GET/api/partner/v1/measurements/{measurement}/participants/{participant}/resultEgy jelölt eredményeresults
GET/api/partner/v1/measurements/{measurement}/participants/{participant}/result.pdfEgy jelölt riportja (PDF)results
POST/api/partner/v1/webhook/testMinta webhook-esemény küldéseread

Résztvevő meghívása

A résztvevő a vállalat névsorába és a megadott alapmérésbe kerül (vázlatba vagy futó mérésbe, a csatlakozási határidőn belül). Futó mérésnél a meghívó azonnal kimegy (send_invite: false esetén nem), és a válasz a személyes meghívó linket is tartalmazza. A kredit ugyanúgy fogy, mint a Manager felületén: a résztvevő első válaszakor.

{
  "email": "anna@example.com",
  "name": "Anna Kovacs",
  "locale": "hu-HU"
}

Eredmények — mi jön ki és mi nem

Kiválasztási mérésnél a hozzájáruló jelöltek készségenkénti szintsávja, betűrendben. Fejlesztési mérésnél csak az összesített eredmény, a mérés 5 fő alatti szabályával.

Webhook

A Manager a Beállítások → Partner API lapon ad meg egy https:// címet. Események: participant.completed (egy résztvevő befejezte a mérést) és measurement.closed (a mérés lezárult). Az eseményben csak kódok és időpontok vannak, név és eredmény nincs; az eredményt az API-n kérd le. Sikertelen kézbesítésnél a rendszer növekvő időközönként újrapróbálja (1 perc, 5 perc, 30 perc, 2 óra, 6 óra, 24 óra).

Minden kérés aláírt: az Erinvia-Signature fejléc t=<unix idő>,v1=<HMAC-SHA256 hex>, ahol az aláírt szöveg „t.törzs”, a kulcs a webhook titka (whsec_…; a beállításkor egyszer látszik). Az 5 percnél régebbi időbélyegű kérést utasítsd el. Az Erinvia-Event és az Erinvia-Delivery fejléc az esemény nevét és azonosítóját adja.

{
  "id": "evt-\u2026",
  "event": "participant.completed",
  "created_at": "2026-11-16T10:00:00+00:00",
  "api_version": "1.0",
  "test": false,
  "data": {
    "campaign": "ACME-2026",
    "measurement": "ACME-2026-1",
    "participant_id": "rst-\u2026",
    "completed_at": "2026-11-16T09:58:12+00:00"
  }
}
import hmac, hashlib
t, v1 = dict(x.split('=', 1) for x in header.split(','))['t'], ...
expected = hmac.new(secret.encode(), f'{t}.'.encode() + body, hashlib.sha256).hexdigest()

Tesztmód

A teszt kulccsal (ev_test_) az olvasó hívások a vállalat valós adatait adják, az írások viszont csak ellenőrzések: nem jön létre résztvevő, nem megy ki levél, nem fogy kredit (a válaszban test: true). A webhookot a minta-eseménnyel próbálhatod ki.

Hibakódok

401unauthorizedHiányzó, érvénytelen vagy visszavont kulcs.
403scope_missingA kulcsnak nincs meg a szükséges jogosultsága.
403api_not_availableA vállalatnak nincs Partner API-hozzáférése.
403read_onlyElfogyott a kredit: csak olvasás.
429rate_limitedTúl sok hívás; várj a Retry-After szerint.
404not_foundIsmeretlen kampány, mérés vagy résztvevő (vagy nem a vállalaté).
422email_invalidÉrvénytelen e-mail-cím.
409measurement_not_openA mérés nem vázlat és nem fut.
409remeasure_addVisszamérésbe nem vehető fel új résztvevő.
409join_closedLejárt a csatlakozási határidő.
409already_participantMár résztvevő; a válasz a participant_id-t is tartalmazza.
409other_measurementA résztvevő a kampány egy másik mérésében van.
403individual_not_availableFejlesztési mérésnél egyéni eredmény nincs.
409result_not_readyMég nincs eredmény (nem fejezte be, vagy nem járult hozzá).