responsiblo

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:

  1. 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.
  2. 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.
  3. 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.
  4. Az ügyfél rákattint, és máris a tanfolyamban van.
  5. 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/..."
}
statusJelenté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ényMikor
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" } }
HTTPreasonTeendő
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.

  1. Létrehozza az igénylő profilját: POST /v1/users az Ön álnevével.
  2. Elküldi az ajánlatot: POST /v1/users/{identifier}/loan-offers; a 201-es válasz tartalmazza az entryUrl-t.
  3. 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.
  4. A végéről webhook értesíti (loanGuide.completed, loanGuide.assistanceRequested és további események).
  5. 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ényMikor
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:

HTTPreasonTeendő
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
errorsAz 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