Partnerski API

Kako to funkcionira

API je isti za sve partnere. U pet koraka:

1. Uključimo API za Vaše poduzeće; u svojoj administraciji u kartici API izradite API ključ.
2. Kada klijent treba proći edukaciju, Vaš sustav poziva POST /v1/users s Vašim identifikatorom klijenta.
3. Izradimo profil bez e-pošte i vratimo ulaznu poveznicu (entryUrl); nju klijentu prikažete kao gumb.
4. Klijent klikne na nju i odmah je u tečaju.
5. Stanje u bilo kojem trenutku očitate putem GET /v1/users/{identifier} ili ga Vašem poslužitelju javimo webhookom.

Voditelj obrade identifikatora ste Vi, mi obrađujemo samo pseudonimizirane podatke. Kao identifikator nikada ne šaljite e-poštu ni ime - adresu e-pošte API odbija pogreškom 422.

Adresa i autentifikacija

Svaki poziv ide preko HTTPS-a na adresu u nastavku i nosi Vaš API ključ u zaglavlju Authorization.

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

• rsb_live_... otvara Vaš produkcijski program, rsb_test_... Vaš testni program (sandbox).
• Ključ se prikazuje samo jednom, pri izradi; pohranjujemo samo njegov otisak. Čuvajte ga kao tajnu na svom poslužitelju - nikada u pregledniku ni u aplikaciji.
• Ključ ima ovlasti: read (stanje i popis osoba, certifikat) i write (slanje i anonimizacija osoba). Može biti ograničen na Vaše IP adrese i imati rok valjanosti.
• Zamjena: izradite novi ključ, stari vrijedi još 7 dana, a zatim istječe.
• Odgovori se nikada ne spremaju u predmemoriju (Cache-Control: no-store) i API ne prihvaća pozive iz preglednika (bez CORS-a).

POST /v1/users

Šalje osobu u program ključa (ovlast 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 novu osobu, 200 OK kada identifikator već postoji - ništa se ne mijenja, poziv se može sigurno ponoviti. Tijelo je stanje opisano u nastavku, zajedno s entryUrl. Iscrpljeno ograničenje broja osoba ili licencija programa vraća 403.

GET /v1/users/{identifier}

Stanje osobe (ovlast read): ono što provjera usklađenosti treba, ništa viš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 rezultat završnog kviza u %, čim je završen. Vremena su u UTC-u na cijele sekunde. Polje certificate nosi certifikat osobe (vidi u nastavku); dok ga osoba nema, vrijednost je null.

?include=detail

Dodaje napredak u svakom tečaju i rezultat svakog kviza - nikada pojedinačne odgovore.

"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

Popis osoba koje ste poslali u program ključa (ovlast read), po stranicama: svaka stavka ima oblik stanja opisanog gore. Neobavezno status (samo osobe u tom stanju), limit (od 1 do 500, zadano 100) i 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"

• Nastavite s cursor = nextCursor dok nextCursor nije null; kursor je neproziran tekst, nikada ga ne sastavljajte sami.
• Osobe dolaze prema trenutku slanja stalnim redoslijedom (i pri istom trenutku), nijedna dvaput; anonimizirane osobe nisu na popisu.
• S filtrom status za jednu stranicu pregledavamo najviše 2000 osoba, pa stranica može imati manje stavki nego limit, pa i nijednu - nastavite dok postoji nextCursor.

Certifikat osobe

Čim osoba završi program, tečaj joj izdaje certifikat - pod njezinim pseudonimom (nadimak profila ID XXXXXX), bez imena i bez e-pošte. Ništa se ne šalje e-poštom; u stanju osobe nalazi se polje certificate s brojem, vremenima i javnom stranicom za provjeru, a PDF preuzimate putem 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

• Stranica za provjeru verifyUrl prikazuje samo pseudonim, program, partnera i valjanost - nikada Vaš identifikator.
• PDF vraća application/pdf (ovlast read). Bez certifikata odgovor je 404 certificateNotFound, a dok se PDF još izrađuje, 404 certificatePdfNotReady s Retry-After.
• Opozvani certifikat nikada se ne izdaje (polje certificate je tada null, PDF 404); certifikat kojemu je istekla valjanost ostaje istinit dokaz i izdaje se.
• Webhook javlja certifikat događajem certificate.issued (odmah nakon user.completed).

DELETE /v1/users/{identifier}

Anonimizira osobu (ovlast write): iz profila nestaju Vaš identifikator, oznaka i svaka poruka webhooka koja ga navodi; ulazne poveznice prestaju vrijediti. Certifikat i rezultat tečaja ostaju pod brojem certifikata - kao dokaz usklađenosti.

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

HTTP/1.1 204 No Content

Odgovor 204 bez tijela; svaki sljedeći poziv s istim identifikatorom vraća 404 userNotFound, pa je ponavljanje sigurno. Isti identifikator zatim možete ponovno poslati kao novu osobu.

Ulazna poveznica

Prikažite entryUrl osobi (gumb Pokreni tečaj u Vašem sustavu). Prijavljuje je u tečaj - bez e-pošte i bez lozinke.

Poveznica vrijedi 30 dana i može se koristiti više puta; svaki poziv GET /v1/users/{identifier} vraća novu. Nikada je ne šaljite nikome drugome: tko ima poveznicu, ulazi kao ta osoba.

Webhookovi

U kartici API svoje administracije postavljate jedan webhook za svaki program: javnu HTTPS adresu svog poslužitelja i događaje. Nakon toga Vam šaljemo POST s JSON-om - samo identifikatore i stanja, nikada ulaznu poveznicu.

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

Potpis

Svaka poruka nosi zaglavlje X-Responsiblo-Signature: t=<Unix vrijeme>,v1=<HMAC-SHA256 teksta t.tijelo s tajnom webhooka, hex>. Tajna (whsec_...) prikazuje se jednom pri izradi webhooka. Prije nego što povjerujete poruci, provjerite potpis i starost t; kao ključ idempotencije koristite 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]);

