Partnerské API

Ako to funguje

API je pre všetkých partnerov rovnaké. V piatich krokoch:

1. API vám pre firmu zapneme; vo svojej administrácii si v záložke API vytvoríte API kľúč.
2. Keď sa má klient vyškoliť, váš systém zavolá POST /v1/users s vaším identifikátorom klienta.
3. Založíme profil bez e-mailu a vrátime vstupný odkaz (entryUrl); ten klientovi ukážete ako tlačidlo.
4. Klient naň klikne a je rovno v kurze.
5. Stav si kedykoľvek prečítate cez GET /v1/users/{identifier}, alebo ho vášmu serveru oznámime webhookom.

Prevádzkovateľom identifikátora ste vy, my spracúvame iba pseudonymné údaje. Ako identifikátor nikdy neposielajte e-mail ani meno - e-mailovú adresu API odmietne chybou 422.

Adresa a autentifikácia

Každé volanie ide cez HTTPS na adresu nižšie a nesie váš API kľúč v hlavičke Authorization.

https://api.responsiblo.com
Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• rsb_live_... otvára váš produkčný program, rsb_test_... váš testovací program (sandbox).
• Kľúč sa zobrazí iba raz, pri vytvorení; ukladáme si iba jeho odtlačok. Majte ho ako tajomstvo na svojom serveri - nikdy v prehliadači ani v aplikácii.
• Kľúč má oprávnenia: read (stav a zoznam osôb, certifikát) a write (posielanie a anonymizácia osôb). Môže byť obmedzený na vaše IP adresy a mať platnosť.
• Výmena: vytvoríte nový kľúč, starý platí ešte 7 dní, potom vyprší.
• Odpovede sa nikdy neukladajú do vyrovnávacej pamäte (Cache-Control: no-store) a API neprijíma volania z prehliadača (bez CORS).

POST /v1/users

Pošle osobu do programu kľúča (oprávnenie write).

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"}'

201 Created pre novú osobu, 200 OK, keď identifikátor už existuje - nič sa nemení, volanie možno bezpečne opakovať. Telo je stav nižšie aj s entryUrl. Vyčerpaný limit osôb alebo licencie programu vracia 403.

GET /v1/users/{identifier}

Stav osoby (oprávnenie read): to, čo compliance check potrebuje, nič navyše.

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/..."
}

quizScore je výsledok záverečného kvízu v %, len čo je dokončený. Časy sú v UTC na celé sekundy. Pole certificate nesie certifikát osoby (pozri nižšie), kým ho nemá, je null.

?include=detail

Pridá postup v každom kurze a výsledok každého kvízu - nikdy jednotlivé odpovede.

"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

Zoznam osôb, ktoré ste poslali do programu kľúča (oprávnenie read), po stránkach: každá položka má tvar stavu vyššie. Voliteľne status (iba osoby v tomto stave), limit (1 až 500, predvolene 100) a 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"

• Pokračujte s cursor = nextCursor, kým nextCursor nie je null; kurzor je nepriehľadný text, nikdy ho neskladajte sami.
• Osoby idú podľa okamihu poslania v stálom poradí (aj pri rovnakom okamihu), žiadna dvakrát; anonymizované osoby v zozname nie sú.
• S filtrom status prejdeme pre jednu stránku najviac 2000 osôb, stránka preto môže mať menej položiek ako limit, aj žiadnu - pokračujte, kým je nextCursor.

Certifikát osoby

Len čo osoba program dokončí, vydá jej kurz certifikát - pod jej pseudonymom (prezývka profilu ID XXXXXX), bez mena a bez e-mailu. Nič sa neposiela e-mailom; v stave osoby je pole certificate s číslom, časmi a verejnou overovacou stránkou a PDF si stiahnete cez GET /v1/users/{identifier}/certificate.

"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

• Overovacia stránka verifyUrl ukáže iba pseudonym, program, partnera a platnosť - nikdy váš identifikátor.
• PDF vracia application/pdf (oprávnenie read). Bez certifikátu odpoveď 404 certificateNotFound, keď sa PDF ešte vyrába, 404 certificatePdfNotReady s Retry-After.
• Zrušený certifikát sa nikdy nevydá (pole certificate je potom null, PDF 404); certifikát s uplynutou platnosťou zostáva pravdivým dokladom a vydá sa.
• Webhook oznámi certifikát udalosťou certificate.issued (hneď po user.completed).

DELETE /v1/users/{identifier}

Anonymizuje osobu (oprávnenie write): z profilu zmizne váš identifikátor, štítok a každá správa webhooku, ktorá ho menuje; vstupné odkazy prestanú platiť. Certifikát a výsledok kurzu zostanú pod číslom certifikátu - ako compliance doklad.

curl -X DELETE https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"

HTTP/1.1 204 No Content

Odpoveď 204 bez tela; každé ďalšie volanie toho istého identifikátora vráti 404 userNotFound, opakovanie je teda bezpečné. Rovnaký identifikátor potom môžete poslať znova ako novú osobu.

Vstupný odkaz

