Partner-API

Sådan fungerer det

API'et er det samme for alle partnere. I fem trin:

1. Vi slår API'et til for jeres virksomhed; i jeres administration opretter I en API-nøgle under fanen API.
2. Når en kunde skal uddannes, kalder jeres system POST /v1/users med jeres identifikator for kunden.
3. Vi opretter en profil uden e-mail og returnerer et adgangslink (entryUrl); det viser I kunden som en knap.
4. Kunden klikker på det og er straks i kurset.
5. Status læser I når som helst via GET /v1/users/{identifier}, eller vi giver jeres server besked via en webhook.

I er dataansvarlige for identifikatoren, vi behandler kun pseudonymiserede oplysninger. Send aldrig en e-mailadresse eller et navn som identifikator - en e-mailadresse afviser API'et med fejlen 422.

Adresse og godkendelse

Hvert kald går via HTTPS til adressen nedenfor og bærer jeres API-nøgle i headeren Authorization.

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

• rsb_live_... åbner jeres produktionsprogram, rsb_test_... jeres testprogram (sandbox).
• Nøglen vises kun én gang, når den oprettes; vi gemmer kun dens fingeraftryk. Opbevar den som en hemmelighed på jeres server - aldrig i en browser eller en app.
• Nøglen har rettigheder: read (status og listen over personer, certifikatet) og write (at sende og anonymisere personer). Den kan være begrænset til jeres IP-adresser og have en gyldighed.
• Udskiftning: I opretter en ny nøgle, den gamle gælder i yderligere 7 dage og udløber derefter.
• Svar gemmes aldrig i cache (Cache-Control: no-store), og API'et modtager ikke kald fra en browser (ingen CORS).

POST /v1/users