Isporuka i ponavljanje

Isporučeno = odgovor 2xx unutar 10 sekundi. Inače pokušavamo ponovno nakon 1 minute, 5 minuta, 30 minuta, 2 sata i 12 sati, a zatim odustajemo. Preusmjeravanja ne slijedimo.

20 neisporučenih poruka zaredom isključuje webhook dok ga ponovno ne uključite; poruke iz tog razdoblja čekaju. Gumb Test šalje ping; zapisnik isporuka nalazite u svojoj administraciji.

Događaj certificate.issued dodajete webhooku u njegovim postavkama; webhook izrađen prije verzije 1.2 ne dobiva ga sam od sebe.

Pogreške

Svaka pogreška ima jedan oblik: status, code, reason i message; pogreška 422 dodaje errors (polje - što nije u redu).

{ "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 i agente

• Odlučujte prema code i reason, nikada prema tekstu message; errors je objekt polje -> što nije u redu.
• Ponavljajte samo 429, 500 i certificatePdfNotReady, i to nakon Retry-After sekundi (inače s rastućim razmakom); ostale 4xx osim 429 ne ponavljajte bez ispravka poziva.
• POST /v1/users idempotentan je prema identifier (201 prvi put, zatim 200); DELETE vraća 204 prvi put, a zatim 404 - oboje se može sigurno ponavljati.
• Webhookove deduplicirajte prema X-Responsiblo-Delivery; redoslijed poruka nije zajamčen, odlučuje stanje u data.

Vodič kroz kredit

Vodič kroz kredit kratki je tečaj za podnositelja zahtjeva kod davatelja kredita: prije potpisivanja ugovora prolazi tri lekcije, osam praktičnih situacija i, ako je uključen, kviz, sve nad brojkama vlastite ponude, a na kraju ponudu potvrđuje. Na svakom zaslonu može zatražiti objašnjenje. Ponudu šaljete putem API-ja, dobivate ulaznu poveznicu, a rezultat Vam javlja webhook.

Vodič kroz kredit aktiviramo u dogovoru s Vama.

Podnositelj zahtjeva i ovdje je samo Vaš pseudonimni profil iz POST /v1/users. Ponudu određuju Vaše reference (externalApplicationId, offerReference), a dokumente samo poveznica s otiskom SHA-256 - nikada ime, e-pošta, osobni identifikacijski broj, broj računa ni telefon. responsiblo kredit ne odobrava, dokumente ne preuzima niti pohranjuje, identitet ne provjerava i za vodič ne izdaje certifikat.

1. Izradite profil podnositelja zahtjeva: POST /v1/users s Vašim pseudonimom.
2. Pošaljite ponudu: POST /v1/users/{identifier}/loan-offers; odgovor 201 nosi entryUrl.
3. entryUrl predajete podnositelju zahtjeva vlastitim provjerenim kanalom. Poveznica vrijedi 30 dana i može se koristiti više puta; vodič prikazuje brojke upravo te ponude.
4. Kraj saznajete webhookom (loanGuide.completed, loanGuide.assistanceRequested i drugi).
5. Stanje očitavate putem GET …/loan-offers/{offerReference}, zapis za svoj spis putem GET …/evidence. Izmijenjena ponuda = nova ponuda sa supersedes, povučeni zahtjev = POST …/cancel.

Do aktivacije operacije vodiča odgovaraju 404 notFound ili 409 loanGuideNotConfigured. Ovlast write šalje i otkazuje ponudu, read očitava stanje i evidenciju.

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

Šalje ponudu uz profil podnositelja zahtjeva (ovlast write). Neobavezno zaglavlje Idempotency-Key ima od 1 do 255 vidljivih ASCII znakova. Primjer: kredit od 10.000 CZK, za plaćanje 10.800 CZK jednokratnom uplatom 30 dana nakon isplate, EKS 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"
}

