Partnerski API

Kako deluje

API je za vse partnerje enak. V petih korakih:

1. API za vaše podjetje vklopimo; v svoji administraciji na zavihku API ustvarite API ključ.
2. Ko naj se stranka izobrazi, vaš sistem pokliče POST /v1/users z vašim identifikatorjem stranke.
3. Ustvarimo profil brez e-pošte in vrnemo vstopno povezavo (entryUrl); stranki jo prikažete kot gumb.
4. Stranka klikne nanjo in je takoj v tečaju.
5. Stanje kadar koli preberete prek GET /v1/users/{identifier}, ali pa ga vašemu strežniku sporočimo z webhookom.

Upravljavec identifikatorja ste vi, mi obdelujemo samo psevdonimizirane podatke. Kot identifikator nikoli ne pošiljajte e-pošte ali imena - e-poštni naslov API zavrne z napako 422.

Naslov in avtentikacija

Vsak klic gre prek HTTPS na spodnji naslov in nosi vaš API ključ v glavi Authorization.

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

• rsb_live_... odpre vaš produkcijski program, rsb_test_... vaš testni program (sandbox).
• Ključ se prikaže samo enkrat, ob ustvarjanju; shranimo samo njegov prstni odtis. Hranite ga kot skrivnost na svojem strežniku - nikoli v brskalniku ali aplikaciji.
• Ključ ima dovoljenja: read (stanje in seznam oseb, certifikat) in write (pošiljanje in anonimizacija oseb). Lahko je omejen na vaše naslove IP in ima lahko veljavnost.
• Zamenjava: ustvarite nov ključ, stari velja še 7 dni, nato poteče.
• Odgovori se nikoli ne shranjujejo v predpomnilnik (Cache-Control: no-store) in API ne sprejema klicev iz brskalnika (brez CORS).

POST /v1/users

Pošlje osebo v program ključa (dovoljenje 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 za novo osebo, 200 OK, ko identifikator že obstaja - nič se ne spremeni, klic je mogoče varno ponoviti. Telo je spodaj opisano stanje, vključno z entryUrl. Izčrpana omejitev oseb ali licenc programa vrne 403.

GET /v1/users/{identifier}

Stanje osebe (dovoljenje read): to, kar preverjanje skladnosti potrebuje, nič več.

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 rezultat zaključnega kviza v %, takoj ko je dokončan. Časi so v UTC na cele sekunde. Polje certificate vsebuje certifikat osebe (glejte spodaj); dokler ga oseba nima, je null.

?include=detail

Doda napredek v vsakem tečaju in rezultat vsakega kviza - nikoli posameznih odgovorov.

"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 oseb, ki ste jih poslali v program ključa (dovoljenje read), po straneh: vsaka postavka ima obliko zgoraj opisanega stanja. Neobvezno status (samo osebe v tem stanju), limit (od 1 do 500, privzeto 100) in 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"

• Nadaljujte s cursor = nextCursor, dokler nextCursor ni null; kazalec je neprozorno besedilo, nikoli ga ne sestavljajte sami.
• Osebe si sledijo po trenutku pošiljanja v stalnem vrstnem redu (tudi pri istem trenutku), nobena dvakrat; anonimiziranih oseb na seznamu ni.
• S filtrom status za eno stran pregledamo največ 2000 oseb, zato ima lahko stran manj postavk, kot je limit, tudi nobene - nadaljujte, dokler obstaja nextCursor.

Certifikat osebe

Takoj ko oseba dokonča program, ji tečaj izda certifikat - pod njenim psevdonimom (vzdevek profila ID XXXXXX), brez imena in brez e-pošte. Nič se ne pošilja po e-pošti; v stanju osebe je polje certificate s številko, časi in javno stranjo za preverjanje, PDF pa prenesete prek 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

• Stran za preverjanje verifyUrl prikaže samo psevdonim, program, partnerja in veljavnost - nikoli vašega identifikatorja.
• PDF vrne application/pdf (dovoljenje read). Brez certifikata je odgovor 404 certificateNotFound, ko se PDF še izdeluje, pa 404 certificatePdfNotReady z Retry-After.
• Preklican certifikat se nikoli ne izda (polje certificate je takrat null, PDF 404); certifikat s pretečeno veljavnostjo ostane resnično dokazilo in se izda.
• Webhook sporoči certifikat z dogodkom certificate.issued (takoj po user.completed).

DELETE /v1/users/{identifier}

Anonimizira osebo (dovoljenje write): iz profila izginejo vaš identifikator, oznaka in vsako sporočilo webhooka, ki ga navaja; vstopne povezave prenehajo veljati. Certifikat in rezultat tečaja ostaneta pod številko certifikata - kot dokazilo o skladnosti.

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

HTTP/1.1 204 No Content

Odgovor 204 brez telesa; vsak nadaljnji klic z istim identifikatorjem vrne 404 userNotFound, zato je ponavljanje varno. Isti identifikator lahko nato znova pošljete kot novo osebo.

Vstopna povezava

entryUrl prikažite osebi (gumb Zaženi tečaj v vašem sistemu). Prijavi jo v tečaj - brez e-pošte in brez gesla.

Povezava velja 30 dni in jo je mogoče uporabiti večkrat; vsak klic GET /v1/users/{identifier} vrne novo. Nikoli je ne pošiljajte nikomur drugemu: kdor ima povezavo, vstopi kot ta oseba.

Webhooki

Na zavihku API svoje administracije nastavite en webhook za vsak program: javni naslov HTTPS svojega strežnika in dogodke. Nato vam pošiljamo POST z JSON - samo identifikatorje in stanja, nikoli vstopne povezave.

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

Vsako sporočilo nosi glavo X-Responsiblo-Signature: t=<čas Unix>,v1=<HMAC-SHA256 besedila t.telo s skrivnostjo webhooka, hex>. Skrivnost (whsec_...) se prikaže enkrat ob ustvarjanju webhooka. Preden sporočilu zaupate, preverite podpis in starost t; kot ključ idempotence uporabite 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]);

