API pentru parteneri

Cum funcționează

API-ul este același pentru toți partenerii. În cinci pași:

1. Activăm API-ul pentru compania dumneavoastră; în administrarea dumneavoastră creați o cheie API în fila API.
2. Când un client trebuie instruit, sistemul dumneavoastră apelează POST /v1/users cu identificatorul dumneavoastră al clientului.
3. Creăm un profil fără e-mail și returnăm un link de acces (entryUrl); îl afișați clientului ca buton.
4. Clientul face clic pe el și intră direct în curs.
5. Citiți stadiul oricând prin GET /v1/users/{identifier}, sau îl anunțăm serverului dumneavoastră printr-un webhook.

Operatorul identificatorului sunteți dumneavoastră, noi prelucrăm doar date pseudonimizate. Nu trimiteți niciodată ca identificator un e-mail sau un nume - API-ul respinge o adresă de e-mail cu eroarea 422.

Adresă și autentificare

Fiecare apel merge prin HTTPS la adresa de mai jos și poartă cheia dumneavoastră API în antetul Authorization.

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

• rsb_live_... deschide programul dumneavoastră de producție, rsb_test_... programul dumneavoastră de test (sandbox).
• Cheia se afișează o singură dată, la creare; păstrăm doar amprenta ei. Păstrați-o ca secret pe serverul dumneavoastră - niciodată într-un browser sau într-o aplicație.
• Cheia are permisiuni: read (stadiul și lista persoanelor, certificatul) și write (trimiterea și anonimizarea persoanelor). Poate fi limitată la adresele dumneavoastră IP și poate avea o valabilitate.
• Înlocuire: creați o cheie nouă, cea veche mai este valabilă 7 zile, apoi expiră.
• Răspunsurile nu sunt niciodată stocate în cache (Cache-Control: no-store), iar API-ul nu acceptă apeluri din browser (fără CORS).

POST /v1/users