Sender en person til nøglens program (rettighed 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 for en ny person, 200 OK, når identifikatoren allerede findes - intet ændres, kaldet kan trygt gentages. Svarets indhold er status nedenfor, inklusive entryUrl. En opbrugt grænse for personer eller for programmets licenser giver 403.

GET /v1/users/{identifier}

En persons status (rettighed read): det, et compliancetjek har brug for, intet mere.

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 er resultatet af den afsluttende quiz i %, så snart den er gennemført. Tidspunkter er i UTC på hele sekunder. Feltet certificate indeholder personens certifikat (se nedenfor); så længe personen ikke har et, er det null.

?include=detail

Tilføjer fremdriften i hvert kursus og resultatet af hver quiz - aldrig de enkelte svar.

"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

Liste over de personer, I har sendt til nøglens program (rettighed read), side for side: hvert element har samme form som status ovenfor. Valgfrit status (kun personer med den status), limit (1 til 500, standard 100) og 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æt med cursor = nextCursor, så længe nextCursor ikke er null; markøren er en uigennemsigtig tekst, sammensæt den aldrig selv.
• Personerne kommer efter tidspunktet for afsendelse i en fast rækkefølge (også ved samme tidspunkt), ingen to gange; anonymiserede personer er ikke på listen.
• Med filteret status gennemgår vi højst 2000 personer pr. side, en side kan derfor have færre elementer end limit, også ingen - fortsæt, så længe der er en nextCursor.

Personens certifikat

Så snart personen gennemfører programmet, udsteder kurset et certifikat - under personens pseudonym (profilens kaldenavn ID XXXXXX), uden navn og uden e-mail. Intet sendes via e-mail; personens status indeholder feltet certificate med nummer, tidspunkter og den offentlige verifikationsside, og PDF'en henter I 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

• Verifikationssiden verifyUrl viser kun pseudonymet, programmet, partneren og gyldigheden - aldrig jeres identifikator.
• PDF'en returnerer application/pdf (rettighed read). Uden certifikat er svaret 404 certificateNotFound, mens PDF'en stadig laves, 404 certificatePdfNotReady med Retry-After.
• Et tilbagekaldt certifikat udleveres aldrig (feltet certificate er da null, PDF'en 404); et certifikat med udløbet gyldighed forbliver et sandt bevis og udleveres.
• En webhook meddeler certifikatet med hændelsen certificate.issued (lige efter user.completed).

DELETE /v1/users/{identifier}

Anonymiserer en person (rettighed write): jeres identifikator, etiketten og enhver webhookbesked, der nævner den, forsvinder fra profilen; adgangslinkene holder op med at gælde. Certifikatet og kursets resultat bliver 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 uden indhold; hvert senere kald med samme identifikator returnerer 404 userNotFound, så en gentagelse er sikker. Samme identifikator kan I derefter sende igen som en ny person.

Adgangslink

Vis entryUrl til personen (en knap Start kurset i jeres system). Den logger personen ind i kurset - uden e-mail og uden adgangskode.

Linket gælder i 30 dage og kan bruges flere gange; hvert kald GET /v1/users/{identifier} returnerer et nyt. Send det aldrig til andre: den, der har linket, kommer ind som den person.

Webhooks

Under fanen API i jeres administration opsætter I én webhook pr. program: en offentlig HTTPS-adresse på jeres server og hændelserne. Derefter sender vi jer POST med JSON - kun identifikatorer og statusser, aldrig adgangslinket.

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

Hver besked bærer headeren X-Responsiblo-Signature: t=<Unix-tid>,v1=<HMAC-SHA256 af teksten t.indhold med webhookens hemmelighed, hex>. Hemmeligheden (whsec_...) vises én gang, når webhooken oprettes. Før I stoler på en besked, skal I kontrollere signaturen og alderen af t; brug X-Responsiblo-Delivery som idempotensnøgle.

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

Levering og nye forsøg

Leveret = svar 2xx inden for 10 sekunder. Ellers prøver vi igen efter 1 minut, 5 minutter, 30 minutter, 2 timer og 12 timer, derefter giver vi op. Omdirigeringer følger vi ikke.

20 ikke-leverede beskeder i træk slår webhooken fra, indtil I slår den til igen; beskederne fra den periode venter. Knappen Test sender et ping; leveringsloggen finder I i jeres administration.

Hændelsen certificate.issued tilføjer I til en webhook i dens indstillinger; en webhook, der er oprettet før version 1.2, får den ikke af sig selv.

Fejl

Hver fejl har én og samme form: status, code, reason og message; en fejl 422 tilføjer errors (felt - hvad der er galt).

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

For programmer og agenter

• Afgør ud fra code og reason, aldrig ud fra teksten i message; errors er et objekt felt -> hvad der er galt.
• Gentag kun 429, 500 og certificatePdfNotReady, og da efter Retry-After sekunder (ellers med voksende interval); gentag ikke andre 4xx end 429 uden at rette kaldet.
• POST /v1/users er idempotent efter identifier (201 første gang, derefter 200); DELETE returnerer 204 første gang og 404 derefter - begge kan trygt gentages.
• Deduplikér webhooks efter X-Responsiblo-Delivery; beskedernes rækkefølge er ikke garanteret, det er status i data, der afgør.

Låneguide

Låneguiden er et kort kursus for en ansøger hos en kreditgiver: før underskrivelsen af aftalen gennemgår ansøgeren tre lektioner, otte praktiske situationer og eventuelt en quiz, alt sammen med tallene i det egne tilbud, og bekræfter tilbuddet til sidst. På hver skærm kan ansøgeren bede om en forklaring. Tilbuddet sender I via API'et, I får et adgangslink, og en webhook giver jer besked om resultatet.

Låneguiden aktiverer vi efter aftale med jer.

Også her er ansøgeren kun jeres pseudonyme profil fra POST /v1/users. Tilbuddet identificeres af jeres referencer (externalApplicationId, offerReference) og dokumenterne kun af et link med et SHA-256-fingeraftryk - aldrig navn, e-mail, personnummer, kontonummer eller telefon. responsiblo godkender ikke lånet, henter og gemmer ikke dokumenterne, verificerer ikke identiteten og udsteder intet certifikat for guiden.

1. I opretter ansøgerens profil: POST /v1/users med jeres pseudonym.
2. I sender tilbuddet: POST /v1/users/{identifier}/loan-offers; svaret 201 indeholder entryUrl.
3. entryUrl giver I ansøgeren via jeres egen godkendte kanal. Linket gælder i 30 dage og kan bruges flere gange; guiden viser tallene i ansøgerens tilbud.
4. Afslutningen får I besked om via en webhook (loanGuide.completed, loanGuide.assistanceRequested med flere).
5. Status læser I via GET …/loan-offers/{offerReference}, dokumentationen til jeres sag via GET …/evidence. Ændret tilbud = nyt tilbud med supersedes, tilbagetrukket ansøgning = POST …/cancel.

Indtil aktiveringen svarer guidens operationer 404 notFound eller 409 loanGuideNotConfigured. Rettigheden write sender og annullerer et tilbud, read læser status og dokumentationen.

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

Sender et tilbud til ansøgerens profil (rettighed write). Den valgfrie header Idempotency-Key har 1 til 255 synlige ASCII-tegn. Eksempel: et lån på 10.000 CZK, 10.800 CZK at betale i én betaling 30 dage efter udbetalingen, ÅOP 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"
}

Samme indhold igen (under samme referencer eller samme Idempotency-Key) returnerer 200 med det eksisterende tilbud og et nyt entryUrl; andet indhold under dem returnerer 409 offerConflict. En profil har ét aktivt tilbud: et nyt uden supersedes returnerer 409 activeOfferExists, en forkert supersedes 409 notSupersedable. Indstillingerne for jeres guide (quiz, kontakt) låses i det øjeblik for tilbuddet.

Status, dokumentation og annullering

• GET /v1/users/{identifier}/loan-offers/{offerReference} - status (rettighed read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), gennemførte lektioner, praksis, quiz (null, når den er slået fra) og tidspunkterne for fremlæggelsen af tilbuddet, bekræftelsen og anmodningen om forklaring. Aldrig svar, tilbuddets værdier eller linket. Gennemførelsen består, også selv om tilbuddet senere udløber.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - dokumentation til jeres sag (rettighed read): schemaVersion loan-guide-evidence/1, et øjebliksbillede af jeres tilbud med fingeraftrykket snapshotSha256, kursets udgave med lektionernes fingeraftryk, hændelser i rækkefølgen sequence, hvert svar med alle forsøg, bekræftelsen og limitations - hvad dokumentationen ikke beviser (fremlagt betyder ikke læst, identiteten oplyser I, dokumenter kun via reference, intet certifikat, ingen godkendelse af lånet).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - annullerer et aktivt tilbud (rettighed write), reasonCode = withdrawn_by_provider eller application_closed; 200 returnerer status, et tilbud, der ikke er aktivt eller har en gennemført guide, returnerer 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= er kun nødvendig, når én offerReference hører til flere ansøgninger i profilen (ellers 409 ambiguousOfferReference).

Guidens webhooks

Programmets webhook (se Webhooks) modtager guidens hændelser uden særskilt abonnement. Signatur, levering og nye forsøg er de samme som for de øvrige hændelser; data indeholder identifier, offerReference, externalApplicationId, guideStatus, occurredAt og sequence (rækkefølgen af hændelserne for ét tilbud) - aldrig dokumentationen, tilbuddets værdier eller adgangslinket.

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

Hver hændelse når en webhook højst én gang (idempotensnøgle = X-Responsiblo-Delivery). En webhook, der oprettes senere, afspiller ikke ældre hændelser, og hændelser ældre end 28 dage meldes ikke længere.

Opbevaring af dokumentationen

Når tilbuddets forløb slutter (gennemført, annulleret, udløbet eller erstattet tilbud), løber opbevaringsperioden fra indstillingerne for jeres guide (som standard 30 dage). Derefter slettes dokumentationen: GET …/evidence returnerer 410 evidenceErased, og status svarer fortsat med evidenceErased: true, referencerne og tidspunkterne. Et aktivt tilbud slettes aldrig. Dokumentation, som I skal opbevare, skal I hente straks efter loanGuide.completed.

Guidens fejl

Fejlene har API'ets form ovenfor. Desuden for guiden:

En fejl gentager aldrig en værdi, som I har sendt. Eksempel: samme tilbud med en betaling på 10.700 CZK i stedet for 10.800 CZK og en gyldighed på 9 dage:

"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 kald i minuttet pr. nøgle. Efter 30 afviste nøgler fra én adresse inden for ti minutter må adressen vente 10 minutter.

Loggen over kald (uden indhold, identifikatoren kun som SHA-256-fingeraftryk) gemmer vi i 180 dage, leverede og opgivne webhookbeskeder i 30 dage.

Status og kontrakt

• GET /v1/status - uden nøgle, returnerer {"status":"ok","version":"1.3.2"}
• GET /openapi - uden nøgle, OpenAPI 3-dokumentet for partner-API'et

Sandbox

Testnøglen rsb_test_... åbner jeres testprogram med det samme kursus. Personer i det ophører efter 7 dage; testprogrammets webhook er adskilt fra produktionens.

Versionshistorik

• 1.3.2 (2026-11) - Hver operation i OpenAPI-dokumentet har et navn og en beskrivelse, og operationerne er inddelt i grupper. /v1/status og webhooks oplyser versionen 1.3.2. Formen på forespørgsler og svar er uændret.
• 1.3.1 (2026-10) - Rettelser uden ændring af endpoints og deres svar.
• 1.3.0 (2026-10) - Låneguide: POST /v1/users/{identifier}/loan-offers, status, dokumentation og annullering af tilbuddet, webhooks loanGuide.*, opbevaring af dokumentationen. Valgfrit felt returnUrl på et tilbud (egen returadresse).
• 1.2.0 (2026-10) - GET /v1/users med sideinddeling, personens certifikat (feltet certificate, GET /v1/users/{identifier}/certificate, hændelsen certificate.issued), DELETE /v1/users/{identifier} (anonymisering), identifikator på højst 64 tegn, opbevaring af loggen.
• 1.1.0 (2026-10) - API-nøgler, POST /v1/users, GET /v1/users/{identifier} med ?include=detail, adgangslink, webhooks, én form for fejl, offentlig status og OpenAPI, grænser.
• 1.0.0 (2024) - GET /v1/user/{identifier} med JWT for partnernøglen.

Vil I have API'et til jeres virksomhed? Skriv til os