Dostava in ponovni poskusi

Dostavljeno = odgovor 2xx v 10 sekundah. Sicer poskusimo znova čez 1 minuto, 5 minut, 30 minut, 2 uri in 12 ur, nato odnehamo. Preusmeritvam ne sledimo.

20 nedostavljenih sporočil zapored webhook izklopi, dokler ga znova ne vklopite; sporočila iz tega časa počakajo. Gumb Test pošlje ping; dnevnik dostav najdete v svoji administraciji.

Dogodek certificate.issued dodate webhooku v njegovih nastavitvah; webhook, ustvarjen pred različico 1.2, ga sam ne prejema.

Napake

Vsaka napaka ima eno obliko: status, code, reason in message; napaka 422 doda errors (polje - kaj je narobe).

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

Za programe in agente

• Odločajte se po code in reason, nikoli po besedilu message; errors je objekt polje -> kaj je narobe.
• Ponavljajte samo 429, 500 in certificatePdfNotReady, in to po Retry-After sekundah (sicer z naraščajočim razmikom); drugih 4xx razen 429 brez popravka klica ne ponavljajte.
• POST /v1/users je idempotenten po identifier (201 prvič, nato 200); DELETE vrne 204 prvič in 404 pozneje - oboje je mogoče varno ponavljati.
• Webhooke deduplicirajte po X-Responsiblo-Delivery; vrstni red sporočil ni zagotovljen, odloča stanje v data.

Vodnik po posojilu

Vodnik po posojilu je kratek tečaj za prosilca pri ponudniku posojila: pred podpisom pogodbe opravi tri lekcije, osem praktičnih situacij in, če je vklopljen, kviz, vse na številkah svoje ponudbe, na koncu pa ponudbo potrdi. Na vsakem zaslonu lahko prosi za pojasnilo. Ponudbo pošljete prek API-ja, dobite vstopno povezavo, rezultat pa vam sporoči webhook.

Vodnik po posojilu aktiviramo po dogovoru z vami.

Prosilec je tudi tu samo vaš psevdonimni profil iz POST /v1/users. Ponudbo določajo vaše reference (externalApplicationId, offerReference), dokumente pa samo povezava s prstnim odtisom SHA-256 - nikoli ime, e-pošta, EMŠO, številka računa ali telefon. responsiblo posojila ne odobrava, dokumentov ne prenaša in ne shranjuje, istovetnosti ne preverja in za vodnik ne izdaja certifikata.

1. Ustvarite profil prosilca: POST /v1/users z vašim psevdonimom.
2. Pošljite ponudbo: POST /v1/users/{identifier}/loan-offers; odgovor 201 vsebuje entryUrl.
3. entryUrl predate prosilcu po svojem preverjenem kanalu. Povezava velja 30 dni in jo je mogoče uporabiti večkrat; vodnik prikaže številke prav te ponudbe.
4. Konec izveste prek webhooka (loanGuide.completed, loanGuide.assistanceRequested in drugi).
5. Stanje preberete prek GET …/loan-offers/{offerReference}, zapis za svoj spis prek GET …/evidence. Spremenjena ponudba = nova ponudba s supersedes, umaknjen zahtevek = POST …/cancel.

Do aktivacije operacije vodnika odgovorijo 404 notFound ali 409 loanGuideNotConfigured. Dovoljenje write pošlje in prekliče ponudbo, read prebere stanje in evidenco.

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

Pošlje ponudbo k profilu prosilca (dovoljenje write). Neobvezna glava Idempotency-Key ima od 1 do 255 vidnih znakov ASCII. Primer: posojilo 10.000 CZK, za plačilo 10.800 CZK v enkratnem plačilu 30 dni po izplačilu, EOM 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"
}

Enako telo znova (pod enakimi referencami ali enakim Idempotency-Key) vrne 200 z obstoječo ponudbo in novim entryUrl; drugačno telo pod njimi vrne 409 offerConflict. Profil ima eno aktivno ponudbo: naslednja brez supersedes vrne 409 activeOfferExists, napačen supersedes 409 notSupersedable. Nastavitve vašega vodnika (kviz, kontakt) se v tistem trenutku zaklenejo k ponudbi.

