responsiblo

Kehittäjille

Kumppani-API

Lähetä meille asiakas omalla pseudonyymisellä tunnisteellasi - ilman sähköpostia, nimeä ja muita henkilötietoja - ja lue milloin tahansa hänen koulutuksensa tila. Se toimii compliance-tarkistuksena ennen sopimusta, talletusta tai maksua.

Versio 1.3.2 · JSON HTTPS:n kautta · OpenAPI

Näin se toimii

API on kaikille kumppaneille sama. Viidessä vaiheessa:

  1. Otamme API:n käyttöön yrityksellesi; luot hallinnassasi API-välilehdellä API-avaimen.
  2. Kun asiakas pitää kouluttaa, järjestelmäsi kutsuu POST /v1/users omalla asiakastunnisteellasi.
  3. Luomme profiilin ilman sähköpostia ja palautamme aloituslinkin (entryUrl); näytät sen asiakkaalle painikkeena.
  4. Asiakas napsauttaa sitä ja on suoraan kurssilla.
  5. Luet tilan milloin tahansa kutsulla GET /v1/users/{identifier}, tai ilmoitamme sen palvelimellesi webhookilla.

Sinä olet tunnisteen rekisterinpitäjä, me käsittelemme vain pseudonymisoituja tietoja. Älä koskaan lähetä tunnisteena sähköpostiosoitetta tai nimeä - API hylkää sähköpostiosoitteen virheellä 422.

Osoite ja todennus

Jokainen kutsu kulkee HTTPS:n kautta alla olevaan osoitteeseen ja sisältää API-avaimesi otsakkeessa Authorization.

https://api.responsiblo.com
Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • rsb_live_... avaa tuotanto-ohjelmasi, rsb_test_... testiohjelmasi (sandbox).
  • Avain näytetään vain kerran, kun se luodaan; säilytämme siitä vain sormenjäljen. Pidä se salaisuutena palvelimellasi - ei koskaan selaimessa eikä sovelluksessa.
  • Avaimella on oikeudet: read (henkilöiden tila ja luettelo, todistus) ja write (henkilöiden lähettäminen ja anonymisointi). Se voi olla rajattu IP-osoitteisiisi ja sillä voi olla voimassaoloaika.
  • Vaihto: luot uuden avaimen, vanha on voimassa vielä 7 päivää ja vanhenee sitten.
  • Vastauksia ei koskaan tallenneta välimuistiin (Cache-Control: no-store), eikä API ota vastaan kutsuja selaimesta (ei CORS:ia).

POST /v1/users

Lähettää henkilön avaimen ohjelmaan (oikeus 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"}'
KenttäPakollinenMerkitys
identifier kyllä Henkilön pseudonyymisi, 1-64 merkkiä A-Z a-z 0-9 . _ : @ -; ei koskaan sähköpostiosoite (hylätään virheellä 422).
program ei Ohjelman koodi; jos annat sen, sen on oltava avaimen ohjelma.
language ei Kurssin kieli (cs, en, ...); oletuksena ohjelman ensimmäinen kieli.
label ei Oma merkintäsi - kohortti tai kampanja, 1-64 merkkiä, ei koskaan henkilötieto.
expiresAt ei Pääsyn viimeinen päivä, VVVV-KK-PP.

201 Created uudelle henkilölle, 200 OK, kun tunniste on jo olemassa - mikään ei muutu, kutsun voi turvallisesti toistaa. Runko on alla kuvattu tila entryUrl mukaan lukien. Käytetty henkilöraja tai ohjelman lisenssien raja palauttaa 403.

GET /v1/users/{identifier}

Henkilön tila (oikeus read): se, mitä compliance-tarkistus tarvitsee, ei mitään ylimääräistä.

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/..."
}
statusMerkitys
enrolled lähetetty, ei ole vielä tullut sisään
started tullut sisään, ei vielä suorittanut mitään
in_progress on suorittanut oppitunteja, ohjelmaa ei vielä
completed ohjelma on suoritettu (completedAt)
expired pääsy on päättynyt (expiresAt on ohitettu; sandboxin henkilö päättyy 7 päivän kuluttua)

quizScore on lopputietovisan tulos prosentteina (%), kun se on suoritettu. Ajat ovat UTC-aikaa kokonaisin sekunnein. Kenttä certificate sisältää henkilön todistuksen (ks. alla); niin kauan kuin hänellä ei ole sitä, arvo on null.

