Partnerské API

Jak to funguje

API je pro všechny partnery stejné. V pěti krocích:

1. API vám pro firmu zapneme; ve své administraci si v záložce API vytvoříte API klíč.
2. Když se má klient proškolit, váš systém zavolá POST /v1/users s vaším identifikátorem klienta.
3. Založíme profil bez e-mailu a vrátíme vstupní odkaz (entryUrl); ten klientovi ukážete jako tlačítko.
4. Klient na něj klikne a je rovnou v kurzu.
5. Stav si kdykoli přečtete přes GET /v1/users/{identifier}, nebo ho vašemu serveru oznámíme webhookem.

Správcem identifikátoru jste vy, my zpracováváme jen pseudonymní data. Jako identifikátor nikdy neposílejte e-mail ani jméno - e-mailovou adresu API odmítne chybou 422.

Adresa a autentizace

Každé volání jde přes HTTPS na adresu níže a nese váš API klíč v hlavičce Authorization.

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

• rsb_live_... otevírá váš produkční program, rsb_test_... váš testovací program (sandbox).
• Klíč se ukáže jen jednou, při vytvoření; ukládáme si jen jeho otisk. Mějte ho jako tajemství na svém serveru - nikdy v prohlížeči ani v aplikaci.
• Klíč má oprávnění: read (stav a seznam osob, certifikát) a write (posílání a anonymizace osob). Může být omezený na vaše IP adresy a mít platnost.
• Výměna: vytvoříte nový klíč, starý platí ještě 7 dní, pak vyprší.
• Odpovědi se nikdy neukládají do mezipaměti (Cache-Control: no-store) a API nepřijímá volání z prohlížeče (bez CORS).

POST /v1/users