Trimite o persoană în programul cheii (permisiunea 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 pentru o persoană nouă, 200 OK când identificatorul există deja - nu se schimbă nimic, apelul poate fi repetat în siguranță. Corpul este stadiul de mai jos, inclusiv entryUrl. O limită epuizată de persoane sau de licențe ale programului returnează 403.

GET /v1/users/{identifier}

Stadiul unei persoane (permisiunea read): ceea ce îi trebuie unei verificări de conformitate, nimic în plus.

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 este rezultatul chestionarului final în %, imediat ce este finalizat. Orele sunt în UTC, la secundă întreagă. Câmpul certificate conține certificatul persoanei (vezi mai jos); cât timp nu îl are, este null.

?include=detail

Adaugă progresul în fiecare curs și rezultatul fiecărui chestionar - niciodată răspunsurile individuale.

"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

Lista persoanelor pe care le-ați trimis în programul cheii (permisiunea read), pagină cu pagină: fiecare element are forma stadiului de mai sus. Opțional status (doar persoanele în acel stadiu), limit (între 1 și 500, implicit 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"

• Continuați cu cursor = nextCursor cât timp nextCursor nu este null; cursorul este un text opac, nu îl compuneți niciodată singur.
• Persoanele vin în ordinea momentului trimiterii, într-o ordine stabilă (și la același moment), niciuna de două ori; persoanele anonimizate nu apar în listă.
• Cu filtrul status parcurgem cel mult 2000 de persoane pentru o pagină, așa că o pagină poate avea mai puține elemente decât limit, chiar niciunul - continuați cât timp există un nextCursor.

Certificatul persoanei

Imediat ce persoana finalizează programul, cursul îi emite un certificat - sub pseudonimul ei (porecla profilului ID XXXXXX), fără nume și fără e-mail. Nu se trimite nimic prin e-mail; stadiul persoanei conține câmpul certificate cu numărul, orele și pagina publică de verificare, iar PDF-ul îl descărcați prin 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

• Pagina de verificare verifyUrl arată doar pseudonimul, programul, partenerul și valabilitatea - niciodată identificatorul dumneavoastră.
• PDF-ul returnează application/pdf (permisiunea read). Fără certificat, răspunsul este 404 certificateNotFound, iar cât timp PDF-ul este încă în pregătire, 404 certificatePdfNotReady cu Retry-After.
• Un certificat revocat nu se eliberează niciodată (câmpul certificate este atunci null, PDF-ul 404); un certificat cu valabilitatea expirată rămâne o dovadă adevărată și se eliberează.
• Un webhook anunță certificatul prin evenimentul certificate.issued (imediat după user.completed).

DELETE /v1/users/{identifier}

Anonimizează o persoană (permisiunea write): din profil dispar identificatorul dumneavoastră, eticheta și fiecare mesaj de webhook care îl menționează; linkurile de acces nu mai sunt valabile. Certificatul și rezultatul cursului rămân sub numărul certificatului - ca dovadă de conformitate.

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

HTTP/1.1 204 No Content

Răspuns 204 fără corp; fiecare apel ulterior cu același identificator returnează 404 userNotFound, deci repetarea este sigură. Același identificator îl puteți apoi trimite din nou ca persoană nouă.

Link de acces

Afișați entryUrl persoanei (un buton Începe cursul în sistemul dumneavoastră). O conectează la curs - fără e-mail și fără parolă.

Linkul este valabil 30 de zile și poate fi folosit de mai multe ori; fiecare apel GET /v1/users/{identifier} returnează unul nou. Nu îl trimiteți niciodată altcuiva: cine are linkul intră ca persoana respectivă.

Webhook-uri

În fila API a administrării dumneavoastră setați câte un webhook pentru fiecare program: o adresă HTTPS publică a serverului dumneavoastră și evenimentele. Apoi vă trimitem POST cu JSON - doar identificatori și stadii, niciodată linkul de acces.

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

Semnătură

Fiecare mesaj poartă antetul X-Responsiblo-Signature: t=<timp Unix>,v1=<HMAC-SHA256 al textului t.corp cu secretul webhook-ului, hex>. Secretul (whsec_...) se afișează o singură dată, la crearea webhook-ului. Înainte să aveți încredere într-un mesaj, verificați semnătura și vechimea lui t; folosiți X-Responsiblo-Delivery drept cheie de idempotență.

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

Livrare și reîncercări

Livrat = răspuns 2xx în cel mult 10 secunde. Altfel reîncercăm după 1 minut, 5 minute, 30 de minute, 2 ore și 12 ore, apoi renunțăm. Nu urmăm redirecționările.

20 de mesaje nelivrate la rând dezactivează webhook-ul până când îl reactivați; mesajele din acea perioadă așteaptă. Butonul Test trimite un ping; jurnalul livrărilor îl găsiți în administrarea dumneavoastră.

Evenimentul certificate.issued îl adăugați unui webhook în setările acestuia; un webhook creat înainte de versiunea 1.2 nu îl primește de la sine.

Erori

Fiecare eroare are o singură formă: status, code, reason și message; o eroare 422 adaugă errors (câmp - ce este greșit).

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

Pentru programe și agenți

• Decideți după code și reason, niciodată după textul din message; errors este un obiect câmp -> ce este greșit.
• Repetați doar 429, 500 și certificatePdfNotReady, și doar după Retry-After secunde (altfel cu un interval crescător); alte coduri 4xx în afară de 429 nu le repetați fără a corecta apelul.
• POST /v1/users este idempotent după identifier (201 prima dată, apoi 200); DELETE returnează 204 prima dată și 404 după aceea - ambele pot fi repetate în siguranță.
• Deduplicați webhook-urile după X-Responsiblo-Delivery; ordinea mesajelor nu este garantată, decide stadiul din data.

Ghidul de credit

Ghidul de credit este un curs scurt pentru solicitantul unui credit la un furnizor de credite: înainte de semnarea contractului parcurge trei lecții, opt situații practice și, dacă este activat, un chestionar, totul pe cifrele propriei oferte, iar la final confirmă oferta. Pe fiecare ecran poate cere o explicație. Trimiteți oferta prin API, primiți un link de acces, iar rezultatul vi-l anunță un webhook.

Activăm ghidul de credit de comun acord cu dumneavoastră.

Și aici solicitantul este doar profilul dumneavoastră pseudonim din POST /v1/users. Oferta este identificată prin referințele dumneavoastră (externalApplicationId, offerReference), iar documentele doar printr-un link cu amprentă SHA-256 - niciodată nume, e-mail, cod numeric personal, număr de cont sau telefon. responsiblo nu aprobă creditul, nu descarcă și nu stochează documentele, nu verifică identitatea și nu emite certificat pentru ghid.

1. Creați profilul solicitantului: POST /v1/users cu pseudonimul dumneavoastră.
2. Trimiteți oferta: POST /v1/users/{identifier}/loan-offers; răspunsul 201 conține entryUrl.
3. Transmiteți entryUrl solicitantului prin propriul canal verificat. Linkul este valabil 30 de zile și poate fi folosit de mai multe ori; ghidul arată cifrele ofertei respective.
4. Aflați finalul printr-un webhook (loanGuide.completed, loanGuide.assistanceRequested și altele).
5. Citiți starea prin GET …/loan-offers/{offerReference}, înregistrarea pentru dosarul dumneavoastră prin GET …/evidence. Ofertă modificată = ofertă nouă cu supersedes, cerere retrasă = POST …/cancel.

Până la activare, operațiile ghidului răspund 404 notFound sau 409 loanGuideNotConfigured. Permisiunea write trimite și anulează oferta, read citește starea și evidența.

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

Trimite o ofertă la profilul solicitantului (permisiunea write). Antetul opțional Idempotency-Key are între 1 și 255 de caractere ASCII vizibile. Exemplu: credit de 10.000 CZK, de plătit 10.800 CZK într-o singură plată la 30 de zile după virare, DAE 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"
}

Același corp din nou (sub aceleași referințe sau același Idempotency-Key) returnează 200 cu oferta existentă și un entryUrl nou; un alt corp sub ele returnează 409 offerConflict. Un profil are o singură ofertă activă: încă una fără supersedes returnează 409 activeOfferExists, un supersedes greșit 409 notSupersedable. Setările ghidului dumneavoastră (chestionar, contact) se blochează în acel moment pentru ofertă.

Stare, evidență și anulare

• GET /v1/users/{identifier}/loan-offers/{offerReference} - starea (permisiunea read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), lecțiile finalizate, practica, chestionarul (null, când este dezactivat) și momentele prezentării ofertei, ale confirmării și ale cererii de explicație. Niciodată răspunsuri, valori ale ofertei sau linkul. Finalizarea rămâne chiar dacă oferta expiră ulterior.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - înregistrarea pentru dosarul dumneavoastră (permisiunea read): schemaVersion loan-guide-evidence/1, instantaneul ofertei dumneavoastră cu amprenta snapshotSha256, ediția cursului cu amprentele lecțiilor, evenimentele în ordinea sequence, fiecare răspuns cu toate încercările, confirmarea și limitations - ce nu dovedește înregistrarea (prezentat nu înseamnă citit, identitatea o declarați dumneavoastră, documentele doar prin link, niciun certificat, nicio aprobare a creditului).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - anulează oferta activă (permisiunea write), reasonCode = withdrawn_by_provider sau application_closed; 200 returnează starea, o ofertă care nu este activă sau are ghidul finalizat returnează 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= este necesar doar când un offerReference aparține mai multor cereri ale profilului (altfel 409 ambiguousOfferReference).

Webhook-urile ghidului

Webhook-ul programului (vezi Webhook-uri) primește evenimentele ghidului fără abonare separată. Semnătura, livrarea și reîncercările sunt aceleași ca la celelalte evenimente; data conțin identifier, offerReference, externalApplicationId, guideStatus, occurredAt și sequence (ordinea evenimentelor unei oferte) - niciodată evidența, valori ale ofertei sau linkul de acces.

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

Fiecare eveniment ajunge la un webhook cel mult o dată (cheia de idempotență = X-Responsiblo-Delivery). Un webhook creat ulterior nu redă evenimentele mai vechi, iar evenimentele mai vechi de 28 de zile nu se mai anunță.

Păstrarea evidenței

Când parcursul ofertei se încheie (ofertă finalizată, anulată, expirată sau înlocuită), începe perioada de păstrare din setările ghidului dumneavoastră (implicit 30 de zile). Apoi evidența se șterge: GET …/evidence returnează 410 evidenceErased, iar starea răspunde în continuare cu evidenceErased: true, referințele și momentele. O ofertă activă nu se șterge niciodată. Evidența pe care trebuie să o păstrați descărcați-o imediat după loanGuide.completed.

Erorile ghidului

Erorile au forma API-ului de mai sus. În plus, pentru ghid:

O eroare nu repetă niciodată valoarea pe care ați trimis-o. Exemplu: aceeași ofertă cu o plată de 10.700 CZK în loc de 10.800 CZK și o valabilitate de 9 zile:

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

Limite

120 de apeluri pe minut pentru fiecare cheie. După 30 de chei respinse de la aceeași adresă în zece minute, adresa așteaptă 10 minute.

Jurnalul apelurilor (fără corpuri, identificatorul doar ca amprentă SHA-256) îl păstrăm 180 de zile, mesajele de webhook livrate și abandonate 30 de zile.

Stare și contract

• GET /v1/status - fără cheie, returnează {"status":"ok","version":"1.3.2"}
• GET /openapi - fără cheie, documentul OpenAPI 3 al API-ului pentru parteneri

Sandbox

Cheia de test rsb_test_... deschide programul dumneavoastră de test cu același curs. Persoanele din el se încheie după 7 zile; webhook-ul programului de test este separat de cel de producție.

Istoricul versiunilor

• 1.3.2 (2026-11) - Fiecare operație a documentului OpenAPI are un nume și o descriere, iar operațiile sunt împărțite în grupuri. /v1/status și webhook-urile raportează versiunea 1.3.2. Forma cererilor și a răspunsurilor rămâne neschimbată.
• 1.3.1 (2026-10) - Corecturi fără modificarea endpoint-urilor și a răspunsurilor lor.
• 1.3.0 (2026-10) - Ghidul de credit: POST /v1/users/{identifier}/loan-offers, starea, evidența și anularea ofertei, webhook-urile loanGuide.*, păstrarea evidenței. Câmpul opțional returnUrl al ofertei (adresă proprie de întoarcere).
• 1.2.0 (2026-10) - GET /v1/users cu paginare, certificatul persoanei (câmpul certificate, GET /v1/users/{identifier}/certificate, evenimentul certificate.issued), DELETE /v1/users/{identifier} (anonimizare), identificator de cel mult 64 de caractere, păstrarea jurnalului.
• 1.1.0 (2026-10) - Chei API, POST /v1/users, GET /v1/users/{identifier} cu ?include=detail, link de acces, webhook-uri, o singură formă a erorilor, stare publică și OpenAPI, limite.
• 1.0.0 (2024) - GET /v1/user/{identifier} cu JWT-ul cheii de partener.

Doriți API-ul pentru compania dumneavoastră? Scrieți-ne