?include=detail

Lisää edistymisen jokaisella kurssilla ja jokaisen tietovisan tuloksen - ei koskaan yksittäisiä vastauksia.

"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

Luettelo henkilöistä, jotka olet lähettänyt avaimen ohjelmaan (oikeus read), sivu kerrallaan: jokaisella kohteella on yllä kuvatun tilan muoto. Valinnaisesti status (vain tässä tilassa olevat henkilöt), limit (1-500, oletus 100) ja 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"
  • Jatka arvolla cursor = nextCursor, kunnes nextCursor on null; kursori on läpinäkymätön teksti, älä koskaan kokoa sitä itse.
  • Henkilöt tulevat lähetyshetken mukaan pysyvässä järjestyksessä (myös samalla hetkellä), kukaan ei kahdesti; anonymisoidut henkilöt eivät ole luettelossa.
  • Suodattimella status käymme yhtä sivua varten läpi enintään 2000 henkilöä, joten sivulla voi olla vähemmän kohteita kuin limit, jopa ei yhtään - jatka niin kauan kuin nextCursor on olemassa.

Henkilön todistus

Heti kun henkilö suorittaa ohjelman, kurssi myöntää hänelle todistuksen - hänen pseudonyymillään (profiilin nimimerkki ID XXXXXX), ilman nimeä ja ilman sähköpostia. Mitään ei lähetetä sähköpostilla; henkilön tilassa on kenttä certificate, jossa on numero, ajat ja julkinen tarkistussivu, ja PDF:n lataat kutsulla 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
  • Tarkistussivu verifyUrl näyttää vain pseudonyymin, ohjelman, kumppanin ja voimassaolon - ei koskaan tunnistettasi.
  • PDF palauttaa application/pdf (oikeus read). Ilman todistusta vastaus on 404 certificateNotFound, ja kun PDF:ää vasta tehdään, 404 certificatePdfNotReady ja Retry-After.
  • Peruutettua todistusta ei koskaan luovuteta (kenttä certificate on silloin null, PDF 404); todistus, jonka voimassaolo on päättynyt, on edelleen paikkansapitävä tosite ja se luovutetaan.
  • Webhook ilmoittaa todistuksesta tapahtumalla certificate.issued (heti tapahtuman user.completed jälkeen).

DELETE /v1/users/{identifier}

Anonymisoi henkilön (oikeus write): profiilista poistuvat tunnisteesi, merkintä ja jokainen webhook-viesti, jossa tunniste mainitaan; aloituslinkit lakkaavat toimimasta. Todistus ja kurssin tulos säilyvät todistuksen numerolla - compliance-tositteena.

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

HTTP/1.1 204 No Content

Vastaus 204 ilman runkoa; jokainen myöhempi kutsu samalla tunnisteella palauttaa 404 userNotFound, joten toistaminen on turvallista. Saman tunnisteen voit sen jälkeen lähettää uudelleen uutena henkilönä.

Aloituslinkki

Näytä entryUrl henkilölle (painike Aloita kurssi järjestelmässäsi). Se kirjaa henkilön kurssille - ilman sähköpostia ja ilman salasanaa.

Linkki on voimassa 30 päivää ja sitä voi käyttää toistuvasti; jokainen kutsu GET /v1/users/{identifier} palauttaa uuden. Älä koskaan lähetä sitä kenellekään muulle: jolla on linkki, pääsee sisään kyseisenä henkilönä.

Webhookit

Hallintasi API-välilehdellä asetat jokaiselle ohjelmalle yhden webhookin: palvelimesi julkisen HTTPS-osoitteen ja tapahtumat. Sen jälkeen lähetämme sinulle POST-kutsun, jossa on JSON - vain tunnisteet ja tilat, ei koskaan aloituslinkkiä.

TapahtumaMilloin
user.enrolled henkilö on lähetetty (ensimmäinen kerta, kun webhookisi tuntee hänet)
user.started henkilö on tullut kurssille
user.completed henkilö on suorittanut ohjelman
certificate.issued henkilö on saanut todistuksen; data sisältää kentän certificate (numero, ajat, verifyUrl)
user.expired henkilön pääsy on päättynyt
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
  }
}

Allekirjoitus

