Files
mostovik-backend/docs/sources/checko-sections.md
2026-10-05 16:45:13 +02:00

39 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Разделы 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: три адаптера, scoped snapshots, monthly claims, карточки/API/экспорт и типизированные OpenAPI variants реализованы. Фактическая приёмка выбранного аккаунта и полной dev-популяции остаётся отдельно. Schedules disabled.
Публичный тариф: первые 100 запросов за день бесплатны, далее Standard 0.15 RUB / Maximum 0.10 RUB за HTTP 200. Конкретный тариф/остаток аккаунта не установлен; это не разрешение расходовать квоту. Для фактической пробы подготовить canonical scope и максимальное число страниц/calls, получить отдельное разрешение.
## Реализованная публикация и контракт
Три источника `checko_leasing`, `checko_messages`, `checko_licenses` имеют независимые карточки `checko-leasing`, `checko-messages`, `checko-licenses`, группы `leasing`, `company_messages`, `company_licenses` и типы `leasing_contract`, `company_message`, `company_license`. Refresh/run доступны администраторам, пользовательские file URLs запрещены. Display copy сохраняет существующую нейтральную конвенцию; machine IDs и проверенный provenance в новом API/экспорте не заменяются.
Eligibility совпадает с существующими платными сборщиками: ОПК / Росатом / Роскосмос и обязательный импорт в канонический справочник. Перед запросом проверяются ИНН (10 цифр/checksum), ОГРН (13), ОКПО (8), наличие имени и однозначная организация; записи филиалов/неоднозначные или неполные реквизиты сохраняются без запроса. Это не сбор полного каталога всех юрлиц страны.
Claim берётся атомарно до первого запроса и сохраняется после ошибки. Каждый раздел обходит максимум 100 страниц / 10 000 сообщений на организацию; staging batches по 500. Ошибка пагинации удаляет staging этой организации, старые опубликованные записи сохраняются. Успешный пустой ответ удаляет прежние записи только своей организации. Нет завершённых организаций — rejected artifact и failure job, без fake snapshot.
Artifact — приватный NDJSON с нормализованными наблюдениями и upstream-полями, SHA-256/size; credentials/meta balance не сохраняются. `completeness=full|partial`; непересекающиеся категории: `organizations_updated + organizations_empty + organizations_failed + quota_skipped = organizations_total`. `organizations_preserved = organizations_failed + quota_skipped`, это пересекающийся диагностический счётчик, его не суммируют второй раз. `updated_records_count` — записи завершённого scope, `retained_records_count` — сохранённые записи, published/snapshot counts — весь текущий опубликованный набор. Partial success не двигает `latest_success_load` полного прохода; последний job/load показывает partial metadata. API и экспорт читают все текущие записи, включая сохранённые из прежних batches.
Локальная проверка 05.10.2026: adapters/старый клиент/local HTTP — 126 passed; PostgreSQL с настоящими миграциями/гонкой monthly claim и admission/export — 42 passed; generated OpenAPI/Orval/type-check и Zod round-trip — 19 фактических JSON-ответов без изменения/потери полей. Платные реальные вызовы не выполнялись. Ограниченная dev-проба и полный обход — отдельные критерии готовности.