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.
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 | Útvonal | Mit ad | Jogosultság |
|---|---|---|---|
GET | /api/partner/v1/me | A kulcs és a hozzáférés adatai | read |
GET | /api/partner/v1/campaigns | Kampányok listája | read |
GET | /api/partner/v1/campaigns/{campaign}/measurements | A kampány méréseinek listája | read |
GET | /api/partner/v1/measurements/{measurement} | Egy mérés adatai | read |
GET | /api/partner/v1/measurements/{measurement}/participants | A mérés résztvevői és állapotuk | read |
POST | /api/partner/v1/measurements/{measurement}/participants | Résztvevő felvétele és meghívása | invite |
GET | /api/partner/v1/measurements/{measurement}/results | A mérés eredménye | results |
GET | /api/partner/v1/measurements/{measurement}/report.pdf | Vezetői összefoglaló (PDF) | results |
GET | /api/partner/v1/measurements/{measurement}/participants/{participant}/result | Egy jelölt eredménye | results |
GET | /api/partner/v1/measurements/{measurement}/participants/{participant}/result.pdf | Egy jelölt riportja (PDF) | results |
POST | /api/partner/v1/webhook/test | Minta webhook-esemény küldése | read |
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.
- Banki adat soha: nincs kérdés, azonosító, súly vagy nyers válasz.
- Összesített pontszám és rangsor nincs: készségenként külön szintsáv; a jelöltek betűrendben.
- Fejlesztési mérésnél egyéni eredmény nincs, csak összesített, az 5 fő alatti szabállyal.
- Kiválasztási mérésnél csak a hozzájáruló jelölt eredménye kérhető le.
- Döntés-támogatás: a döntést a HR hozza.
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
401 | unauthorized | Hiányzó, érvénytelen vagy visszavont kulcs. |
403 | scope_missing | A kulcsnak nincs meg a szükséges jogosultsága. |
403 | api_not_available | A vállalatnak nincs Partner API-hozzáférése. |
403 | read_only | Elfogyott a kredit: csak olvasás. |
429 | rate_limited | Túl sok hívás; várj a Retry-After szerint. |
404 | not_found | Ismeretlen kampány, mérés vagy résztvevő (vagy nem a vállalaté). |
422 | email_invalid | Érvénytelen e-mail-cím. |
409 | measurement_not_open | A mérés nem vázlat és nem fut. |
409 | remeasure_add | Visszamérésbe nem vehető fel új résztvevő. |
409 | join_closed | Lejárt a csatlakozási határidő. |
409 | already_participant | Már résztvevő; a válasz a participant_id-t is tartalmazza. |
409 | other_measurement | A résztvevő a kampány egy másik mérésében van. |
403 | individual_not_available | Fejlesztési mérésnél egyéni eredmény nincs. |
409 | result_not_ready | Még nincs eredmény (nem fejezte be, vagy nem járult hozzá). |