Pošle osobu do programu klíče (oprávnění 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 pro novou osobu, 200 OK, když identifikátor už existuje - nic se nemění, volání lze bezpečně opakovat. Tělo je stav níže i s entryUrl. Vyčerpaný limit osob nebo licence programu vrací 403.

GET /v1/users/{identifier}

Stav osoby (oprávnění read): to, co compliance check potřebuje, nic navíc.

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ýsledek závěrečného kvízu v %, jakmile je dokončený. Časy jsou v UTC na celé sekundy. Pole certificate nese certifikát osoby (viz níže), dokud ho nemá, je null.

?include=detail

Přidá postup v každém kurzu a výsledek každého kvízu - nikdy jednotlivé odpovědi.

"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

Seznam osob, které jste poslali do programu klíče (oprávnění read), po stránkách: každá položka má tvar stavu výše. Volitelně status (jen osoby v tomto stavu), limit (1 až 500, výchozí 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, dokud nextCursor není null; kurzor je neprůhledný text, nikdy ho neskládejte sami.
• Osoby jdou podle okamžiku poslání ve stálém pořadí (i při stejném okamžiku), žádná dvakrát; anonymizované osoby v seznamu nejsou.
• S filtrem status projdeme pro jednu stránku nejvýš 2000 osob, stránka proto může mít méně položek než limit, i žádnou - pokračujte, dokud je nextCursor.

Certifikát osoby

Jakmile osoba program dokončí, vydá jí kurz certifikát - pod jejím pseudonymem (přezdívka profilu ID XXXXXX), bez jména a bez e-mailu. Nic se neposílá e-mailem; ve stavu osoby je pole certificate s číslem, časy a veřejnou ověřovací stránkou a PDF si stáhnete přes 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

• Ověřovací stránka verifyUrl ukáže jen pseudonym, program, partnera a platnost - nikdy váš identifikátor.
• PDF vrací application/pdf (oprávnění read). Bez certifikátu odpověď 404 certificateNotFound, když se PDF teprve vyrábí, 404 certificatePdfNotReady s Retry-After.
• Zrušený certifikát se nikdy nevydá (pole certificate je pak null, PDF 404); certifikát s uplynulou platností zůstává pravdivým dokladem a vydá se.
• Webhook oznámí certifikát událostí certificate.issued (hned po user.completed).

DELETE /v1/users/{identifier}

Anonymizuje osobu (oprávnění write): z profilu zmizí váš identifikátor, štítek a každá zpráva webhooku, která ho jmenuje; vstupní odkazy přestanou platit. Certifikát a výsledek kurzu zůstanou pod číslem certifikátu - jako compliance doklad.

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

HTTP/1.1 204 No Content

Odpověď 204 bez těla; každé další volání téhož identifikátoru vrátí 404 userNotFound, opakování je tedy bezpečné. Stejný identifikátor pak můžete poslat znovu jako novou osobu.

Vstupní odkaz

entryUrl ukažte osobě (tlačítko Spustit kurz ve vašem systému). Přihlásí ji do kurzu - bez e-mailu a bez hesla.

Odkaz platí 30 dní a lze ho použít opakovaně; každé volání GET /v1/users/{identifier} vrátí nový. Nikdy ho neposílejte nikomu jinému: kdo odkaz má, vstoupí jako ta osoba.

Webhooky

V záložce API své administrace nastavíte jeden webhook pro každý program: veřejnou HTTPS adresu svého serveru a události. Pak vám posíláme POST s JSON - jen 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á zpráva nese hlavičku X-Responsiblo-Signature: t=<unixový čas>,v1=<HMAC-SHA256 textu t.tělo s tajemstvím webhooku, hex>. Tajemství (whsec_...) se ukáže jednou při vytvoření webhooku. Než zprávě uvěříte, ověřte podpis i stáří t; jako klíč idempotence použijte 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čení a opakování

Doručeno = odpověď 2xx do 10 sekund. Jinak to zkusíme znovu za 1 minutu, 5 minut, 30 minut, 2 hodiny a 12 hodin, pak to vzdáme. Přesměrování nesledujeme.

20 nedoručených zpráv po sobě webhook vypne, dokud ho znovu nezapnete; zprávy z té doby počkají. Tlačítko Otestovat pošle ping; log doručení najdete ve své administraci.

Událost certificate.issued přidáte webhooku v jeho nastavení; webhook založený před verzí 1.2 ji sám nedostává.

Chyby

Každá chyba má jeden tvar: status, code, reason a message; chyba 422 přidá errors (pole - co je špatně).

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

Pro programy a agenty

• Rozhodujte podle code a reason, nikdy podle textu message; errors je objekt pole -> co je špatně.
• Opakujte jen 429, 500 a certificatePdfNotReady, a to po Retry-After sekundách (jinak s rostoucím odstupem); 4xx kromě 429 bez opravy volání neopakujte.
• POST /v1/users je idempotentní podle identifier (201 poprvé, pak 200); DELETE vrátí 204 poprvé a 404 potom - obojí lze bezpečně opakovat.
• Webhook dedupujte podle X-Responsiblo-Delivery; pořadí zpráv není zaručené, rozhoduje stav v data.

Průvodce půjčkou

Průvodce půjčkou je krátký kurz pro žadatele u poskytovatele půjčky: před podpisem smlouvy projde tři lekce, osm praktických situací a případně kvíz, vše nad čísly své vlastní nabídky, a na konci nabídku potvrdí. Na každé obrazovce může požádat o vysvětlení. Nabídku pošlete přes API, dostanete vstupní odkaz a výsledek vám oznámí webhook.

Průvodce půjčkou aktivujeme po dohodě s vámi.

Žadatel je i tady jen váš pseudonymní profil z POST /v1/users. Nabídku určují vaše reference (externalApplicationId, offerReference) a dokumenty jen odkaz s otiskem SHA-256 - nikdy jméno, e-mail, rodné číslo, číslo účtu ani telefon. responsiblo půjčku neschvaluje, dokumenty nestahuje ani neukládá, totožnost neověřuje a k průvodci nevydává certifikát.

1. Založíte profil žadatele: POST /v1/users s vaším pseudonymem.
2. Pošlete nabídku: POST /v1/users/{identifier}/loan-offers; odpověď 201 nese entryUrl.
3. entryUrl předáte žadateli svým ověřeným kanálem. Odkaz platí 30 dní a lze ho použít opakovaně; průvodce ukáže čísla jeho nabídky.
4. Konec se dozvíte webhookem (loanGuide.completed, loanGuide.assistanceRequested a další).
5. Stav si přečtete přes GET …/loan-offers/{offerReference}, záznam pro svůj spis přes GET …/evidence. Změněná nabídka = nová nabídka se supersedes, stažená žádost = POST …/cancel.

Do aktivace odpovídají operace průvodce 404 notFound nebo 409 loanGuideNotConfigured. Oprávnění write posílá a ruší nabídku, read čte stav a evidenci.

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

Pošle nabídku k profilu žadatele (oprávnění write). Volitelná hlavička Idempotency-Key má 1 až 255 viditelných znaků ASCII. Příklad: půjčka 10 000 Kč, k zaplacení 10 800 Kč jednou platbou 30 dní po výplatě, RPSN 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"
}

Stejné tělo znovu (pod stejnými referencemi nebo stejným Idempotency-Key) vrátí 200 s existující nabídkou a novým entryUrl; jiné tělo pod nimi vrátí 409 offerConflict. Profil má jednu aktivní nabídku: další bez supersedes vrátí 409 activeOfferExists, chybné supersedes 409 notSupersedable. Nastavení vašeho průvodce (kvíz, kontakt) se v tu chvíli k nabídce uzamkne.

Stav, evidence a zrušení

• GET /v1/users/{identifier}/loan-offers/{offerReference} - stav (oprávnění read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), dokončené lekce, praxe, kvíz (null, když je vypnutý) a okamžiky předložení nabídky, potvrzení a žádosti o vysvětlení. Nikdy odpovědi, hodnoty nabídky ani odkaz. Dokončení zůstává, i když nabídka později vyprší.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - záznam pro váš spis (oprávnění read): schemaVersion loan-guide-evidence/1, snímek vaší nabídky s otiskem snapshotSha256, vydání kurzu s otisky lekcí, události v pořadí sequence, každá odpověď se všemi pokusy, potvrzení a limitations - co záznam nedokazuje (předloženo neznamená přečteno, totožnost tvrdíte vy, dokumenty jen odkazem, žádný certifikát, žádné schválení půjčky).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - zruší aktivní nabídku (oprávnění write), reasonCode = withdrawn_by_provider nebo application_closed; 200 vrátí stav, nabídka, která není aktivní nebo má dokončeného průvodce, vrátí 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 potřeba, jen když jedna offerReference patří k více žádostem profilu (jinak 409 ambiguousOfferReference).

Webhooky průvodce

Webhook programu (viz Webhooky) dostává události průvodce bez zvláštního odběru. Podpis, doručení a opakování jsou stejné jako u ostatních událostí; data nesou identifier, offerReference, externalApplicationId, guideStatus, occurredAt a sequence (pořadí událostí jedné nabídky) - nikdy evidenci, hodnoty nabídky 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á událost přijde jednomu webhooku nejvýš jednou (klíč idempotence = X-Responsiblo-Delivery). Webhook založený později starší události nepřehrává a události starší 28 dní se už neoznamují.

Retence evidence

Když cesta nabídky skončí (dokončená, zrušená, expirovaná nebo nahrazená nabídka), běží doba uchování z nastavení vašeho průvodce (výchozí 30 dní). Pak se evidence smaže: GET …/evidence vrátí 410 evidenceErased a stav dál odpovídá s evidenceErased: true, referencemi a okamžiky. Aktivní nabídka se nikdy nemaže. Evidenci, kterou musíte uchovat, si stáhněte hned po loanGuide.completed.

Chyby průvodce

Chyby mají tvar API výše. Navíc pro průvodce:

Chyba nikdy neopakuje hodnotu, kterou jste poslali. Příklad: stejná nabídka s platbou 10 700 Kč místo 10 800 Kč a platností 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 volání za minutu na klíč. Po 30 odmítnutých klíčích z jedné adresy během deseti minut adresa 10 minut čeká.

Log volání (bez těl, identifikátor jen jako otisk SHA-256) uchováváme 180 dní, doručené a vzdané zprávy webhooků 30 dní.

Stav a kontrakt

• GET /v1/status - bez klíče, vrací {"status":"ok","version":"1.3.2"}
• GET /openapi - bez klíče, dokument OpenAPI 3 partnerského API

Sandbox

Testovací klíč rsb_test_... otevírá váš testovací program se stejným kurzem. Osoby v něm končí po 7 dnech; webhook testovacího programu je oddělený od produkčního.

Historie verzí

• 1.3.2 (2026-11) - Každá operace dokumentu OpenAPI má název a popis a operace jsou rozdělené do skupin. /v1/status a webhooky hlásí verzi 1.3.2. Tvary požadavků a odpovědí beze změny.
• 1.3.1 (2026-10) - Opravy bez změny endpointů a jejich odpovědí.
• 1.3.0 (2026-10) - Průvodce půjčkou: POST /v1/users/{identifier}/loan-offers, stav, evidence a zrušení nabídky, webhooky loanGuide.*, retence evidence. Nepovinná adresa návratu returnUrl u nabídky.
• 1.2.0 (2026-10) - GET /v1/users se stránkováním, certifikát osoby (pole certificate, GET /v1/users/{identifier}/certificate, událost certificate.issued), DELETE /v1/users/{identifier} (anonymizace), identifikátor nejvýš 64 znaků, retence logu.
• 1.1.0 (2026-10) - API klíče, POST /v1/users, GET /v1/users/{identifier} s ?include=detail, vstupní odkaz, webhooky, jeden tvar chyb, veřejný stav a OpenAPI, limity.
• 1.0.0 (2024) - GET /v1/user/{identifier} s JWT partnerského klíče.

Chcete API pro svou firmu? Napište nám