За разработчици
Партньорски API
Изпратете ни клиент под собствен псевдонимен идентификатор, без имейл, име и други лични данни, и по всяко време проверете състоянието на обучението му. Служи като проверка за съответствие преди договор, депозит или изплащане.
Версия 1.3.2 · JSON през HTTPS · OpenAPI
Как работи това
API е еднакъв за всички партньори. В пет стъпки:
- Ще включим API за вашата фирма; в своята администрация, в раздела API, ще създадете API ключ.
- Когато клиентът трябва да премине обучение, вашата система извиква POST /v1/users с вашия идентификатор на клиента.
- Създаваме профил без имейл и връщаме входна връзка (entryUrl); показвате я на клиента като бутон.
- Клиентът щраква върху нея и веднага е в курса.
- Състоянието проверявате по всяко време чрез GET /v1/users/{identifier}, или ние го съобщаваме на вашия сървър чрез уебхук.
Вие сте администратор на идентификатора, ние обработваме само псевдонимизирани данни. Като идентификатор никога не изпращайте имейл или име: API отхвърля имейл адрес с грешка 422.
Адрес и удостоверяване
Всяко извикване минава през HTTPS към адреса по-долу и носи вашия API ключ в заглавката Authorization.
https://api.responsiblo.com Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- rsb_live_... отваря вашата продукционна програма, rsb_test_... вашата тестова програма (sandbox).
- Ключът се показва само веднъж, при създаването; съхраняваме само неговия отпечатък. Пазете го като тайна на своя сървър, никога в браузър или в приложение.
- Ключът има права: read (състояние и списък на лицата, сертификат) и write (изпращане и анонимизиране на лица). Може да бъде ограничен до вашите IP адреси и да има срок на валидност.
- Смяна: създавате нов ключ, старият е валиден още 7 дни, след това изтича.
- Отговорите никога не се съхраняват в кеша (Cache-Control: no-store) и API не приема извиквания от браузър (без CORS).
POST /v1/users
Изпраща лице в програмата на ключа (право 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"}'
| Поле | Задължително | Значение |
|---|---|---|
identifier |
да | Вашият псевдоним на лицето, от 1 до 64 знака A-Z a-z 0-9 . _ : @ -; никога имейл адрес (отхвърля се с грешка 422). |
program |
не | Код на програмата; ако го посочите, трябва да е програмата на ключа. |
language |
не | Език на курса (cs, en, ...); по подразбиране първият език на програмата. |
label |
не | Вашият етикет (кохорта или кампания), от 1 до 64 знака, никога лични данни. |
expiresAt |
не | Последен ден на достъпа, ГГГГ-ММ-ДД. |
201 Created за ново лице, 200 OK, когато идентификаторът вече съществува: нищо не се променя и извикването може безопасно да се повтори. Тялото е състоянието по-долу, включително entryUrl. Изчерпан лимит на лицата или на лиценза на програмата връща 403.
GET /v1/users/{identifier}
Състояние на лицето (право read): това, от което се нуждае проверката за съответствие, нищо повече.
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 | Значение |
|---|---|
enrolled |
изпратено, още не е влязло |
started |
влязло, още нищо не е завършило |
in_progress |
има завършени уроци, програмата още не |
completed |
програмата е завършена (completedAt) |
expired |
достъпът е приключил (изтекъл е expiresAt; лице в sandbox приключва след 7 дни) |
quizScore е резултатът от финалния тест в %, щом бъде завършен. Времената са в UTC с точност до цели секунди. Полето certificate съдържа сертификата на лицето (вж. по-долу); докато лицето няма сертификат, е null.
?include=detail
Добавя напредъка във всеки курс и резултата от всеки тест, никога отделните отговори.
"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
Списък на лицата, които сте изпратили в програмата на ключа (право read), по страници: всеки елемент има формата на състоянието по-горе. По избор status (само лицата в това състояние), limit (от 1 до 500, по подразбиране 100) и 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"
- Продължете с cursor = nextCursor, докато nextCursor не е null; курсорът е непрозрачен текст, никога не го съставяйте сами.
- Лицата са подредени по момента на изпращане в стабилен ред (и при еднакъв момент), никое не се повтаря; анонимизираните лица не са в списъка.
- С филтъра status за една страница преглеждаме най-много 2000 лица, затова страницата може да има по-малко елементи от limit или дори нито един; продължавайте, докато има nextCursor.
Сертификат на лицето
Щом лицето завърши програмата, курсът му издава сертификат под неговия псевдоним (прякор на профила ID XXXXXX), без име и без имейл. Нищо не се изпраща по имейл; в състоянието на лицето има поле certificate с номер, времена и публична страница за проверка, а PDF изтегляте чрез 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
- Страницата за проверка verifyUrl показва само псевдонима, програмата, партньора и валидността, никога вашия идентификатор.
- PDF се връща като application/pdf (право read). Без сертификат отговорът е 404 certificateNotFound, а докато PDF още се генерира, 404 certificatePdfNotReady с Retry-After.
- Отнет сертификат никога не се предоставя (полето certificate тогава е null, PDF 404); сертификат с изтекла валидност остава достоверен документ и се предоставя.
- Уебхукът съобщава за сертификата чрез събитието certificate.issued (веднага след user.completed).
DELETE /v1/users/{identifier}
Анонимизира лицето (право write): от профила изчезват вашият идентификатор, етикетът и всяко съобщение на уебхук, което го споменава; входните връзки престават да важат. Сертификатът и резултатът от курса остават под номера на сертификата като доказателство за съответствие.
curl -X DELETE https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY" HTTP/1.1 204 No Content
Отговор 204 без тяло; всяко следващо извикване със същия идентификатор връща 404 userNotFound, така че повторението е безопасно. След това можете да изпратите същия идентификатор отново като ново лице.
Входна връзка
Покажете entryUrl на лицето (бутон „Започнете курса“ във вашата система). Чрез нея лицето влиза в курса, без имейл и без парола.
Връзката е валидна 30 дни и може да се използва многократно; всяко извикване GET /v1/users/{identifier} връща нова. Никога не я изпращайте на никого другиго: който има връзката, влиза като това лице.
Уебхукове
В раздела API на своята администрация настройвате по един уебхук за всяка програма: публичен HTTPS адрес на своя сървър и събития. След това ви изпращаме POST с JSON, само идентификатори и състояния, никога входната връзка.
| Събитие | Кога |
|---|---|
user.enrolled |
лицето е изпратено (първият път, когато вашият уебхук научава за него) |
user.started |
лицето е влязло в курса |
user.completed |
лицето е завършило програмата |
certificate.issued |
лицето е получило сертификат; data съдържа certificate (номер, времена, verifyUrl) |
user.expired |
достъпът на лицето е приключил |
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
}
}
Подпис
Всяко съобщение носи заглавка X-Responsiblo-Signature: t=<unix време>,v1=<HMAC-SHA256 на текста t.тяло с тайната на уебхука, hex>. Тайната (whsec_...) се показва веднъж при създаването на уебхука. Преди да се доверите на съобщението, проверете подписа и давността на t; като ключ за идемпотентност използвайте 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]);
Доставка и повторни опити
Доставено = отговор 2xx в рамките на 10 секунди. В противен случай опитваме отново след 1 минута, 5 минути, 30 минути, 2 часа и 12 часа, след което се отказваме. Пренасочвания не следваме.
20 последователни недоставени съобщения изключват уебхука, докато не го включите отново; съобщенията от този период изчакват. Бутонът „Тестване“ изпраща ping; журнала на доставките ще намерите в своята администрация.
Събитието certificate.issued добавяте към уебхука в неговите настройки; уебхук, създаден преди версия 1.2, не го получава автоматично.
Грешки
Всяка грешка има една и съща форма: status, code, reason и message; грешка 422 добавя errors (поле: какво не е наред).
{ "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 | Какво да направите |
|---|---|---|
| 400 | invalidJson |
изпратете един JSON обект |
| 401 | missingToken, invalidToken |
изпратете валиден ключ (отнетият и изтеклият ключ изглеждат еднакво); заглавката WWW-Authenticate казва Bearer |
| 403 | scopeDenied, ipNotAllowed, apiDisabled, partnerInactive, spaceUnavailable, httpsRequired, userLimitReached, seatsExhausted |
ключът няма право на това, API е изключен за вашата фирма или програмата е пълна |
| 404 | userNotFound, notFound |
в програмата на ключа няма лице с този идентификатор (нито анонимизирано) |
| 404 | certificateNotFound, certificatePdfNotReady |
лицето още няма сертификат или неговият PDF се генерира; опитайте отново след Retry-After |
| 409 | identifierTaken |
идентификаторът принадлежи на лице от друга програма |
| 422 | invalidBody, invalidParameter |
вж. errors (поле на тялото или параметър на заявката: какво не е наред) |
| 429 | rateLimited |
изчакайте Retry-After секунди |
| 500 | internalError |
опитайте по-късно; съобщете на нашата поддръжка incidentId |
За програми и агенти
- Решавайте по code и reason, никога по текста на message; errors е обект поле -> какво не е наред.
- Повтаряйте само 429, 500 и certificatePdfNotReady, и то след Retry-After секунди (иначе с нарастващ интервал); 4xx освен 429 не повтаряйте, без да коригирате извикването.
- POST /v1/users е идемпотентен по identifier (201 първия път, след това 200); DELETE връща 204 първия път и 404 след това, и двете могат безопасно да се повтарят.
- Дедуплицирайте уебхуковете по X-Responsiblo-Delivery; редът на съобщенията не е гарантиран, решава състоянието в data.
Пътеводител за заема
Пътеводителят за заема е кратък курс за кандидата при доставчик на заеми: преди да подпише договора, той преминава три урока, осем практически ситуации и евентуално тест, всичко върху числата на собствената си оферта, и накрая потвърждава офертата. На всеки екран може да поиска обяснение. Изпращате офертата чрез API, получавате входна връзка, а резултата ви съобщава уебхук.
Пътеводителя за заема активираме след споразумение с вас.
И тук кандидатът е само вашият псевдонимизиран профил от POST /v1/users. Офертата се определя от вашите референции (externalApplicationId, offerReference), а документите само от връзка с отпечатък SHA-256, никога от име, имейл, личен идентификационен номер, номер на банкова сметка или телефон. Платформата responsiblo не одобрява заема, не изтегля и не съхранява документите, не проверява самоличността и не издава сертификат за пътеводителя.
- Създавате профил на кандидата: POST /v1/users с вашия псевдоним.
- Изпращате офертата: POST /v1/users/{identifier}/loan-offers; отговорът 201 съдържа entryUrl.
- Предавате entryUrl на кандидата по свой проверен канал. Връзката е валидна 30 дни и може да се използва многократно; пътеводителят показва числата на неговата оферта.
- За края научавате чрез уебхук (loanGuide.completed, loanGuide.assistanceRequested и други).
- Състоянието проверявате чрез GET …/loan-offers/{offerReference}, записа за своето досие чрез GET …/evidence. Променена оферта = нова оферта със supersedes, оттеглено заявление = POST …/cancel.
До активирането операциите на пътеводителя отговарят с 404 notFound или 409 loanGuideNotConfigured. Правото write изпраща и анулира оферта, read чете състоянието и доказателствения запис.
POST /v1/users/{identifier}/loan-offers
Изпраща оферта към профила на кандидата (право write). Незадължителната заглавка Idempotency-Key има от 1 до 255 видими ASCII знака. Пример: заем от 10 000 CZK, за плащане 10 800 CZK с еднократно плащане 30 дни след изплащането, ГПР 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-22T18:00:00Z"
}'
HTTP/1.1 201 Created
{
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"offerStatus": "active",
"guideStatus": "created",
"validUntil": "2026-11-22T18:00:00Z",
"snapshotSha256": "8055bfa3c5f2c163691b85785eaf61221169a123bed67aff2c1dbaf2a8e44e7e",
"entryUrl": "https://your-company.responsiblo.com/entry/...",
"createdAt": "2026-11-17T09:14:05Z"
}
| Поле | Задължително | Значение |
|---|---|---|
externalApplicationId |
да | Вашият номер на заявлението, от 1 до 128 знака A-Z a-z 0-9 . _ : -; никога имейл адрес. |
offerReference |
да | Вашата референция на офертата, същите правила като за externalApplicationId. |
locale |
да | Език и държава на пътеводителя: cs-CZ. |
currency |
да | Валута: CZK. |
principalMinor |
да | Размер на заема в халери, цяло число от 1 до 10 000 000 000. |
disbursedAmountMinor |
да | Изплатена сума в халери; трябва да е равна на размера на заема. |
totalPayableMinor |
да | Обща сума за плащане в халери; най-малко размерът на заема и точно сборът на плащанията. |
aprPercent |
да | ГПР в проценти като текст ("155.10"), изчислен и гарантиран от вас. Положителни разходи с ГПР 0 API отхвърля. |
interestRate |
не | Лихвен процент {percent, period}, period = year, month или day. |
repayment |
да | Погасяване: singlePayment {amountMinor, due} с дата (kind date) или брой дни от изплащането (kind relative, от 1 до 365), или installments {schedule: [{date, amountMinor}]} с от 1 до 360 вноски във възходящ ред, нито една в миналото. Типът трябва да отговаря на продукта, настроен за вашия пътеводител. |
documents |
да | От 2 до 10 документа {role, reference, title, url, sha256}; те трябва да покриват ролите, които изискват настройките на вашия пътеводител (по подразбиране precontract_information и contract_package). url само HTTPS на хост, разрешен в настройките на вашия пътеводител, най-много 2 048 знака, без данни за вход; sha256 = 64 шестнадесетични знака, които декларирате вие. |
validUntil |
да | Валидност на офертата, RFC 3339 с часово отместване, в бъдещето и най-много 7 дни напред. |
supersedes |
не | offerReference на активната оферта на същия профил, която новата оферта заменя. |
returnUrl |
не | Незадължително: адрес, към който страницата „Готово“ връща кандидата след завършване на пътеводителя. Само абсолютен HTTPS, най-много 2 048 знака, без данни за вход; символите {offerReference} и {externalApplicationId} заменяме с референциите на офертата. Без него важи адресът за връщане от настройките на вашия пътеводител. |
Същото тяло отново (под същите референции или със същия Idempotency-Key) връща 200 със съществуващата оферта и нов entryUrl; друго тяло под тях връща 409 offerConflict. Профилът има една активна оферта: следваща без supersedes връща 409 activeOfferExists, грешно supersedes 409 notSupersedable. В този момент настройките на вашия пътеводител (тест, контакт) се заключват към офертата.
Състояние, доказателствен запис и анулиране
GET /v1/users/{identifier}/loan-offers/{offerReference}- състояние (право read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), завършени уроци, практика, тест (null, когато е изключен) и моментите на представяне на офертата, на потвърждението и на искането за обяснение. Никога отговорите, стойностите на офертата или връзката. Завършването остава, дори ако офертата по-късно изтече.GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence- запис за вашето досие (право read): schemaVersion loan-guide-evidence/1, моментна снимка на вашата оферта с отпечатък snapshotSha256, издание на курса с отпечатъци на уроците, събития в реда на sequence, всеки отговор с всички опити, потвърждение и limitations, тоест какво записът не доказва (представено не означава прочетено, самоличността я твърдите вие, документите са само чрез връзка, никакъв сертификат, никакво одобрение на заем).POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel- анулира активна оферта (право write), reasonCode = withdrawn_by_provider или application_closed; 200 връща състоянието, оферта, която не е активна или има завършен пътеводител, връща 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-17T18:32:47Z",
"confirmedAt": "2026-11-17T18:34:02Z",
"completedAt": "2026-11-17T18:34:02Z",
"assistanceRequested": false,
"assistanceRequestedAt": null,
"validUntil": "2026-11-22T18: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= е необходим само когато една offerReference принадлежи към няколко заявления на профила (иначе 409 ambiguousOfferReference).
Уебхукове на пътеводителя
Уебхукът на програмата (вж. Уебхукове) получава събитията на пътеводителя без отделен абонамент. Подписът, доставката и повторните опити са същите като при останалите събития; data съдържа identifier, offerReference, externalApplicationId, guideStatus, occurredAt и sequence (редът на събитията на една оферта), никога доказателствения запис, стойностите на офертата или входната връзка.
| Събитие | Кога |
|---|---|
loanGuide.completed |
кандидатът е преминал пътеводителя и е потвърдил офертата |
loanGuide.assistanceRequested |
кандидатът е поискал обяснение (обадете му се) |
loanGuide.expired |
на офертата е изтекъл validUntil |
loanGuide.superseded |
офертата е заменена с нова (supersedes) |
loanGuide.cancelled |
анулирали сте офертата |
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=1794940447,v1=8b2d...4c
{
"id": "0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08",
"type": "loanGuide.completed",
"createdAt": "2026-11-17T18: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-17T18:34:02Z",
"sequence": 23
}
}
Всяко събитие достига до даден уебхук най-много веднъж (ключ за идемпотентност = X-Responsiblo-Delivery). Уебхук, създаден по-късно, не възпроизвежда по-стари събития, а събития, по-стари от 28 дни, вече не се съобщават.
Срок на съхранение на доказателствения запис
Когато пътят на офертата приключи (завършена, анулирана, изтекла или заменена оферта), започва да тече срокът на съхранение от настройките на вашия пътеводител (по подразбиране 30 дни). След това доказателственият запис се изтрива: GET …/evidence връща 410 evidenceErased, а състоянието продължава да отговаря с evidenceErased: true, референциите и моментите. Активна оферта никога не се изтрива. Доказателствения запис, който трябва да съхранявате, изтеглете веднага след loanGuide.completed.
Грешки на пътеводителя
Грешките имат формата на API по-горе. Допълнително за пътеводителя:
| HTTP | reason | Какво да направите |
|---|---|---|
| 404 | offerNotFound |
профилът няма такава оферта (userNotFound = профилът не съществува) |
| 409 | offerConflict, activeOfferExists, notSupersedable |
референциите или Idempotency-Key вече принадлежат на друго тяло, или профилът има друга активна оферта: изпратете supersedes |
| 409 | loanGuideNotConfigured |
пътеводителят не е активиран за вашата програма: пишете ни |
| 409 | ambiguousOfferReference |
добавете ?externalApplicationId= |
| 409 | notActive |
офертата не е активна или има завършен пътеводител |
| 410 | evidenceErased |
доказателственият запис е изтрит след срока на съхранение, състоянието остава |
| 422 | invalidOffer |
errors = {път: код[,код]} с пътя в тялото (repayment.schedule[2].date, documents[0].url); кодовете са в таблицата по-долу |
| 422 | invalidBody |
supersedes, Idempotency-Key или тялото на анулирането |
errors | Кодове на грешката invalidOffer |
|---|---|
required |
полето липсва |
invalidFormat |
грешна форма (тип, шаблон, дължина, връзка без HTTPS или с данни за вход) |
outOfRange |
извън разрешения диапазон (сума, брой документи, вноски или дни) |
notEqualPrincipal |
изплатената сума не е равна на размера на заема |
sumMismatch |
сборът на плащанията не е равен на общата сума за плащане |
belowPrincipal |
общата сума за плащане е по-ниска от размера на заема |
aprContradiction |
ГПР 0 при положителни разходи |
typeMismatch |
типът погасяване не отговаря на продукта, настроен за вашия пътеводител |
missingRole |
липсва документ с роля, която настройките на вашия пътеводител изискват |
hostNotAllowed |
връзката на документа сочи към хост, който настройките на вашия пътеводител не разрешават |
notAscending |
датите на вноските не са във възходящ ред или се повтарят |
inPast |
датата на вноска или validUntil е в миналото |
tooFar |
validUntil е повече от 7 дни напред |
unsupported |
неподдържана стойност (locale, currency, type, period, kind) |
unknownField |
поле, което API не познава |
looksLikeEmail |
референцията изглежда като имейл адрес |
Грешката никога не повтаря стойност, която сте изпратили. Пример: същата оферта с плащане 10 700 CZK вместо 10 800 CZK и валидност 9 дни:
"repayment": { "type": "singlePayment", "amountMinor": 1070000, "due": { "kind": "relative", "days": 30, "anchor": "disbursement" } },
"validUntil": "2026-11-26T18: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"
}
}
Лимити
120 извиквания на минута на ключ. След 30 отхвърлени ключа от един адрес в рамките на десет минути адресът изчаква 10 минути.
Журнала на извикванията (без тела, идентификаторът само като отпечатък SHA-256) съхраняваме 180 дни, доставените и изоставените съобщения на уебхуковете 30 дни.
Статус и спецификация
GET /v1/status- без ключ, връща {"status":"ok","version":"1.3.2"}GET /openapi- без ключ, документ OpenAPI 3 на партньорския API
Sandbox
Тестовият ключ rsb_test_... отваря вашата тестова програма със същия курс. Лицата в нея приключват след 7 дни; уебхукът на тестовата програма е отделен от продукционния.
История на версиите
- 1.3.2 (2026-11) - Всяка операция в документа OpenAPI има наименование и описание, а операциите са разделени на групи. /v1/status и уебхуковете отчитат версия 1.3.2. Формите на заявките и отговорите са без промяна.
- 1.3.1 (2026-10) - Корекции без промяна на крайните точки и техните отговори.
- 1.3.0 (2026-10) - Пътеводител за заема: POST /v1/users/{identifier}/loan-offers, състояние, доказателствен запис и анулиране на оферта, уебхукове loanGuide.*, срок на съхранение на доказателствения запис. Незадължителен адрес за връщане returnUrl към офертата.
- 1.2.0 (2026-10) - GET /v1/users със странициране, сертификат на лицето (поле certificate, GET /v1/users/{identifier}/certificate, събитие certificate.issued), DELETE /v1/users/{identifier} (анонимизиране), идентификатор най-много 64 знака, срок на съхранение на журнала.
- 1.1.0 (2026-10) - API ключове, POST /v1/users, GET /v1/users/{identifier} с ?include=detail, входна връзка, уебхукове, единна форма на грешките, публичен статус и OpenAPI, лимити.
- 1.0.0 (2024) - GET /v1/user/{identifier} с JWT на партньорски ключ.
Искате ли API за своята фирма? Пишете ни