Partner-API

Så fungerar det

API:et är detsamma för alla partner. I fem steg:

1. Vi aktiverar API:et för ert företag; i er administration skapar ni en API-nyckel under fliken API.
2. När en kund ska utbildas anropar ert system POST /v1/users med er identifierare för kunden.
3. Vi skapar en profil utan e-post och returnerar en startlänk (entryUrl); den visar ni för kunden som en knapp.
4. Kunden klickar på den och är direkt i kursen.
5. Statusen läser ni när som helst via GET /v1/users/{identifier}, eller så meddelar vi er server via en webhook.

Ni är personuppgiftsansvarig för identifieraren, vi behandlar bara pseudonymiserade uppgifter. Skicka aldrig en e-postadress eller ett namn som identifierare - en e-postadress avvisar API:et med felet 422.

Adress och autentisering

Varje anrop går via HTTPS till adressen nedan och bär er API-nyckel i headern Authorization.

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

• rsb_live_... öppnar ert produktionsprogram, rsb_test_... ert testprogram (sandbox).
• Nyckeln visas bara en gång, när den skapas; vi sparar bara dess fingeravtryck. Förvara den som en hemlighet på er server - aldrig i en webbläsare eller en app.
• Nyckeln har behörigheter: read (statusen och listan över personer, certifikatet) och write (att skicka och anonymisera personer). Den kan vara begränsad till era IP-adresser och ha en giltighetstid.
• Byte: ni skapar en ny nyckel, den gamla gäller i ytterligare 7 dagar och upphör sedan.
• Svar sparas aldrig i cache (Cache-Control: no-store) och API:et tar inte emot anrop från en webbläsare (ingen CORS).

POST /v1/users

