Fejlesztőknek
Partneri API
Küldje be nekünk az ügyfelet saját álnevesített azonosítóval - e-mail-cím, név és más személyes adat nélkül - és bármikor olvassa le a képzése állapotát. Compliance-ellenőrzésként szolgál szerződés, befizetés vagy kifizetés előtt.
1.3.2-es verzió · JSON HTTPS-en keresztül · OpenAPI
Hogyan működik
Az API minden partner számára ugyanaz. Öt lépésben:
- Bekapcsoljuk az API-t az Ön vállalata számára; az adminisztrációjában az API fülön létrehoz egy API-kulcsot.
- Amikor egy ügyfélnek képzésen kell részt vennie, az Ön rendszere meghívja a POST /v1/users végpontot az Ön ügyfélazonosítójával.
- E-mail-cím nélküli profilt hozunk létre, és visszaadunk egy belépési linket (entryUrl); ezt gombként mutatja meg az ügyfélnek.
- Az ügyfél rákattint, és máris a tanfolyamban van.
- Az állapotot bármikor leolvashatja a GET /v1/users/{identifier} hívással, vagy webhookkal értesítjük róla az Ön szerverét.
Az azonosító adatkezelője Ön, mi csak álnevesített adatokat kezelünk. Azonosítóként soha ne küldjön e-mail-címet vagy nevet - az e-mail-címet az API 422-es hibával elutasítja.
Cím és hitelesítés
Minden hívás HTTPS-en keresztül az alábbi címre megy, és az Ön API-kulcsát az Authorization fejlécben hordozza.
https://api.responsiblo.com Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- Az rsb_live_... az éles programját nyitja meg, az rsb_test_... a tesztprogramját (sandbox).
- A kulcs csak egyszer jelenik meg, a létrehozáskor; csak az ujjlenyomatát tároljuk. Titokként őrizze a saját szerverén - soha ne böngészőben vagy alkalmazásban.
- A kulcsnak jogosultságai vannak: read (a személyek állapota és listája, a tanúsítvány) és write (személyek beküldése és anonimizálása). Korlátozható az Ön IP-címeire, és lehet érvényességi ideje.
- Csere: új kulcsot hoz létre, a régi még 7 napig érvényes, aztán lejár.
- A válaszokat soha nem tároljuk gyorsítótárban (Cache-Control: no-store), és az API nem fogad hívásokat böngészőből (nincs CORS).
POST /v1/users
Beküld egy személyt a kulcs programjába (write jogosultság).
curl -X POST https://api.responsiblo.com/v1/users \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-d '{"identifier":"client-48213","language":"cs","label":"campaign-2026-10"}'
| Mező | Kötelező | Jelentés |
|---|---|---|
identifier |
igen | Az Ön álneve a személyhez, 1-64 karakter A-Z a-z 0-9 . _ : @ -; soha nem e-mail-cím (422-vel elutasítva). |
program |
nem | A program kódja; ha megadja, a kulcs programjának kell lennie. |
language |
nem | A tanfolyam nyelve (cs, en, ...); alapértelmezés a program első nyelve. |
label |
nem | Az Ön címkéje - kohorsz vagy kampány, 1-64 karakter, soha nem személyes adat. |
expiresAt |
nem | A hozzáférés utolsó napja, ÉÉÉÉ-HH-NN. |
201 Created új személy esetén, 200 OK, ha az azonosító már létezik - semmi sem változik, a hívás biztonságosan megismételhető. A törzs az alábbi állapot, az entryUrl-lel együtt. A személyek vagy a program licenceinek kimerült kerete 403-at ad vissza.
GET /v1/users/{identifier}
Egy személy állapota (read jogosultság): amire a compliance-ellenőrzésnek szüksége van, semmi több.
curl https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"
{
"identifier": "client-48213",
"program": "your-program",
"status": "in_progress",
"progress": 43,
"lessonsCompleted": 3,
"lessonsTotal": 7,
"quizScore": null,
"label": "campaign-2026-10",
"createdAt": "2026-10-20T10:02:11Z",
"startedAt": "2026-10-20T10:05:40Z",
"completedAt": null,
"lastActivityAt": "2026-10-20T10:31:40Z",
"expiresAt": null,
"certificate": null,
"entryUrl": "https://your-company.responsiblo.com/entry/..."
}
status | Jelentés |
|---|---|
enrolled |
beküldve, még nem lépett be |
started |
belépett, még semmit sem fejezett be |
in_progress |
vannak befejezett leckéi, a programot még nem fejezte be |
completed |
a program befejeződött (completedAt) |
expired |
a hozzáférés véget ért (az expiresAt lejárt; a sandboxban lévő személy 7 nap után kilép) |
A quizScore a záró kvíz eredménye %-ban, amint befejeződött. Az időpontok UTC szerint, egész másodpercre vannak megadva. A certificate mező a személy tanúsítványát tartalmazza (lásd alább); amíg nincs neki, értéke null.
?include=detail
Hozzáadja az előrehaladást minden tanfolyamban és minden kvíz eredményét - soha nem az egyes válaszokat.
"courses": [{"id": "733db340-...", "name": "Introduction", "progress": 40, "lessonsCompleted": 2, "lessonsTotal": 5, "completed": false}],
"quizzes": [{"id": "d2e72fd7-...", "name": "Quiz of the introduction", "score": 85, "completedAt": "2026-10-20T10:31:40Z"}]
GET /v1/users
Azoknak a személyeknek a listája, akiket a kulcs programjába küldött (read jogosultság), oldalanként: minden tétel a fenti állapot formáját követi. Opcionálisan status (csak az ilyen állapotú személyek), limit (1-500, alapértelmezés 100) és cursor.
curl "https://api.responsiblo.com/v1/users?status=completed&limit=100" -H "Authorization: Bearer $RSB_KEY"
{
"items": [{ "identifier": "client-48213", "status": "completed", "...": "the state of GET /v1/users/{identifier}" }],
"nextCursor": "MjAyNi0xMC0yMFQxMDowMjoxMVp8...",
"limit": 100
}
curl "https://api.responsiblo.com/v1/users?status=completed&limit=100&cursor=MjAyNi0xMC0yMFQxMDowMjoxMVp8..." -H "Authorization: Bearer $RSB_KEY"
- Folytassa a cursor = nextCursor értékkel, amíg a nextCursor nem null; a kurzor átláthatatlan szöveg, soha ne állítsa össze maga.
- A személyek a beküldés időpontja szerint, állandó sorrendben következnek (azonos időpont esetén is), egyik sem kétszer; az anonimizált személyek nem szerepelnek a listában.
- A status szűrővel egy oldalhoz legfeljebb 2000 személyt nézünk át, ezért egy oldalon kevesebb tétel lehet, mint a limit, akár egy sem - folytassa, amíg van nextCursor.
A személy tanúsítványa
Amint a személy befejezi a programot, a tanfolyam tanúsítványt állít ki neki - az álnevén (a profil beceneve ID XXXXXX), név és e-mail-cím nélkül. E-mailben semmit sem küldünk; a személy állapotában szerepel a certificate mező a számmal, az időpontokkal és a nyilvános ellenőrző oldallal, a PDF-et pedig a GET /v1/users/{identifier}/certificate hívással töltheti le.
"certificate": {
"number": "RSP-7KQ2-M4XH-9TWB",
"issuedAt": "2026-10-20T10:39:15Z",
"expiresAt": "2028-10-20T10:39:12Z",
"verifyUrl": "https://responsiblo.com/verify/RSP-7KQ2-M4XH-9TWB"
}
curl https://api.responsiblo.com/v1/users/client-48213/certificate -H "Authorization: Bearer $RSB_KEY" -o client-48213.pdf
- A verifyUrl ellenőrző oldal csak az álnevet, a programot, a partnert és az érvényességet mutatja - soha nem az Ön azonosítóját.
- A PDF application/pdf típust ad vissza (read jogosultság). Tanúsítvány nélkül a válasz 404 certificateNotFound, ha pedig a PDF még készül, 404 certificatePdfNotReady Retry-After fejléccel.
- Visszavont tanúsítványt soha nem adunk ki (a certificate mező ekkor null, a PDF 404); a lejárt érvényességű tanúsítvány valós igazolás marad, és kiadjuk.
- A webhook a certificate.issued eseménnyel jelzi a tanúsítványt (közvetlenül a user.completed után).
DELETE /v1/users/{identifier}
Anonimizál egy személyt (write jogosultság): a profilból eltűnik az Ön azonosítója, a címke és minden webhook-üzenet, amely megnevezi; a belépési linkek érvényüket vesztik. A tanúsítvány és a tanfolyam eredménye a tanúsítvány száma alatt megmarad - compliance-igazolásként.
curl -X DELETE https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY" HTTP/1.1 204 No Content
Válasz: 204 törzs nélkül; ugyanazzal az azonosítóval minden további hívás 404 userNotFound választ ad, így az ismétlés biztonságos. Ugyanazt az azonosítót ezután újra beküldheti új személyként.
Belépési link
Mutassa meg az entryUrl-t a személynek (egy Tanfolyam indítása gomb az Ön rendszerében). Bejelentkezteti a tanfolyamba - e-mail-cím és jelszó nélkül.
A link 30 napig érvényes, és többször is használható; minden GET /v1/users/{identifier} hívás újat ad vissza. Soha ne küldje el senki másnak: akinél a link van, az az adott személyként lép be.
Webhookok
Az adminisztrációja API fülén minden programhoz egy webhookot állít be: a szervere nyilvános HTTPS-címét és az eseményeket. Ezután POST kérést küldünk Önnek JSON-nal - csak azonosítókat és állapotokat, soha nem a belépési linket.
| Esemény | Mikor |
|---|---|
user.enrolled |
a személyt beküldték (először, amikor a webhookja ismeri) |
user.started |
a személy belépett a tanfolyamba |
user.completed |
a személy befejezte a programot |
certificate.issued |
a személy tanúsítványt kapott; a data tartalmazza a certificate mezőt (szám, időpontok, verifyUrl) |
user.expired |
a személy hozzáférése véget ért |
POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: user.completed
X-Responsiblo-Delivery: 5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77
X-Responsiblo-Signature: t=1792492800,v1=3f1c...e9
{
"id": "5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77",
"type": "user.completed",
"createdAt": "2026-10-20T10:40:00Z",
"apiVersion": "1.3.2",
"program": "your-program",
"data": {
"identifier": "client-48213",
"status": "completed",
"progress": 100,
"lessonsCompleted": 7,
"lessonsTotal": 7,
"quizScore": 85,
"label": "campaign-2026-10",
"startedAt": "2026-10-20T10:05:40Z",
"completedAt": "2026-10-20T10:39:12Z",
"expiresAt": null
}
}
Aláírás
Minden üzenet tartalmazza az X-Responsiblo-Signature: t=<Unix-idő>,v1=<HMAC-SHA256 a t.törzs szövegből a webhook titkával, hex> fejlécet. A titok (whsec_...) egyszer jelenik meg, a webhook létrehozásakor. Mielőtt megbízna egy üzenetben, ellenőrizze az aláírást és a t korát; idempotenciakulcsként használja az X-Responsiblo-Delivery fejlécet.
// PHP: $secret = "whsec_...", $header = X-Responsiblo-Signature, $body = the raw body
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m);
$valid = $m
&& abs(time() - (int) $m[1]) <= 300
&& hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);
Kézbesítés és ismétlés
Kézbesítve = 2xx válasz 10 másodpercen belül. Ellenkező esetben 1 perc, 5 perc, 30 perc, 2 óra és 12 óra múlva újrapróbáljuk, aztán feladjuk. Az átirányításokat nem követjük.
20 egymást követő kézbesítetlen üzenet kikapcsolja a webhookot, amíg újra be nem kapcsolja; az ebből az időszakból származó üzenetek várnak. A Test gomb pinget küld; a kézbesítési naplót az adminisztrációjában találja.
A certificate.issued eseményt a webhook beállításaiban adhatja hozzá; az 1.2-es verzió előtt létrehozott webhook magától nem kapja meg.
Hibák
Minden hibának egyetlen formája van: status, code, reason és message; a 422-es hiba hozzáadja az errors mezőt (mező - mi a hiba).
{ "status": "error", "code": 422, "reason": "invalidBody", "message": "The body is not valid.",
"errors": { "identifier": "identifier must be a pseudonym of the partner, never an e-mail address" } }
| HTTP | reason | Teendő |
|---|---|---|
| 400 | invalidJson |
küldjön egyetlen JSON-objektumot |
| 401 | missingToken, invalidToken |
küldjön érvényes kulcsot (a visszavont és a lejárt kulcs ugyanúgy néz ki); a WWW-Authenticate fejléc értéke Bearer |
| 403 | scopeDenied, ipNotAllowed, apiDisabled, partnerInactive, spaceUnavailable, httpsRequired, userLimitReached, seatsExhausted |
a kulcs ezt nem teheti meg, az API ki van kapcsolva az Ön vállalata számára, vagy a program betelt |
| 404 | userNotFound, notFound |
a kulcs programjában nincs ilyen azonosítójú személy (anonimizált sem) |
| 404 | certificateNotFound, certificatePdfNotReady |
a személynek még nincs tanúsítványa, vagy a PDF-je készül - próbálja újra a Retry-After után |
| 409 | identifierTaken |
az azonosító egy másik program személyéhez tartozik |
| 422 | invalidBody, invalidParameter |
lásd errors (a törzs mezője vagy a lekérdezés paramétere - mi a hiba) |
| 429 | rateLimited |
várjon Retry-After másodpercet |
| 500 | internalError |
próbálja újra később; ügyfélszolgálatunknak adja meg az incidentId-t |
Programoknak és ügynököknek
- A code és a reason alapján döntsön, soha ne a message szövege alapján; az errors egy mező -> mi a hiba szerkezetű objektum.
- Csak a 429-et, az 500-at és a certificatePdfNotReady-t ismételje meg, mégpedig Retry-After másodperc után (egyébként növekvő időközzel); a 429-en kívüli 4xx hibákat a hívás javítása nélkül ne ismételje meg.
- A POST /v1/users az identifier szerint idempotens (első alkalommal 201, utána 200); a DELETE első alkalommal 204-et, utána 404-et ad vissza - mindkettő biztonságosan megismételhető.
- A webhookokat az X-Responsiblo-Delivery alapján deduplikálja; az üzenetek sorrendje nem garantált, a data állapota dönt.
Hitelkalauz
A Hitelkalauz rövid tanfolyam a hitelnyújtónál hitelt igénylők számára: a szerződés aláírása előtt az igénylő három leckén, nyolc gyakorlati helyzeten és adott esetben egy kvízen megy végig, mindezt a saját ajánlata számaival, a végén pedig megerősíti az ajánlatot. Minden képernyőn kérhet magyarázatot. Az ajánlatot az API-n keresztül küldi el, belépési linket kap, az eredményről pedig webhook értesíti.
A hitelkalauzt az Önnel kötött megállapodás alapján aktiváljuk.
Az igénylő itt is csak az Ön álnevesített profilja a következő hívásból: POST /v1/users. Az ajánlatot az Ön referenciái (externalApplicationId, offerReference) azonosítják, a dokumentumokat pedig csak egy link SHA-256 ujjlenyomattal - soha nem név, e-mail-cím, személyi azonosító, számlaszám vagy telefonszám. A responsiblo nem hagyja jóvá a hitelt, a dokumentumokat nem tölti le és nem tárolja, a személyazonosságot nem ellenőrzi, és a kalauzhoz nem állít ki tanúsítványt.
- Létrehozza az igénylő profilját: POST /v1/users az Ön álnevével.
- Elküldi az ajánlatot: POST /v1/users/{identifier}/loan-offers; a 201-es válasz tartalmazza az entryUrl-t.
- Az entryUrl-t a saját hitelesített csatornáján adja át az igénylőnek. A link 30 napig érvényes és többször is használható; a kalauz az igénylő saját ajánlatának számait mutatja.
- A végéről webhook értesíti (loanGuide.completed, loanGuide.assistanceRequested és további események).
- Az állapotot a GET …/loan-offers/{offerReference}, az aktájába szánt nyilvántartást a GET …/evidence hívással olvassa le. Módosított ajánlat = új ajánlat supersedes mezővel, visszavont igénylés = POST …/cancel.
Az aktiválásig a kalauz műveletei 404 notFound vagy 409 loanGuideNotConfigured választ adnak. A write jogosultság elküldi és visszavonja az ajánlatot, a read leolvassa az állapotot és a nyilvántartást.
POST /v1/users/{identifier}/loan-offers
Ajánlatot küld az igénylő profiljához (write jogosultság). Az opcionális Idempotency-Key fejléc 1-255 látható ASCII karakterből áll. Példa: 10 000 CZK hitel, 10 800 CZK fizetendő egy összegben a folyósítás után 30 nappal, THM 155,10%.
curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: offer-30417-1" \
-d '{
"externalApplicationId": "APP-30417",
"offerReference": "OFF-30417-1",
"locale": "cs-CZ",
"currency": "CZK",
"principalMinor": 1000000,
"disbursedAmountMinor": 1000000,
"totalPayableMinor": 1080000,
"aprPercent": "155.10",
"interestRate": { "percent": "8", "period": "month" },
"repayment": {
"type": "singlePayment",
"amountMinor": 1080000,
"due": { "kind": "relative", "days": 30, "anchor": "disbursement" }
},
"documents": [
{ "role": "precontract_information", "reference": "DOC-PRE-30417", "title": "Předsmluvní informace",
"url": "https://documents.lender.example/pre/30417.pdf",
"sha256": "623f4a37e444268c076896d6c2f389b46f568d1a26539b013f2ba25d03846f72" },
{ "role": "contract_package", "reference": "DOC-CON-30417", "title": "Smlouva a podmínky",
"url": "https://documents.lender.example/contract/30417.pdf",
"sha256": "9c7bfe0077d1189914f0e1c483c961f4c5b36e9892385f3d2ab6168e0c088aa6" }
],
"validUntil": "2026-11-15T18:00:00Z"
}'
HTTP/1.1 201 Created
{
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"offerStatus": "active",
"guideStatus": "created",
"validUntil": "2026-11-15T18:00:00Z",
"snapshotSha256": "8055bfa3c5f2c163691b85785eaf61221169a123bed67aff2c1dbaf2a8e44e7e",
"entryUrl": "https://your-company.responsiblo.com/entry/...",
"createdAt": "2026-11-10T09:14:05Z"
}
| Mező | Kötelező | Jelentés |
|---|---|---|
externalApplicationId |
igen | Az Ön igénylésszáma, 1-128 karakter A-Z a-z 0-9 . _ : -; soha nem e-mail-cím. |
offerReference |
igen | Az Ön ajánlat-referenciája, ugyanazok a szabályok, mint az externalApplicationId esetén. |
locale |
igen | A kalauz nyelve és országa: cs-CZ. |
currency |
igen | Pénznem: CZK. |
principalMinor |
igen | A hitel összege fillérben, egész szám 1 és 10 000 000 000 között. |
disbursedAmountMinor |
igen | A folyósított összeg fillérben; meg kell egyeznie a hitel összegével. |
totalPayableMinor |
igen | A teljes fizetendő összeg fillérben; legalább a hitel összege, és pontosan a fizetések összege. |
aprPercent |
igen | A THM százalékban, szövegként ("155.10"), Ön számítja ki és Ön szavatolja. Pozitív költségeket 0 THM mellett az API elutasít. |
interestRate |
nem | Kamatláb {percent, period}, period = year, month vagy day. |
repayment |
igen | Törlesztés: singlePayment {amountMinor, due} dátummal (kind date) vagy a folyósítástól számított napok számával (kind relative, 1-365), vagy installments {schedule: [{date, amountMinor}]} 1-360 részlettel növekvő sorrendben, egyik sem a múltban. A típusnak meg kell felelnie a kalauzához beállított terméknek. |
documents |
igen | 2-10 dokumentum {role, reference, title, url, sha256}; lefedve a kalauza beállításai által megkövetelt szerepek (alapértelmezés precontract_information és contract_package). url csak HTTPS a kalauza beállításaiban engedélyezett hoszton, legfeljebb 2 048 karakter, belépési adatok nélkül; sha256 = 64 hexadecimális karakter, amelyet Ön deklarál. |
validUntil |
igen | Az ajánlat érvényessége, RFC 3339 időeltolással, a jövőben és legfeljebb 7 nappal előre. |
supersedes |
nem | Ugyanannak a profilnak az aktív ajánlatához tartozó offerReference, amelyet az új ajánlat felvált. |
returnUrl |
nem | Nem kötelező: a cím, ahová a Kész oldal a kalauz végén visszaküldi az igénylőt. Csak abszolút HTTPS, legfeljebb 2048 karakter, belépési adatok nélkül; a {offerReference} és {externalApplicationId} szimbólumokat az ajánlat hivatkozásaival helyettesítjük. Nélküle a kalauza beállításaiban megadott visszatérési cím érvényes. |
Ugyanaz a törzs újra (ugyanazon referenciák vagy ugyanazon Idempotency-Key alatt) 200-at ad vissza a meglévő ajánlattal és új entryUrl-lel; más törzs alattuk 409 offerConflict választ ad. Egy profilnak egy aktív ajánlata van: egy újabb supersedes nélkül 409 activeOfferExists, hibás supersedes 409 notSupersedable választ ad. A kalauza beállításai (kvíz, kapcsolat) ekkor az ajánlathoz rögzülnek.
Állapot, nyilvántartás és visszavonás
GET /v1/users/{identifier}/loan-offers/{offerReference}- állapot (read jogosultság): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), befejezett leckék, gyakorlat, kvíz (null, ha ki van kapcsolva), valamint az ajánlat bemutatásának, a megerősítésnek és a magyarázatkérésnek az időpontjai. Soha nem a válaszok, az ajánlat értékei vagy a link. A befejezés akkor is megmarad, ha az ajánlat később lejár.GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence- nyilvántartás az Ön aktájába (read jogosultság): schemaVersion loan-guide-evidence/1, az Ön ajánlatának pillanatképe snapshotSha256 ujjlenyomattal, a tanfolyam kiadása a leckék ujjlenyomataival, az események sequence sorrendben, minden válasz az összes kísérlettel, a megerősítés és limitations - amit a nyilvántartás nem bizonyít (a bemutatás nem jelenti az elolvasást, a személyazonosságot Ön állítja, a dokumentumok csak hivatkozással, nincs tanúsítvány, nincs hiteljóváhagyás).POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel- visszavonja az aktív ajánlatot (write jogosultság), reasonCode = withdrawn_by_provider vagy application_closed; a 200 az állapotot adja vissza, a nem aktív vagy befejezett kalauzú ajánlat 409 notActive választ ad.
curl https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1 -H "Authorization: Bearer $RSB_KEY"
{
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"offerStatus": "active",
"guideStatus": "completed",
"quizEnabled": true,
"lessonsCompleted": 3,
"lessonsTotal": 3,
"practiceCompleted": true,
"quizPassed": true,
"offerPresentedAt": "2026-11-10T18:32:47Z",
"confirmedAt": "2026-11-10T18:34:02Z",
"completedAt": "2026-11-10T18:34:02Z",
"assistanceRequested": false,
"assistanceRequestedAt": null,
"validUntil": "2026-11-15T18:00:00Z",
"evidenceErased": false,
"...": "..."
}
curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1/cancel \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-d '{"reasonCode":"withdrawn_by_provider"}'
?externalApplicationId= csak akkor szükséges, ha egy offerReference a profil több igényléséhez tartozik (egyébként 409 ambiguousOfferReference).
A kalauz webhookjai
A program webhookja (lásd Webhookok) külön feliratkozás nélkül megkapja a kalauz eseményeit. Az aláírás, a kézbesítés és az ismétlés ugyanaz, mint a többi eseménynél; a data tartalmazza az identifier, offerReference, externalApplicationId, guideStatus, occurredAt és sequence mezőt (egy ajánlat eseményeinek sorrendje) - soha nem a nyilvántartást, az ajánlat értékeit vagy a belépési linket.
| Esemény | Mikor |
|---|---|
loanGuide.completed |
az igénylő végigment a kalauzon és megerősítette az ajánlatot |
loanGuide.assistanceRequested |
az igénylő magyarázatot kért (hívja fel) |
loanGuide.expired |
az ajánlat validUntil ideje lejárt |
loanGuide.superseded |
az ajánlatot új ajánlat váltotta fel (supersedes) |
loanGuide.cancelled |
Ön visszavonta az ajánlatot |
POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: loanGuide.completed
X-Responsiblo-Delivery: 0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08
X-Responsiblo-Signature: t=1794335647,v1=8b2d...4c
{
"id": "0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08",
"type": "loanGuide.completed",
"createdAt": "2026-11-10T18:34:07Z",
"apiVersion": "1.3.2",
"program": "your-program",
"data": {
"identifier": "applicant-30417",
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"guideStatus": "completed",
"occurredAt": "2026-11-10T18:34:02Z",
"sequence": 23
}
}
Minden esemény egy webhookhoz legfeljebb egyszer érkezik meg (idempotenciakulcs = X-Responsiblo-Delivery). A később létrehozott webhook nem játssza le újra a korábbi eseményeket, és a 28 napnál régebbi eseményekről már nem küldünk értesítést.
A nyilvántartás megőrzése
Amikor az ajánlat útja véget ér (befejezett, visszavont, lejárt vagy felváltott ajánlat), elindul a kalauza beállításai szerinti megőrzési idő (alapértelmezés 30 nap). Ezután a nyilvántartás törlődik: a GET …/evidence 410 evidenceErased választ ad, az állapot pedig továbbra is válaszol evidenceErased: true értékkel, a referenciákkal és az időpontokkal. Aktív ajánlatot soha nem törlünk. A megőrzendő nyilvántartást közvetlenül a loanGuide.completed után töltse le.
A kalauz hibái
A hibák a fenti API-formát követik. Ezen felül a kalauzhoz:
| HTTP | reason | Teendő |
|---|---|---|
| 404 | offerNotFound |
a profilnak nincs ilyen ajánlata (userNotFound = a profil nem létezik) |
| 409 | offerConflict, activeOfferExists, notSupersedable |
a referenciák vagy az Idempotency-Key már egy másik törzshöz tartoznak, vagy a profilnak másik aktív ajánlata van - küldje el a supersedes mezőt |
| 409 | loanGuideNotConfigured |
a kalauz nincs aktiválva az Ön programja számára - írjon nekünk |
| 409 | ambiguousOfferReference |
adja meg: ?externalApplicationId= |
| 409 | notActive |
az ajánlat nem aktív, vagy a kalauza befejeződött |
| 410 | evidenceErased |
a nyilvántartást a megőrzési idő után töröltük, az állapot megmarad |
| 422 | invalidOffer |
errors = {útvonal: kód[,kód]} a törzsbeli útvonallal (repayment.schedule[2].date, documents[0].url); a kódok az alábbi táblázatban |
| 422 | invalidBody |
supersedes, Idempotency-Key vagy a visszavonás törzse |
errors | Az invalidOffer hiba kódjai |
|---|---|
required |
a mező hiányzik |
invalidFormat |
hibás forma (típus, minta, hossz, link HTTPS nélkül vagy belépési adatokkal) |
outOfRange |
az engedélyezett tartományon kívül (összeg, a dokumentumok, részletek vagy napok száma) |
notEqualPrincipal |
a folyósított összeg nem egyezik a hitel összegével |
sumMismatch |
a fizetések összege nem egyezik a teljes fizetendő összeggel |
belowPrincipal |
a teljes fizetendő összeg kisebb a hitel összegénél |
aprContradiction |
0 THM pozitív költségek mellett |
typeMismatch |
a törlesztés típusa nem felel meg a kalauzához beállított terméknek |
missingRole |
hiányzik egy olyan szerepű dokumentum, amelyet a kalauza beállításai megkövetelnek |
hostNotAllowed |
a dokumentum linkje olyan hosztra mutat, amelyet a kalauza beállításai nem engedélyeznek |
notAscending |
a részletek dátumai nem növekvő sorrendűek, vagy ismétlődnek |
inPast |
a részlet dátuma vagy a validUntil a múltban van |
tooFar |
a validUntil több mint 7 nappal előre esik |
unsupported |
nem támogatott érték (locale, currency, type, period, kind) |
unknownField |
az API által nem ismert mező |
looksLikeEmail |
a referencia e-mail-címnek tűnik |
A hiba soha nem ismétli meg az Ön által küldött értéket. Példa: ugyanaz az ajánlat 10 800 CZK helyett 10 700 CZK fizetéssel és 9 napos érvényességgel:
"repayment": { "type": "singlePayment", "amountMinor": 1070000, "due": { "kind": "relative", "days": 30, "anchor": "disbursement" } },
"validUntil": "2026-11-19T18:00:00Z"
HTTP/1.1 422 Unprocessable Entity
{
"status": "error",
"code": 422,
"reason": "invalidOffer",
"message": "The offer contains invalid data.",
"errors": {
"repayment.amountMinor": "sumMismatch",
"validUntil": "tooFar"
}
}
Korlátok
Kulcsonként percenként 120 hívás. Ha egy címről tíz percen belül 30 kulcsot utasítunk el, a cím 10 percig vár.
A hívások naplóját (törzsek nélkül, az azonosítót csak SHA-256 ujjlenyomatként) 180 napig őrizzük, a kézbesített és feladott webhook-üzeneteket 30 napig.
Állapot és szerződés
GET /v1/status- kulcs nélkül, visszaadja: {"status":"ok","version":"1.3.2"}GET /openapi- kulcs nélkül, a partneri API OpenAPI 3 dokumentuma
Sandbox
Az rsb_test_... tesztkulcs a tesztprogramját nyitja meg ugyanazzal a tanfolyammal. Az ott lévő személyek 7 nap után kilépnek; a tesztprogram webhookja külön van az élesétől.
Verziótörténet
- 1.3.2 (2026-11) - Az OpenAPI dokumentum minden műveletének van neve és leírása, a műveletek csoportokba vannak rendezve. A /v1/status és a webhookok az 1.3.2-es verziót jelentik. A kérések és válaszok formája változatlan.
- 1.3.1 (2026-10) - Javítások a végpontok és válaszaik változtatása nélkül.
- 1.3.0 (2026-10) - Hitelkalauz: POST /v1/users/{identifier}/loan-offers, az ajánlat állapota, nyilvántartása és visszavonása, loanGuide.* webhookok, a nyilvántartás megőrzése. Az ajánlat nem kötelező returnUrl mezője (saját visszatérési cím).
- 1.2.0 (2026-10) - GET /v1/users lapozással, a személy tanúsítványa (certificate mező, GET /v1/users/{identifier}/certificate, certificate.issued esemény), DELETE /v1/users/{identifier} (anonimizálás), legfeljebb 64 karakteres azonosító, a napló megőrzése.
- 1.1.0 (2026-10) - API-kulcsok, POST /v1/users, GET /v1/users/{identifier} ?include=detail paraméterrel, belépési link, webhookok, a hibák egységes formája, nyilvános állapot és OpenAPI, korlátok.
- 1.0.0 (2024) - GET /v1/user/{identifier} a partnerkulcs JWT-jével.
Szeretné az API-t a vállalata számára? Írjon nekünk