Stanje, evidenca in preklic

• GET /v1/users/{identifier}/loan-offers/{offerReference} - stanje (dovoljenje read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), dokončane lekcije, praksa, kviz (null, ko je izklopljen) in trenutki predložitve ponudbe, potrditve in prošnje za pojasnilo. Nikoli odgovori, vrednosti ponudbe ali povezava. Dokončanje ostane, tudi če ponudba pozneje poteče.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - zapis za vaš spis (dovoljenje read): schemaVersion loan-guide-evidence/1, posnetek vaše ponudbe s prstnim odtisom snapshotSha256, izdaja tečaja s prstnimi odtisi lekcij, dogodki v vrstnem redu sequence, vsak odgovor z vsemi poskusi, potrditev in limitations - česa zapis ne dokazuje (predloženo ne pomeni prebrano, istovetnost trdite vi, dokumenti samo s povezavo, noben certifikat, nobena odobritev posojila).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - prekliče aktivno ponudbo (dovoljenje write), reasonCode = withdrawn_by_provider ali application_closed; 200 vrne stanje, ponudba, ki ni aktivna ali ima dokončan vodnik, vrne 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 potreben samo, ko ena offerReference pripada več zahtevkom profila (sicer 409 ambiguousOfferReference).

Webhooki vodnika

Webhook programa (glejte Webhooki) prejema dogodke vodnika brez posebne naročnine. Podpis, dostava in ponavljanje so enaki kot pri drugih dogodkih; data vsebujejo identifier, offerReference, externalApplicationId, guideStatus, occurredAt in sequence (vrstni red dogodkov ene ponudbe) - nikoli evidence, vrednosti ponudbe ali vstopne povezave.

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

Vsak dogodek pride do enega webhooka največ enkrat (ključ idempotence = X-Responsiblo-Delivery). Webhook, ustvarjen pozneje, starejših dogodkov ne predvaja, dogodki, starejši od 28 dni, pa se ne sporočajo več.

Hramba evidence

Ko se pot ponudbe konča (dokončana, preklicana, potekla ali nadomeščena ponudba), teče hramba iz nastavitev vašega vodnika (privzeto 30 dni). Nato se evidenca izbriše: GET …/evidence vrne 410 evidenceErased, stanje pa še naprej odgovarja z evidenceErased: true, referencami in trenutki. Aktivna ponudba se nikoli ne izbriše. Evidenco, ki jo morate hraniti, prenesite takoj po loanGuide.completed.

Napake vodnika

Napake imajo obliko API-ja zgoraj. Dodatno za vodnik:

Napaka nikoli ne ponovi vrednosti, ki ste jo poslali. Primer: enaka ponudba s plačilom 10.700 CZK namesto 10.800 CZK in veljavnostjo 9 dni:

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

Omejitve

120 klicev na minuto na ključ. Po 30 zavrnjenih ključih z enega naslova v desetih minutah naslov čaka 10 minut.

Dnevnik klicev (brez teles, identifikator samo kot prstni odtis SHA-256) hranimo 180 dni, dostavljena in opuščena sporočila webhookov 30 dni.

Stanje in pogodba

• GET /v1/status - brez ključa, vrne {"status":"ok","version":"1.3.2"}
• GET /openapi - brez ključa, dokument OpenAPI 3 partnerskega API-ja

Sandbox

Testni ključ rsb_test_... odpre vaš testni program z istim tečajem. Osebe v njem končajo po 7 dneh; webhook testnega programa je ločen od produkcijskega.

Zgodovina različic

• 1.3.2 (2026-11) - Vsaka operacija dokumenta OpenAPI ima ime in opis, operacije pa so razdeljene v skupine. /v1/status in webhooki sporočajo različico 1.3.2. Oblika zahtev in odgovorov ostaja nespremenjena.
• 1.3.1 (2026-10) - Popravki brez spremembe končnih točk in njihovih odgovorov.
• 1.3.0 (2026-10) - Vodnik po posojilu: POST /v1/users/{identifier}/loan-offers, stanje, evidenca in preklic ponudbe, webhooki loanGuide.*, hramba evidence. Neobvezno polje returnUrl ponudbe (lasten naslov za vrnitev).
• 1.2.0 (2026-10) - GET /v1/users s straničenjem, certifikat osebe (polje certificate, GET /v1/users/{identifier}/certificate, dogodek certificate.issued), DELETE /v1/users/{identifier} (anonimizacija), identifikator največ 64 znakov, hramba dnevnika.
• 1.1.0 (2026-10) - API ključi, POST /v1/users, GET /v1/users/{identifier} z ?include=detail, vstopna povezava, webhooki, ena oblika napak, javno stanje in OpenAPI, omejitve.
• 1.0.0 (2024) - GET /v1/user/{identifier} z JWT partnerskega ključa.

Želite API za svoje podjetje? Pišite nam