responsiblo

За разработчици

Партньорски API

Изпратете ни клиент под собствен псевдонимен идентификатор, без имейл, име и други лични данни, и по всяко време проверете състоянието на обучението му. Служи като проверка за съответствие преди договор, депозит или изплащане.

Версия 1.3.2 · JSON през HTTPS · OpenAPI

Как работи това

API е еднакъв за всички партньори. В пет стъпки:

  1. Ще включим API за вашата фирма; в своята администрация, в раздела API, ще създадете API ключ.
  2. Когато клиентът трябва да премине обучение, вашата система извиква POST /v1/users с вашия идентификатор на клиента.
  3. Създаваме профил без имейл и връщаме входна връзка (entryUrl); показвате я на клиента като бутон.
  4. Клиентът щраква върху нея и веднага е в курса.
  5. Състоянието проверявате по всяко време чрез 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" } }
HTTPreasonКакво да направите
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 не одобрява заема, не изтегля и не съхранява документите, не проверява самоличността и не издава сертификат за пътеводителя.

  1. Създавате профил на кандидата: POST /v1/users с вашия псевдоним.
  2. Изпращате офертата: POST /v1/users/{identifier}/loan-offers; отговорът 201 съдържа entryUrl.
  3. Предавате entryUrl на кандидата по свой проверен канал. Връзката е валидна 30 дни и може да се използва многократно; пътеводителят показва числата на неговата оферта.
  4. За края научавате чрез уебхук (loanGuide.completed, loanGuide.assistanceRequested и други).
  5. Състоянието проверявате чрез 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 по-горе. Допълнително за пътеводителя:

HTTPreasonКакво да направите
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 за своята фирма? Пишете ни

Подробности