entryUrl ukážte osobe (tlačidlo Spustiť kurz vo vašom systéme). Prihlási ju do kurzu - bez e-mailu a bez hesla.

Odkaz platí 30 dní a možno ho použiť opakovane; každé volanie GET /v1/users/{identifier} vráti nový. Nikdy ho neposielajte nikomu inému: kto odkaz má, vstúpi ako tá osoba.

Webhooky

V záložke API svojej administrácie nastavíte jeden webhook pre každý program: verejnú HTTPS adresu svojho servera a udalosti. Potom vám posielame POST s JSON - iba identifikátory a stavy, nikdy vstupný odkaz.

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
  }
}

Podpis

Každá správa nesie hlavičku X-Responsiblo-Signature: t=<unixový čas>,v1=<HMAC-SHA256 textu t.telo s tajomstvom webhooku, hex>. Tajomstvo (whsec_...) sa zobrazí raz pri vytvorení webhooku. Skôr než správe uveríte, overte podpis aj vek t; ako kľúč idempotencie použite X-Responsiblo-Delivery.

// 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]);

Doručenie a opakovanie

Doručené = odpoveď 2xx do 10 sekúnd. Inak to skúsime znova o 1 minútu, 5 minút, 30 minút, 2 hodiny a 12 hodín, potom to vzdáme. Presmerovania nesledujeme.

20 nedoručených správ za sebou webhook vypne, kým ho znova nezapnete; správy z toho času počkajú. Tlačidlo Test pošle ping; log doručení nájdete vo svojej administrácii.

Udalosť certificate.issued pridáte webhooku v jeho nastaveniach; webhook založený pred verziou 1.2 ju sám nedostáva.

Chyby

Každá chyba má jeden tvar: status, code, reason a message; chyba 422 pridá errors (pole - čo je zle).

{ "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" } }

Pre programy a agentov

• Rozhodujte podľa code a reason, nikdy podľa textu message; errors je objekt pole -> čo je zle.
• Opakujte iba 429, 500 a certificatePdfNotReady, a to po Retry-After sekundách (inak s rastúcim odstupom); 4xx okrem 429 bez opravy volania neopakujte.
• POST /v1/users je idempotentné podľa identifier (201 prvýkrát, potom 200); DELETE vráti 204 prvýkrát a 404 potom - obe možno bezpečne opakovať.
• Webhook deduplikujte podľa X-Responsiblo-Delivery; poradie správ nie je zaručené, rozhoduje stav v data.

Sprievodca pôžičkou

Sprievodca pôžičkou je krátky kurz pre žiadateľa u poskytovateľa pôžičky: pred podpisom zmluvy prejde tri lekcie, osem praktických situácií a prípadne kvíz, všetko nad číslami svojej vlastnej ponuky, a na konci ponuku potvrdí. Na každej obrazovke môže požiadať o vysvetlenie. Ponuku pošlete cez API, dostanete vstupný odkaz a výsledok vám oznámi webhook.

Sprievodcu pôžičkou aktivujeme po dohode s vami.

Žiadateľ je aj tu iba váš pseudonymný profil z POST /v1/users. Ponuku určujú vaše referencie (externalApplicationId, offerReference) a dokumenty iba odkaz s odtlačkom SHA-256 - nikdy meno, e-mail, rodné číslo, číslo účtu ani telefón. responsiblo pôžičku neschvaľuje, dokumenty nesťahuje ani neukladá, totožnosť neoveruje a k sprievodcovi nevydáva certifikát.

1. Založíte profil žiadateľa: POST /v1/users s vaším pseudonymom.
2. Pošlete ponuku: POST /v1/users/{identifier}/loan-offers; odpoveď 201 nesie entryUrl.
3. entryUrl odovzdáte žiadateľovi svojím overeným kanálom. Odkaz platí 30 dní a možno ho použiť opakovane; sprievodca ukáže čísla jeho ponuky.
4. Koniec sa dozviete webhookom (loanGuide.completed, loanGuide.assistanceRequested a ďalšie).
5. Stav si prečítate cez GET …/loan-offers/{offerReference}, záznam pre svoj spis cez GET …/evidence. Zmenená ponuka = nová ponuka so supersedes, stiahnutá žiadosť = POST …/cancel.

Do aktivácie odpovedajú operácie sprievodcu 404 notFound alebo 409 loanGuideNotConfigured. Oprávnenie write posiela a ruší ponuku, read číta stav a evidenciu.

POST /v1/users/{identifier}/loan-offers

Pošle ponuku k profilu žiadateľa (oprávnenie write). Voliteľná hlavička Idempotency-Key má 1 až 255 viditeľných znakov ASCII. Príklad: pôžička 10 000 CZK, na zaplatenie 10 800 CZK jednou platbou 30 dní po výplate, RPMN 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"
}

Rovnaké telo znova (pod rovnakými referenciami alebo rovnakým Idempotency-Key) vráti 200 s existujúcou ponukou a novým entryUrl; iné telo pod nimi vráti 409 offerConflict. Profil má jednu aktívnu ponuku: ďalšia bez supersedes vráti 409 activeOfferExists, chybné supersedes 409 notSupersedable. Nastavenia vášho sprievodcu (kvíz, kontakt) sa v tej chvíli k ponuke uzamknú.