Skickar en person till nyckelns program (behörighet 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 för en ny person, 200 OK när identifieraren redan finns - inget ändras, anropet kan säkert upprepas. Svarets innehåll är statusen nedan, inklusive entryUrl. En förbrukad gräns för personer eller för programmets licenser ger 403.

GET /v1/users/{identifier}

En persons status (behörighet read): det som en compliancekontroll behöver, inget mer.

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 är resultatet av slutquizet i %, så snart det är slutfört. Tider anges i UTC på hela sekunder. Fältet certificate innehåller personens certifikat (se nedan); så länge personen inte har något är det null.

?include=detail

Lägger till framstegen i varje kurs och resultatet av varje quiz - aldrig de enskilda svaren.

"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 över de personer som ni har skickat till nyckelns program (behörighet read), sida för sida: varje post har samma form som statusen ovan. Valfritt status (bara personer med den statusen), limit (1 till 500, standard 100) och 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"

• Fortsätt med cursor = nextCursor så länge nextCursor inte är null; markören är en ogenomskinlig text, sätt aldrig ihop den själva.
• Personerna kommer efter när de skickades, i en fast ordning (även vid samma tidpunkt), ingen två gånger; anonymiserade personer finns inte i listan.
• Med filtret status går vi igenom högst 2000 personer per sida, en sida kan därför ha färre poster än limit, även inga - fortsätt så länge det finns en nextCursor.

Personens certifikat

Så snart personen slutför programmet utfärdar kursen ett certifikat - under personens pseudonym (profilens smeknamn ID XXXXXX), utan namn och utan e-post. Inget skickas via e-post; personens status innehåller fältet certificate med nummer, tider och den offentliga verifieringssidan, och PDF:en laddar ni ner via 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

• Verifieringssidan verifyUrl visar bara pseudonymen, programmet, partnern och giltigheten - aldrig er identifierare.
• PDF:en returnerar application/pdf (behörighet read). Utan certifikat är svaret 404 certificateNotFound, medan PDF:en fortfarande skapas 404 certificatePdfNotReady med Retry-After.
• Ett återkallat certifikat lämnas aldrig ut (fältet certificate är då null, PDF:en 404); ett certifikat vars giltighet har gått ut förblir ett sant bevis och lämnas ut.
• En webhook meddelar certifikatet med händelsen certificate.issued (direkt efter user.completed).

DELETE /v1/users/{identifier}

Anonymiserar en person (behörighet write): er identifierare, etiketten och varje webhookmeddelande som nämner den försvinner från profilen; startlänkarna slutar gälla. Certifikatet och kursresultatet finns kvar under certifikatets nummer - som compliancebevis.

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

HTTP/1.1 204 No Content

Svar 204 utan innehåll; varje senare anrop med samma identifierare returnerar 404 userNotFound, så en upprepning är säker. Samma identifierare kan ni sedan skicka igen som en ny person.

Startlänk

Visa entryUrl för personen (en knapp Starta kursen i ert system). Den loggar in personen i kursen - utan e-post och utan lösenord.

Länken gäller i 30 dagar och kan användas flera gånger; varje anrop GET /v1/users/{identifier} returnerar en ny. Skicka den aldrig till någon annan: den som har länken kommer in som den personen.

Webhooks

Under fliken API i er administration ställer ni in en webhook per program: en offentlig HTTPS-adress till er server och händelserna. Sedan skickar vi POST med JSON till er - bara identifierare och statusar, aldrig startlänken.

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

Signatur

Varje meddelande bär headern X-Responsiblo-Signature: t=<Unix-tid>,v1=<HMAC-SHA256 av texten t.innehåll med webhookens hemlighet, hex>. Hemligheten (whsec_...) visas en gång när webhooken skapas. Innan ni litar på ett meddelande, kontrollera signaturen och åldern på t; använd X-Responsiblo-Delivery som idempotensnyckel.

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

Leverans och nya försök

Levererat = svar 2xx inom 10 sekunder. Annars försöker vi igen efter 1 minut, 5 minuter, 30 minuter, 2 timmar och 12 timmar, sedan ger vi upp. Omdirigeringar följer vi inte.

20 olevererade meddelanden i rad stänger av webhooken tills ni slår på den igen; meddelandena från den tiden väntar. Knappen Test skickar en ping; leveransloggen hittar ni i er administration.

Händelsen certificate.issued lägger ni till en webhook i dess inställningar; en webhook som skapades före version 1.2 får den inte av sig själv.

Fel

Varje fel har en och samma form: status, code, reason och message; ett fel 422 lägger till errors (fält - vad som är fel).

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

För program och agenter

• Avgör utifrån code och reason, aldrig utifrån texten i message; errors är ett objekt fält -> vad som är fel.
• Upprepa bara 429, 500 och certificatePdfNotReady, och då efter Retry-After sekunder (annars med växande intervall); upprepa inte andra 4xx än 429 utan att rätta anropet.
• POST /v1/users är idempotent efter identifier (201 första gången, sedan 200); DELETE returnerar 204 första gången och 404 därefter - båda kan säkert upprepas.
• Deduplicera webhooks efter X-Responsiblo-Delivery; meddelandenas ordning är inte garanterad, det är statusen i data som avgör.

Låneguide

Låneguiden är en kort kurs för en sökande hos en kreditgivare: före undertecknandet av avtalet går den sökande igenom tre lektioner, åtta praktiska situationer och eventuellt ett quiz, allt med siffrorna i det egna erbjudandet, och bekräftar erbjudandet i slutet. På varje skärm kan den sökande be om en förklaring. Erbjudandet skickar ni via API:et, ni får en startlänk och en webhook meddelar er resultatet.

Låneguiden aktiverar vi efter överenskommelse med er.

Även här är den sökande bara er pseudonyma profil från POST /v1/users. Erbjudandet identifieras av era referenser (externalApplicationId, offerReference) och dokumenten bara av en länk med ett SHA-256-fingeravtryck - aldrig namn, e-post, personnummer, kontonummer eller telefon. responsiblo godkänner inte lånet, hämtar inte och lagrar inte dokumenten, verifierar inte identiteten och utfärdar inget certifikat för guiden.

1. Ni skapar den sökandes profil: POST /v1/users med er pseudonym.
2. Ni skickar erbjudandet: POST /v1/users/{identifier}/loan-offers; svaret 201 innehåller entryUrl.
3. entryUrl lämnar ni till den sökande via er egen autentiserade kanal. Länken gäller i 30 dagar och kan användas flera gånger; guiden visar siffrorna i den sökandes erbjudande.
4. Slutet får ni veta via en webhook (loanGuide.completed, loanGuide.assistanceRequested med flera).
5. Statusen läser ni via GET …/loan-offers/{offerReference}, underlaget för er akt via GET …/evidence. Ändrat erbjudande = nytt erbjudande med supersedes, återkallad ansökan = POST …/cancel.

Fram till aktiveringen svarar guidens operationer 404 notFound eller 409 loanGuideNotConfigured. Behörigheten write skickar och annullerar ett erbjudande, read läser statusen och underlaget.

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

Skickar ett erbjudande till den sökandes profil (behörighet write). Den valfria headern Idempotency-Key har 1 till 255 synliga ASCII-tecken. Exempel: ett lån på 10 000 CZK, 10 800 CZK att betala i en enda betalning 30 dagar efter utbetalningen, effektiv ränta 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"
}

Samma innehåll igen (under samma referenser eller samma Idempotency-Key) returnerar 200 med det befintliga erbjudandet och en ny entryUrl; annat innehåll under dem returnerar 409 offerConflict. En profil har ett aktivt erbjudande: ett till utan supersedes returnerar 409 activeOfferExists, en felaktig supersedes 409 notSupersedable. Inställningarna för er guide (quiz, kontakt) låses i det ögonblicket för erbjudandet.