Jokaisessa viestissä on otsake X-Responsiblo-Signature: t=<Unix-aika>,v1=<HMAC-SHA256 tekstistä t.runko webhookin salaisuudella, hex>. Salaisuus (whsec_...) näytetään kerran webhookin luomisen yhteydessä. Ennen kuin luotat viestiin, tarkista allekirjoitus ja t:n ikä; käytä idempotenssiavaimena otsaketta 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]);

Toimitus ja uusintayritykset

Toimitettu = vastaus 2xx 10 sekunnin kuluessa. Muuten yritämme uudelleen 1 minuutin, 5 minuutin, 30 minuutin, 2 tunnin ja 12 tunnin kuluttua, sitten luovutamme. Uudelleenohjauksia emme seuraa.

20 peräkkäistä toimittamatonta viestiä kytkee webhookin pois päältä, kunnes kytket sen uudelleen päälle; tuon ajan viestit odottavat. Painike Test lähettää pingin; toimitusloki löytyy hallinnastasi.

Tapahtuman certificate.issued lisäät webhookille sen asetuksissa; ennen versiota 1.2 luotu webhook ei saa sitä itsestään.

Virheet

Jokaisella virheellä on yksi muoto: status, code, reason ja message; virhe 422 lisää kentän errors (kenttä - mikä on vialla).

{ "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" } }
HTTPreasonMitä tehdä
400 invalidJson lähetä yksi JSON-objekti
401 missingToken, invalidToken lähetä voimassa oleva avain (peruutettu ja vanhentunut avain näyttävät samalta); otsake WWW-Authenticate sanoo Bearer
403 scopeDenied, ipNotAllowed, apiDisabled, partnerInactive, spaceUnavailable, httpsRequired, userLimitReached, seatsExhausted avain ei saa tehdä tätä, API on poistettu käytöstä yritykseltäsi tai ohjelma on täynnä
404 userNotFound, notFound avaimen ohjelmassa ei ole henkilöä tällä tunnisteella (ei myöskään anonymisoitua)
404 certificateNotFound, certificatePdfNotReady henkilöllä ei vielä ole todistusta tai sen PDF:ää tehdään - yritä uudelleen ajan Retry-After jälkeen
409 identifierTaken tunniste kuuluu toisen ohjelman henkilölle
422 invalidBody, invalidParameter katso errors (rungon kenttä tai kyselyn parametri - mikä on vialla)
429 rateLimited odota Retry-After sekuntia
500 internalError yritä myöhemmin uudelleen; ilmoita tukeemme incidentId

Ohjelmille ja agenteille

  • Päätä kenttien code ja reason perusteella, ei koskaan kentän message tekstin perusteella; errors on objekti kenttä -> mikä on vialla.
  • Toista vain 429, 500 ja certificatePdfNotReady, ja vasta Retry-After sekunnin kuluttua (muuten kasvavin välein); muita 4xx-virheitä kuin 429 älä toista korjaamatta kutsua.
  • POST /v1/users on idempotentti tunnisteen identifier mukaan (201 ensimmäisellä kerralla, sitten 200); DELETE palauttaa 204 ensimmäisellä kerralla ja sen jälkeen 404 - molemmat voi turvallisesti toistaa.
  • Poista webhookien kaksoiskappaleet otsakkeen X-Responsiblo-Delivery perusteella; viestien järjestystä ei taata, ratkaiseva on tila kentässä data.

Lainaopas

Lainaopas on lyhyt kurssi lainanantajan hakijalle: ennen sopimuksen allekirjoittamista hakija käy läpi kolme oppituntia, kahdeksan käytännön tilannetta ja mahdollisesti tietovisan, kaikki oman tarjouksensa luvuilla, ja vahvistaa lopuksi tarjouksen. Jokaisella näytöllä hakija voi pyytää selitystä. Lähetät tarjouksen API:n kautta, saat aloituslinkin ja webhook ilmoittaa sinulle tuloksen.

Otamme lainaoppaan käyttöön kanssasi sovitusti.

