From 7375da2548b326c296de6fa7634f01086097788e Mon Sep 17 00:00:00 2001 From: Aleksandr Meshchryakov Date: Mon, 5 Oct 2026 16:09:00 +0200 Subject: [PATCH] docs: verify Checko section API contracts --- docs/sources/checko-sections.md | 25 +++++++++++++++ tests/fixtures/checko_sections/denied.json | 8 +++++ .../fixtures/checko_sections/lease-types.json | 32 +++++++++++++++++++ .../checko_sections/license-empty.json | 13 ++++++++ tests/fixtures/checko_sections/license.json | 24 ++++++++++++++ .../checko_sections/messages-empty.json | 17 ++++++++++ .../checko_sections/messages-page-1.json | 29 +++++++++++++++++ .../checko_sections/messages-page-2.json | 29 +++++++++++++++++ .../fixtures/checko_sections/rate-limit.json | 8 +++++ tests/fixtures/checko_sections/renewed.json | 24 ++++++++++++++ 10 files changed, 209 insertions(+) create mode 100644 docs/sources/checko-sections.md create mode 100644 tests/fixtures/checko_sections/denied.json create mode 100644 tests/fixtures/checko_sections/lease-types.json create mode 100644 tests/fixtures/checko_sections/license-empty.json create mode 100644 tests/fixtures/checko_sections/license.json create mode 100644 tests/fixtures/checko_sections/messages-empty.json create mode 100644 tests/fixtures/checko_sections/messages-page-1.json create mode 100644 tests/fixtures/checko_sections/messages-page-2.json create mode 100644 tests/fixtures/checko_sections/rate-limit.json create mode 100644 tests/fixtures/checko_sections/renewed.json diff --git a/docs/sources/checko-sections.md b/docs/sources/checko-sections.md new file mode 100644 index 0000000..03e1a30 --- /dev/null +++ b/docs/sources/checko-sections.md @@ -0,0 +1,25 @@ +# Разделы Checko: проверенные методы API 2.5 + +Проверено 5 октября 2026 по официальным страницам [API](https://checko.ru/integration/api), [company](https://checko.ru/integration/api/company), [fedresurs](https://checko.ru/integration/api/fedresurs) и [справочнику типов](https://checko.ru/uploads/datasets/message_types.xlsx). Старые /api адреса возвращают 404. Публичная документация подтверждает все методы на всех тарифах; фактический доступ выбранного аккаунта ещё не проверен. Ключи/личный кабинет не читались, платных запросов не было. + +## Транспорт и полнота + +HTTPS GET https://api.checko.ru/v2/company или /fedresurs через существующий CheckoClient. inn и ogrn — точные канонические идентификаторы, key добавляет существующий транспорт. Лицензии: один /company запрос; data.ИНН/ОГРН обязаны совпасть, data.Лиценз должен явно присутствовать массивом. Отсутствующий раздел не означает пустой список. + +Сообщения и лизинг: /fedresurs, inn/ogrn, role=all, limit=100, page=1..N, sort=date. Envelope company.ИНН/ОГРН, data.ЗапВсего (total_records), СтрВсего (total_pages), СтрТекущ (current_page), Записи. Проверять неизменные totals, точный номер страницы, полное число результатов и конец total_pages; пропущенная/повторённая страница и конфликтующий GUID отвергаются. Для пустого результата принимается total_records=0, total_pages=0 или 1, current_page=1, records=[]. Ошибка/not-found/отказ доступа не становится verified empty. + +Документированный максимум limit=100 и 32 requests/s. Собственная защитная граница: не более 100 страниц / 10 000 сообщений на организацию/раздел; превышение вызывает отказ до публикации. Это operational limit, не обещание провайдера. Запросы последовательные, один месячный claim на org/source, пагинация внутри claim, ошибки claim не освобождают. Meta.status=error классифицируется существующим клиентом; balance и credentials не сохраняются в payload/artifact/job. + +## Поля + +Сообщения /fedresurs — ЕФРСФДЮЛ, отдельный метод от /bankruptcy-messages (ЕФРСБ). Подтверждённые поля: GUID, URL, Дата, Тип, ТипНаим, Публикатор (ОГРН/ОГРНИП), Участники (ОГРН/ИНН). Identity — org.INN + provider GUID. Payload: message_guid, publication_raw/date, message_type/code label, publisher_identifier, participant_identifiers, source_url, fetched_at, upstream (только сообщение). record_date — дата публикации, amount=null, status=published. Полный текст API не документирует. + +Лизинг — FinancialLeaseContract, ChangeFinancialLeaseContract, StopFinancialLeaseContract и версии этих трёх типов с суффиксом 2. Справочник сохранён как lease-types.json. Чтобы не платить за шесть отдельных обходов, собирать полный role=all результат и отбирать эти шесть типов после EOF. Независимый source/checko_leasing claim. Запись — событие договора с GUID; record_type=leasing_contract сохраняет согласованный machine ID. Payload содержит поля сообщения и lease_event_type. SaleOrLeaseEnterprise исключён: это не финансовый лизинг. Сумма/предмет/участники договора не выдумываются. + +Лицензии /company: Номер, Дата, ДатаНач, ДатаОконч, ЛицОрг, ВидДеят. Существующие client aliases end_date/authority/activities не совпадают с актуальными; добавить актуальные aliases, сохранив прежние. Payload: license_number, issued_on, valid_from/until, authority, activities, source_url, fetched_at, upstream (только лицензия). Identity — org.INN + номер + орган + дата выдачи, без mutable expiry/activities. Без этих компонентов reject. record_date=issued_on, amount=null, даты nullable с raw; истечение даты не доказывает прекращение лицензии. + +## Fixtures и готовность + +Fixtures синтетические, структура из официальной документации; реальные ответы аккаунта не снимались. Success/renewed/empty/denied/rate-limit/two pages доступны локально. Никаких вымышленных /leasing,/messages. Readiness: schema documented; implementation и фактическая dev-приёмка впереди. Месячные claims/полная популяция требуют отдельной проверки. Schedules disabled. + +Публичный тариф: первые 100 запросов за день бесплатны, далее Standard 0.15 RUB / Maximum 0.10 RUB за HTTP 200. Конкретный тариф/остаток аккаунта не установлен; это не разрешение расходовать квоту. Для фактической пробы подготовить canonical scope и максимальное число страниц/calls, получить отдельное разрешение. diff --git a/tests/fixtures/checko_sections/denied.json b/tests/fixtures/checko_sections/denied.json new file mode 100644 index 0000000..2ba5f2f --- /dev/null +++ b/tests/fixtures/checko_sections/denied.json @@ -0,0 +1,8 @@ +{ + "meta": { + "status": "error", + "message": "Доступ к методу запрещен", + "today_request_count": 100, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/lease-types.json b/tests/fixtures/checko_sections/lease-types.json new file mode 100644 index 0000000..9353211 --- /dev/null +++ b/tests/fixtures/checko_sections/lease-types.json @@ -0,0 +1,32 @@ +[ + { + "id": 38, + "code": "FinancialLeaseContract", + "title": "Заключение договора финансовой аренды (лизинга)" + }, + { + "id": 39, + "code": "ChangeFinancialLeaseContract", + "title": "Изменение договора финансовой аренды (лизинга)" + }, + { + "id": 40, + "code": "StopFinancialLeaseContract", + "title": "Прекращение договора финансовой аренды (лизинга)" + }, + { + "id": 106, + "code": "FinancialLeaseContract2", + "title": "Заключение договора финансовой аренды (лизинга)" + }, + { + "id": 107, + "code": "ChangeFinancialLeaseContract2", + "title": "Изменение договора финансовой аренды (лизинга)" + }, + { + "id": 108, + "code": "StopFinancialLeaseContract2", + "title": "Прекращение договора финансовой аренды (лизинга)" + } +] diff --git a/tests/fixtures/checko_sections/license-empty.json b/tests/fixtures/checko_sections/license-empty.json new file mode 100644 index 0000000..dfff78d --- /dev/null +++ b/tests/fixtures/checko_sections/license-empty.json @@ -0,0 +1,13 @@ +{ + "data": { + "ИНН": "7707083893", + "ОГРН": "1027700132195", + "НаимСокр": "АО Синтетическая организация", + "Лиценз": [] + }, + "meta": { + "status": "ok", + "today_request_count": 1, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/license.json b/tests/fixtures/checko_sections/license.json new file mode 100644 index 0000000..0015b27 --- /dev/null +++ b/tests/fixtures/checko_sections/license.json @@ -0,0 +1,24 @@ +{ + "data": { + "ИНН": "7707083893", + "ОГРН": "1027700132195", + "НаимСокр": "АО Синтетическая организация", + "Лиценз": [ + { + "Номер": "ЛИЦ-001", + "Дата": "2020-01-02", + "ДатаНач": "2020-01-03", + "ДатаОконч": null, + "ЛицОрг": "Синтетический лицензирующий орган", + "ВидДеят": [ + "Синтетический вид деятельности" + ] + } + ] + }, + "meta": { + "status": "ok", + "today_request_count": 1, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/messages-empty.json b/tests/fixtures/checko_sections/messages-empty.json new file mode 100644 index 0000000..5eb354d --- /dev/null +++ b/tests/fixtures/checko_sections/messages-empty.json @@ -0,0 +1,17 @@ +{ + "company": { + "ИНН": "7707083893", + "ОГРН": "1027700132195" + }, + "data": { + "ЗапВсего": 0, + "СтрВсего": 0, + "СтрТекущ": 1, + "Записи": [] + }, + "meta": { + "status": "ok", + "today_request_count": 1, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/messages-page-1.json b/tests/fixtures/checko_sections/messages-page-1.json new file mode 100644 index 0000000..3986b99 --- /dev/null +++ b/tests/fixtures/checko_sections/messages-page-1.json @@ -0,0 +1,29 @@ +{ + "company": { + "ИНН": "7707083893", + "ОГРН": "1027700132195" + }, + "data": { + "ЗапВсего": 2, + "СтрВсего": 2, + "СтрТекущ": 1, + "Записи": [ + { + "GUID": "00000000-0000-4000-8000-000000000001", + "URL": "https://fedresurs.ru/sfactmessages/00000000-0000-4000-8000-000000000001", + "Дата": "2026-10-01", + "Тип": "FinancialLeaseContract2", + "ТипНаим": "Синтетическое сообщение", + "Публикатор": "1027700132195", + "Участники": [ + "7707083893" + ] + } + ] + }, + "meta": { + "status": "ok", + "today_request_count": 1, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/messages-page-2.json b/tests/fixtures/checko_sections/messages-page-2.json new file mode 100644 index 0000000..160e4b9 --- /dev/null +++ b/tests/fixtures/checko_sections/messages-page-2.json @@ -0,0 +1,29 @@ +{ + "company": { + "ИНН": "7707083893", + "ОГРН": "1027700132195" + }, + "data": { + "ЗапВсего": 2, + "СтрВсего": 2, + "СтрТекущ": 2, + "Записи": [ + { + "GUID": "00000000-0000-4000-8000-000000000002", + "URL": "https://fedresurs.ru/sfactmessages/00000000-0000-4000-8000-000000000002", + "Дата": "2026-10-01", + "Тип": "Liquidation", + "ТипНаим": "Синтетическое сообщение", + "Публикатор": "1027700132195", + "Участники": [ + "7707083893" + ] + } + ] + }, + "meta": { + "status": "ok", + "today_request_count": 2, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/rate-limit.json b/tests/fixtures/checko_sections/rate-limit.json new file mode 100644 index 0000000..4f17813 --- /dev/null +++ b/tests/fixtures/checko_sections/rate-limit.json @@ -0,0 +1,8 @@ +{ + "meta": { + "status": "error", + "message": "Превышен лимит запросов", + "today_request_count": 100, + "balance": 0 + } +} diff --git a/tests/fixtures/checko_sections/renewed.json b/tests/fixtures/checko_sections/renewed.json new file mode 100644 index 0000000..1c25612 --- /dev/null +++ b/tests/fixtures/checko_sections/renewed.json @@ -0,0 +1,24 @@ +{ + "data": { + "ИНН": "7707083893", + "ОГРН": "1027700132195", + "НаимСокр": "АО Синтетическая организация", + "Лиценз": [ + { + "Номер": "ЛИЦ-001", + "Дата": "2020-01-02", + "ДатаНач": "2020-01-03", + "ДатаОконч": "2030-01-01", + "ЛицОрг": "Синтетический лицензирующий орган", + "ВидДеят": [ + "Синтетический вид деятельности" + ] + } + ] + }, + "meta": { + "status": "ok", + "today_request_count": 1, + "balance": 0 + } +}