Isto tijelo ponovno (pod istim referencama ili istim Idempotency-Key) vraća 200 s postojećom ponudom i novim entryUrl; drugačije tijelo pod njima vraća 409 offerConflict. Profil ima jednu aktivnu ponudu: sljedeća bez supersedes vraća 409 activeOfferExists, pogrešan supersedes 409 notSupersedable. Postavke Vašeg vodiča (kviz, kontakt) u tom se trenutku zaključavaju uz ponudu.

Stanje, evidencija i otkazivanje

• GET /v1/users/{identifier}/loan-offers/{offerReference} - stanje (ovlast read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), završene lekcije, praksa, kviz (null kada je isključen) i trenuci predočenja ponude, potvrde i zahtjeva za objašnjenjem. Nikada odgovori, vrijednosti ponude ni poveznica. Završetak ostaje i kada ponuda kasnije istekne.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - zapis za Vaš spis (ovlast read): schemaVersion loan-guide-evidence/1, snimka Vaše ponude s otiskom snapshotSha256, izdanje tečaja s otiscima lekcija, događaji redoslijedom sequence, svaki odgovor sa svim pokušajima, potvrda i limitations - što zapis ne dokazuje (predočeno ne znači pročitano, identitet tvrdite Vi, dokumenti samo poveznicom, nikakav certifikat, nikakvo odobrenje kredita).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - otkazuje aktivnu ponudu (ovlast write), reasonCode = withdrawn_by_provider ili application_closed; 200 vraća stanje, ponuda koja nije aktivna ili ima završen vodič vraća 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= potreban je samo kada jedna offerReference pripada više zahtjeva profila (inače 409 ambiguousOfferReference).

Webhookovi vodiča

Webhook programa (vidi Webhookovi) prima događaje vodiča bez posebne pretplate. Potpis, isporuka i ponavljanje isti su kao kod ostalih događaja; data nose identifier, offerReference, externalApplicationId, guideStatus, occurredAt i sequence (redoslijed događaja jedne ponude) - nikada evidenciju, vrijednosti ponude ni ulaznu poveznicu.

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

Svaki događaj stiže jednom webhooku najviše jednom (ključ idempotencije = X-Responsiblo-Delivery). Webhook izrađen kasnije ne reproducira starije događaje, a događaji stariji od 28 dana više se ne javljaju.

Čuvanje evidencije

Kada put ponude završi (završena, otkazana, istekla ili zamijenjena ponuda), teče razdoblje čuvanja iz postavki Vašeg vodiča (zadano 30 dana). Zatim se evidencija briše: GET …/evidence vraća 410 evidenceErased, a stanje i dalje odgovara s evidenceErased: true, referencama i trenucima. Aktivna ponuda nikada se ne briše. Evidenciju koju morate čuvati preuzmite odmah nakon loanGuide.completed.

Pogreške vodiča

Pogreške imaju oblik API-ja opisan gore. Dodatno za vodič:

Pogreška nikada ne ponavlja vrijednost koju ste poslali. Primjer: ista ponuda s uplatom od 10.700 CZK umjesto 10.800 CZK i valjanošću od 9 dana:

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

Ograničenja

120 poziva u minuti po ključu. Nakon 30 odbijenih ključeva s jedne adrese unutar deset minuta adresa čeka 10 minuta.

Zapisnik poziva (bez tijela, identifikator samo kao otisak SHA-256) čuvamo 180 dana, isporučene i napuštene poruke webhookova 30 dana.

Stanje i ugovor

• GET /v1/status - bez ključa, vraća {"status":"ok","version":"1.3.2"}
• GET /openapi - bez ključa, dokument OpenAPI 3 partnerskog API-ja

Sandbox

Testni ključ rsb_test_... otvara Vaš testni program s istim tečajem. Osobe u njemu završavaju nakon 7 dana; webhook testnog programa odvojen je od produkcijskog.

Povijest verzija

• 1.3.2 (2026-11) - Svaka operacija dokumenta OpenAPI ima naziv i opis, a operacije su razvrstane u skupine. /v1/status i webhookovi javljaju verziju 1.3.2. Oblik zahtjeva i odgovora ostaje nepromijenjen.
• 1.3.1 (2026-10) - Ispravci bez promjene endpointa i njihovih odgovora.
• 1.3.0 (2026-10) - Vodič kroz kredit: POST /v1/users/{identifier}/loan-offers, stanje, evidencija i otkazivanje ponude, webhookovi loanGuide.*, čuvanje evidencije. Neobavezno polje returnUrl ponude (vlastita adresa povratka).
• 1.2.0 (2026-10) - GET /v1/users sa straničenjem, certifikat osobe (polje certificate, GET /v1/users/{identifier}/certificate, događaj certificate.issued), DELETE /v1/users/{identifier} (anonimizacija), identifikator najviše 64 znaka, čuvanje zapisnika.
• 1.1.0 (2026-10) - API ključevi, POST /v1/users, GET /v1/users/{identifier} s ?include=detail, ulazna poveznica, webhookovi, jedan oblik pogrešaka, javno stanje i OpenAPI, ograničenja.
• 1.0.0 (2024) - GET /v1/user/{identifier} s JWT-om partnerskog ključa.

Želite li API za svoje poduzeće? Pišite nam