Hakija on tässäkin vain pseudonyyminen profiilisi kutsusta POST /v1/users. Tarjouksen yksilöivät viitteesi (externalApplicationId, offerReference), ja asiakirjoista on vain linkki ja SHA-256-sormenjälki - ei koskaan nimeä, sähköpostia, henkilötunnusta, tilinumeroa eikä puhelinnumeroa. responsiblo ei hyväksy lainaa, ei lataa eikä tallenna asiakirjoja, ei tarkista henkilöllisyyttä eikä myönnä oppaasta todistusta.

  1. Luot hakijan profiilin: POST /v1/users omalla pseudonyymilläsi.
  2. Lähetät tarjouksen: POST /v1/users/{identifier}/loan-offers; vastaus 201 sisältää kentän entryUrl.
  3. Toimitat linkin entryUrl hakijalle omaa varmennettua kanavaasi pitkin. Linkki on voimassa 30 päivää ja sitä voi käyttää toistuvasti; opas näyttää hakijan tarjouksen luvut.
  4. Lopusta saat tiedon webhookilla (loanGuide.completed, loanGuide.assistanceRequested ja muut).
  5. Tilan luet kutsulla GET …/loan-offers/{offerReference}, tallenteen omaan arkistoosi kutsulla GET …/evidence. Muuttunut tarjous = uusi tarjous, jossa on supersedes, peruttu hakemus = POST …/cancel.

Ennen käyttöönottoa oppaan toiminnot vastaavat 404 notFound tai 409 loanGuideNotConfigured. Oikeus write lähettää ja peruu tarjouksen, read lukee tilan ja todisteaineiston.

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

Lähettää tarjouksen hakijan profiiliin (oikeus write). Valinnaisessa otsakkeessa Idempotency-Key on 1-255 näkyvää ASCII-merkkiä. Esimerkki: laina 10 000 CZK, maksettavaa 10 800 CZK yhdellä maksulla 30 päivää maksatuksen jälkeen, todellinen vuosikorko 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"
}
KenttäPakollinenMerkitys
externalApplicationId kyllä Hakemuksesi numero, 1-128 merkkiä A-Z a-z 0-9 . _ : -; ei koskaan sähköpostiosoite.
offerReference kyllä Tarjouksesi viite, samat säännöt kuin kentällä externalApplicationId.
locale kyllä Oppaan kieli ja maa: cs-CZ.
currency kyllä Valuutta: CZK.
principalMinor kyllä Lainan määrä korunan sadasosina, kokonaisluku väliltä 1-10 000 000 000.
disbursedAmountMinor kyllä Lainan maksatusmäärä korunan sadasosina; sen on oltava sama kuin lainan määrä.
totalPayableMinor kyllä Takaisin maksettava kokonaismäärä korunan sadasosina; vähintään lainan määrä ja täsmälleen maksujen summa.
aprPercent kyllä Todellinen vuosikorko prosentteina tekstinä ("155.10"), jonka sinä lasket ja takaat. API hylkää positiiviset kulut, joiden todellinen vuosikorko on 0.
interestRate ei Korko {percent, period}, period = year, month tai day.
repayment kyllä Takaisinmaksu: singlePayment {amountMinor, due} päivämäärällä (kind date) tai päivien määrällä maksatuksesta (kind relative, 1-365), tai installments {schedule: [{date, amountMinor}]}, jossa on 1-360 erää nousevassa järjestyksessä, ei yhtään menneisyydessä. Tyypin on vastattava oppaallesi asetettua tuotetta.
documents kyllä 2-10 asiakirjaa {role, reference, title, url, sha256}; niiden on katettava roolit, joita oppaasi asetukset vaativat (oletuksena precontract_information ja contract_package). url vain HTTPS oppaasi asetuksissa sallitulla isäntäpalvelimella, enintään 2 048 merkkiä, ilman kirjautumistietoja; sha256 = 64 heksadesimaalimerkkiä, jotka sinä ilmoitat.
validUntil kyllä Tarjouksen voimassaolo, RFC 3339 aikavyöhykepoikkeamalla, tulevaisuudessa ja enintään 7 päivää eteenpäin.
supersedes ei Saman profiilin aktiivisen tarjouksen offerReference, jonka uusi tarjous korvaa.
returnUrl ei Valinnainen: osoite, johon Valmis-sivu palauttaa hakijan oppaan lopussa. Vain absoluuttinen HTTPS, enintään 2 048 merkkiä, ilman kirjautumistietoja; korvaamme symbolit {offerReference} ja {externalApplicationId} tarjouksen viitteillä. Ilman sitä käytetään oppaasi asetusten paluuosoitetta.

