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:
- Otamme API:n käyttöön yrityksellesi; luot hallinnassasi API-välilehdellä API-avaimen.
- Kun asiakas pitää kouluttaa, järjestelmäsi kutsuu POST /v1/users omalla asiakastunnisteellasi.
- Luomme profiilin ilman sähköpostia ja palautamme aloituslinkin (entryUrl); näytät sen asiakkaalle painikkeena.
- Asiakas napsauttaa sitä ja on suoraan kurssilla.
- 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ä | Pakollinen | Merkitys |
|---|---|---|
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/..."
}
status | Merkitys |
|---|---|
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ä.
| Tapahtuma | Milloin |
|---|---|
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" } }
| HTTP | reason | Mitä 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.
- Luot hakijan profiilin: POST /v1/users omalla pseudonyymilläsi.
- Lähetät tarjouksen: POST /v1/users/{identifier}/loan-offers; vastaus 201 sisältää kentän entryUrl.
- 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.
- Lopusta saat tiedon webhookilla (loanGuide.completed, loanGuide.assistanceRequested ja muut).
- 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ä | Pakollinen | Merkitys |
|---|---|---|
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ä.
| Tapahtuma | Milloin |
|---|---|
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:
| HTTP | reason | Mitä 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 |
errors | Virheen 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