Stav, evidencia a zrušenie

• GET /v1/users/{identifier}/loan-offers/{offerReference} - stav (oprávnenie read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), dokončené lekcie, prax, kvíz (null, keď je vypnutý) a okamihy predloženia ponuky, potvrdenia a žiadosti o vysvetlenie. Nikdy odpovede, hodnoty ponuky ani odkaz. Dokončenie zostáva, aj keď ponuka neskôr vyprší.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - záznam pre váš spis (oprávnenie read): schemaVersion loan-guide-evidence/1, snímka vašej ponuky s odtlačkom snapshotSha256, vydanie kurzu s odtlačkami lekcií, udalosti v poradí sequence, každá odpoveď so všetkými pokusmi, potvrdenie a limitations - čo záznam nedokazuje (predložené neznamená prečítané, totožnosť tvrdíte vy, dokumenty iba odkazom, žiadny certifikát, žiadne schválenie pôžičky).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - zruší aktívnu ponuku (oprávnenie write), reasonCode = withdrawn_by_provider alebo application_closed; 200 vráti stav, ponuka, ktorá nie je aktívna alebo má dokončeného sprievodcu, vráti 409 notActive.

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= je potrebné, iba keď jedna offerReference patrí k viacerým žiadostiam profilu (inak 409 ambiguousOfferReference).

Webhooky sprievodcu

Webhook programu (pozri Webhooky) dostáva udalosti sprievodcu bez osobitného odberu. Podpis, doručenie a opakovanie sú rovnaké ako pri ostatných udalostiach; data nesú identifier, offerReference, externalApplicationId, guideStatus, occurredAt a sequence (poradie udalostí jednej ponuky) - nikdy evidenciu, hodnoty ponuky ani vstupný odkaz.

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
  }
}

Každá udalosť príde jednému webhooku najviac raz (kľúč idempotencie = X-Responsiblo-Delivery). Webhook založený neskôr staršie udalosti neprehráva a udalosti staršie ako 28 dní sa už neoznamujú.

Retencia evidencie

Keď cesta ponuky skončí (dokončená, zrušená, expirovaná alebo nahradená ponuka), beží doba uchovania z nastavení vášho sprievodcu (predvolene 30 dní). Potom sa evidencia zmaže: GET …/evidence vráti 410 evidenceErased a stav ďalej odpovedá s evidenceErased: true, referenciami a okamihmi. Aktívna ponuka sa nikdy nemaže. Evidenciu, ktorú musíte uchovať, si stiahnite hneď po loanGuide.completed.

Chyby sprievodcu

Chyby majú tvar API vyššie. Navyše pre sprievodcu:

Chyba nikdy neopakuje hodnotu, ktorú ste poslali. Príklad: rovnaká ponuka s platbou 10 700 CZK namiesto 10 800 CZK a platnosťou 9 dní:

"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"
  }
}

Limity

120 volaní za minútu na kľúč. Po 30 odmietnutých kľúčoch z jednej adresy počas desiatich minút adresa 10 minút čaká.

Log volaní (bez tiel, identifikátor iba ako odtlačok SHA-256) uchovávame 180 dní, doručené a vzdané správy webhookov 30 dní.

Stav a kontrakt

• GET /v1/status - bez kľúča, vracia {"status":"ok","version":"1.3.2"}
• GET /openapi - bez kľúča, dokument OpenAPI 3 partnerského API

Sandbox

Testovací kľúč rsb_test_... otvára váš testovací program s rovnakým kurzom. Osoby v ňom končia po 7 dňoch; webhook testovacieho programu je oddelený od produkčného.

História verzií

• 1.3.2 (2026-11) - Každá operácia dokumentu OpenAPI má názov a popis a operácie sú rozdelené do skupín. /v1/status a webhooky hlásia verziu 1.3.2. Tvary požiadaviek a odpovedí bez zmeny.
• 1.3.1 (2026-10) - Opravy bez zmeny endpointov a ich odpovedí.
• 1.3.0 (2026-10) - Sprievodca pôžičkou: POST /v1/users/{identifier}/loan-offers, stav, evidencia a zrušenie ponuky, webhooky loanGuide.*, retencia evidencie. Nepovinná adresa návratu returnUrl pri ponuke.
• 1.2.0 (2026-10) - GET /v1/users so stránkovaním, certifikát osoby (pole certificate, GET /v1/users/{identifier}/certificate, udalosť certificate.issued), DELETE /v1/users/{identifier} (anonymizácia), identifikátor najviac 64 znakov, retencia logu.
• 1.1.0 (2026-10) - API kľúče, POST /v1/users, GET /v1/users/{identifier} s ?include=detail, vstupný odkaz, webhooky, jeden tvar chýb, verejný stav a OpenAPI, limity.
• 1.0.0 (2024) - GET /v1/user/{identifier} s JWT partnerského kľúča.

Chcete API pre svoju firmu? Napíšte nám