Sama runko uudelleen (samoilla viitteillä tai samalla otsakkeella Idempotency-Key) palauttaa 200 ja olemassa olevan tarjouksen sekä uuden linkin entryUrl; eri runko niillä palauttaa 409 offerConflict. Profiililla on yksi aktiivinen tarjous: seuraava ilman kenttää supersedes palauttaa 409 activeOfferExists, virheellinen supersedes 409 notSupersedable. Oppaasi asetukset (tietovisa, yhteystieto) lukitaan tarjoukseen sillä hetkellä.

Tila, todisteaineisto ja peruutus

  • GET /v1/users/{identifier}/loan-offers/{offerReference} - tila (oikeus read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), suoritetut oppitunnit, käytännön tilanteet, tietovisa (null, kun se on pois päältä) sekä tarjouksen esittämisen, vahvistuksen ja selityspyynnön ajankohdat. Ei koskaan vastauksia, tarjouksen arvoja eikä linkkiä. Suoritus säilyy, vaikka tarjous myöhemmin vanhenisi.
  • GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - tallenne omaan arkistoosi (oikeus read): schemaVersion loan-guide-evidence/1, tilannevedos tarjouksestasi sormenjäljellä snapshotSha256, kurssin versio oppituntien sormenjäljillä, tapahtumat järjestyksessä sequence, jokainen vastaus kaikkine yrityksineen, vahvistus ja limitations - mitä tallenne ei todista (esitetty ei tarkoita luettua, henkilöllisyyden ilmoitat sinä, asiakirjat vain viittauksena, ei todistusta, ei lainan hyväksyntää).
  • POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - peruu aktiivisen tarjouksen (oikeus write), reasonCode = withdrawn_by_provider tai application_closed; 200 palauttaa tilan, tarjous, joka ei ole aktiivinen tai jonka opas on suoritettu, palauttaa 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= tarvitaan vain, kun yksi offerReference kuuluu profiilin useampaan hakemukseen (muuten 409 ambiguousOfferReference).

Oppaan webhookit

Ohjelman webhook (ks. Webhookit) saa oppaan tapahtumat ilman erillistä tilausta. Allekirjoitus, toimitus ja uusintayritykset ovat samat kuin muissa tapahtumissa; data sisältää kentät identifier, offerReference, externalApplicationId, guideStatus, occurredAt ja sequence (yhden tarjouksen tapahtumien järjestys) - ei koskaan todisteaineistoa, tarjouksen arvoja eikä aloituslinkkiä.

TapahtumaMilloin
loanGuide.completed hakija kävi oppaan läpi ja vahvisti tarjouksen
loanGuide.assistanceRequested hakija pyysi selitystä (soita hänelle)
loanGuide.expired tarjouksen validUntil umpeutui
loanGuide.superseded uusi tarjous korvasi sen (supersedes)
loanGuide.cancelled peruit tarjouksen
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
  }
}

Jokainen tapahtuma tulee yhdelle webhookille enintään kerran (idempotenssiavain = X-Responsiblo-Delivery). Myöhemmin luotu webhook ei toista vanhempia tapahtumia, eikä yli 28 päivää vanhoista tapahtumista enää ilmoiteta.

Todisteaineiston säilytysaika

Kun tarjouksen polku päättyy (suoritettu, peruttu, vanhentunut tai korvattu tarjous), alkaa kulua oppaasi asetusten säilytysaika (oletuksena 30 päivää). Sen jälkeen todisteaineisto poistetaan: GET …/evidence palauttaa 410 evidenceErased ja tila vastaa edelleen arvolla evidenceErased: true, viitteillä ja ajankohdilla. Aktiivista tarjousta ei koskaan poisteta. Todisteaineiston, joka sinun on säilytettävä, lataa heti tapahtuman loanGuide.completed jälkeen.

Oppaan virheet

Virheillä on yllä kuvattu API:n muoto. Lisäksi oppaalle:

HTTPreasonMitä tehdä
404 offerNotFound profiililla ei ole tällaista tarjousta (userNotFound = profiilia ei ole)
409 offerConflict, activeOfferExists, notSupersedable viitteet tai Idempotency-Key kuuluvat jo toiselle rungolle, tai profiililla on toinen aktiivinen tarjous - lähetä supersedes
409 loanGuideNotConfigured opasta ei ole otettu käyttöön ohjelmallesi - kirjoita meille
409 ambiguousOfferReference lisää ?externalApplicationId=
409 notActive tarjous ei ole aktiivinen tai sen opas on suoritettu
410 evidenceErased todisteaineisto poistettiin säilytysajan jälkeen, tila säilyy
422 invalidOffer errors = {polku: koodi[,koodi]}, jossa polku rungossa (repayment.schedule[2].date, documents[0].url); koodit alla olevassa taulukossa
422 invalidBody supersedes, Idempotency-Key tai peruutuksen runko
errorsVirheen invalidOffer koodit
required kenttä puuttuu
invalidFormat väärä muoto (tyyppi, kuvio, pituus, linkki ilman HTTPS:ää tai kirjautumistiedoilla)
outOfRange sallitun alueen ulkopuolella (summa, asiakirjojen, erien tai päivien määrä)
notEqualPrincipal maksatusmäärä ei ole sama kuin lainan määrä
sumMismatch maksujen summa ei ole sama kuin takaisin maksettava kokonaismäärä
belowPrincipal takaisin maksettava kokonaismäärä on pienempi kuin lainan määrä
aprContradiction todellinen vuosikorko 0 positiivisilla kuluilla
typeMismatch takaisinmaksun tyyppi ei vastaa oppaallesi asetettua tuotetta
missingRole asiakirja, jonka roolia oppaasi asetukset vaativat, puuttuu
hostNotAllowed asiakirjan linkki osoittaa isäntäpalvelimeen, jota oppaasi asetukset eivät salli
notAscending erien päivämäärät eivät ole nousevassa järjestyksessä tai toistuvat
inPast erän päivämäärä tai validUntil on menneisyydessä
tooFar validUntil on yli 7 päivää eteenpäin
unsupported tukematon arvo (locale, currency, type, period, kind)
unknownField kenttä, jota API ei tunne
looksLikeEmail viite näyttää sähköpostiosoitteelta

Virhe ei koskaan toista lähettämääsi arvoa. Esimerkki: sama tarjous, jossa maksu on 10 700 CZK eikä 10 800 CZK ja voimassaolo 9 päivää:

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

Rajat

120 kutsua minuutissa avainta kohden. Kun yhdestä osoitteesta tulee kymmenen minuutin aikana 30 hylättyä avainta, osoite odottaa 10 minuuttia.

Kutsujen lokia (ilman runkoja, tunniste vain SHA-256-sormenjälkenä) säilytämme 180 päivää, toimitettuja ja luovutettuja webhook-viestejä 30 päivää.

Tila ja sopimus

  • GET /v1/status - ilman avainta, palauttaa {"status":"ok","version":"1.3.2"}
  • GET /openapi - ilman avainta, kumppani-API:n OpenAPI 3 -dokumentti

Sandbox

Testiavain rsb_test_... avaa testiohjelmasi samalla kurssilla. Siellä olevat henkilöt päättyvät 7 päivän kuluttua; testiohjelman webhook on erillään tuotannon webhookista.

Versiohistoria

  • 1.3.2 (2026-11) - Jokaisella OpenAPI-dokumentin toiminnolla on nimi ja kuvaus, ja toiminnot on jaettu ryhmiin. /v1/status ja webhookit ilmoittavat version 1.3.2. Pyyntöjen ja vastausten muoto pysyy ennallaan.
  • 1.3.1 (2026-10) - Korjauksia; rajapintapäätepisteet ja niiden vastaukset pysyvät ennallaan.
  • 1.3.0 (2026-10) - Lainaopas: POST /v1/users/{identifier}/loan-offers, tarjouksen tila, todisteaineisto ja peruutus, webhookit loanGuide.*, todisteaineiston säilytysaika. Tarjouksen valinnainen kenttä returnUrl (oma paluuosoite).
  • 1.2.0 (2026-10) - GET /v1/users sivutettuna, henkilön todistus (kenttä certificate, GET /v1/users/{identifier}/certificate, tapahtuma certificate.issued), DELETE /v1/users/{identifier} (anonymisointi), tunniste enintään 64 merkkiä, lokin säilytys.
  • 1.1.0 (2026-10) - API-avaimet, POST /v1/users, GET /v1/users/{identifier} parametrilla ?include=detail, aloituslinkki, webhookit, yksi virhemuoto, julkinen tila ja OpenAPI, rajat.
  • 1.0.0 (2024) - GET /v1/user/{identifier} kumppaniavaimen JWT:llä.

Haluatko API:n yrityksellesi? Kirjoita meille