Status, underlag och annullering

• GET /v1/users/{identifier}/loan-offers/{offerReference} - status (behörighet read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), slutförda lektioner, praktik, quiz (null när det är avstängt) och tidpunkterna för när erbjudandet lades fram, bekräftelsen och begäran om förklaring. Aldrig svar, erbjudandets värden eller länken. Slutförandet står kvar, även om erbjudandet senare löper ut.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - underlag för er akt (behörighet read): schemaVersion loan-guide-evidence/1, en ögonblicksbild av ert erbjudande med fingeravtrycket snapshotSha256, kursens utgåva med lektionernas fingeravtryck, händelser i ordningen sequence, varje svar med alla försök, bekräftelsen och limitations - vad underlaget inte bevisar (framlagt betyder inte läst, identiteten uppger ni, dokument bara via referens, inget certifikat, inget godkännande av lånet).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - annullerar ett aktivt erbjudande (behörighet write), reasonCode = withdrawn_by_provider eller application_closed; 200 returnerar statusen, ett erbjudande som inte är aktivt eller vars guide är slutförd returnerar 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= behövs bara när en offerReference hör till flera ansökningar i profilen (annars 409 ambiguousOfferReference).

Guidens webhooks

Programmets webhook (se Webhooks) får guidens händelser utan särskild prenumeration. Signatur, leverans och nya försök är desamma som för övriga händelser; data innehåller identifier, offerReference, externalApplicationId, guideStatus, occurredAt och sequence (ordningen för händelserna i ett erbjudande) - aldrig underlaget, erbjudandets värden eller startlänken.

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

Varje händelse når en webhook högst en gång (idempotensnyckel = X-Responsiblo-Delivery). En webhook som skapas senare spelar inte upp äldre händelser, och händelser äldre än 28 dagar meddelas inte längre.

Lagringstid för underlaget

När erbjudandets väg tar slut (slutfört, annullerat, utgånget eller ersatt erbjudande) löper lagringstiden från inställningarna för er guide (som standard 30 dagar). Sedan raderas underlaget: GET …/evidence returnerar 410 evidenceErased och statusen svarar fortsatt med evidenceErased: true, referenserna och tidpunkterna. Ett aktivt erbjudande raderas aldrig. Underlag som ni måste bevara laddar ni ner direkt efter loanGuide.completed.

Guidens fel

Felen har API:ets form ovan. Dessutom för guiden:

Ett fel upprepar aldrig ett värde som ni har skickat. Exempel: samma erbjudande med en betalning på 10 700 CZK i stället för 10 800 CZK och en giltighet på 9 dagar:

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

Gränser

120 anrop per minut och nyckel. Efter 30 avvisade nycklar från en och samma adress inom tio minuter får adressen vänta 10 minuter.

Loggen över anrop (utan innehåll, identifieraren bara som SHA-256-fingeravtryck) sparar vi i 180 dagar, levererade och uppgivna webhookmeddelanden i 30 dagar.

Status och kontrakt

• GET /v1/status - utan nyckel, returnerar {"status":"ok","version":"1.3.2"}
• GET /openapi - utan nyckel, OpenAPI 3-dokumentet för partner-API:et

Sandbox

Testnyckeln rsb_test_... öppnar ert testprogram med samma kurs. Personer där upphör efter 7 dagar; testprogrammets webhook är skild från produktionens.

Versionshistorik

• 1.3.2 (2026-11) - Varje operation i OpenAPI-dokumentet har ett namn och en beskrivning, och operationerna är indelade i grupper. /v1/status och webhooks anger versionen 1.3.2. Formen på förfrågningar och svar är oförändrad.
• 1.3.1 (2026-10) - Rättelser utan ändring av ändpunkterna och deras svar.
• 1.3.0 (2026-10) - Låneguide: POST /v1/users/{identifier}/loan-offers, status, underlag och annullering av erbjudandet, webhooks loanGuide.*, lagringstid för underlaget. Valfritt fält returnUrl för ett erbjudande (egen returadress).
• 1.2.0 (2026-10) - GET /v1/users med sidindelning, personens certifikat (fältet certificate, GET /v1/users/{identifier}/certificate, händelsen certificate.issued), DELETE /v1/users/{identifier} (anonymisering), identifierare på högst 64 tecken, lagringstid för loggen.
• 1.1.0 (2026-10) - API-nycklar, POST /v1/users, GET /v1/users/{identifier} med ?include=detail, startlänk, webhooks, en form för fel, offentlig status och OpenAPI, gränser.
• 1.0.0 (2024) - GET /v1/user/{identifier} med JWT för partnernyckeln.

Vill ni ha API:et för ert företag? Skriv till oss