DocHub API

Создаёт документ, маршрут согласования, добавляет согласующих, загружает файл. multipart/form-data (с файлом) или application/json (без).

iin_bin у согласующего — сервер сверяет его с ИИН/БИН из сертификата ЭЦП при подписании и отклоняет чужую подпись (403 IIN_BIN_MISMATCH).

← 200 {
  success, doc_id, flow_id,
  public_url: "https://doc-hub.net/p/{doc_id}",
  approver_links: [{ order_num, name, email, role, sign_token,
    sign_url: "https://doc-hub.net/p/{doc_id}?t={sign_token}" }]
}

Сохраняет подпись согласующего. Вызывается с публичной страницы /p/{docId}?t={token} — токен сам по себе и есть авторизация конкретного подписанта.

← 200 { success, approver_id, all_signed, doc_status }

Публичная отдача оригинального файла документа — используется на странице подписания и в превью.

Генерирует печатный PDF со штампом ЭЦП и QR-кодом после того, как документ подписан.

Собирает «Счёт на оплату» из структурированных данных (реквизиты поставщика подтягиваются из companies по company_id), рендерит PDF и сразу запускает согласование — тонкая обёртка над /api/approval/start.

← 200 { success, doc_id, flow_id, public_url, file_url, approver_links, total, total_words }

Собирает обычный печатный «Акт выполненных работ (оказанных услуг)» по образцу официального бланка (Форма Р-1, Приложение 50 к приказу Министра финансов РК от 20.12.2012 № 562) — это не электронный эАВР через esf.gov.kz (см. раздел «ИС ЭСФ — документы» ниже для того случая). Реквизиты исполнителя подтягиваются из companies по company_id, рендерится PDF и сразу запускается подписание обеими сторонами по персональным ссылкам — тонкая обёртка над /api/approval/start, аналогично /api/invoice/create.

← 200 { success, doc_id, flow_id, public_url, file_url, approver_links, total, total_words }

Собирает обычную бумажную/PDF «Счёт-фактуру» — бухгалтерский документ с разбивкой НДС по позициям и подписями руководителя/главного бухгалтера поставщика — это не электронная ЭСФ через esf.gov.kz (см. раздел «ИС ЭСФ — документы (электронные ЭСФ/эАВР)» ниже для того случая). Реквизиты поставщика подтягиваются из companies по company_id, рендерится PDF и запускается внутреннее согласование (например руководитель → гл. бухгалтер) — тонкая обёртка над /api/approval/start, аналогично /api/invoice/create.

← 200 { success, doc_id, flow_id, public_url, file_url, approver_links, total, total_no_vat, total_vat, total_words }

Шаг 1: получить билет на подпись.

← 200 { success, auth_ticket_xml, environment }

Шаг 2: отправить билет, подписанный через NCALayer.signXml, — открывает сессию.

← 200 { success, session_id, environment }

Текущее состояние подключения компании.

← 200 { connected, status, live_status, session_id, tin, environment }

Приём факта/статуса отправки ЭСФ или АВР от 1С. Токен (не общий DOCHUB_API_KEY — свой на компанию) сам определяет, к какой компании относится документ.

← 200 { success, id }

Получить (GET, создаёт при отсутствии) или перевыпустить (POST) токен компании для настройки 1С.

← 200 { success, token }

Список документов компании — реестр «ЭСФ и АВР» в интерфейсе.

← 200 { success, documents: [...] }

Собрать черновик ЭСФ или АВР. Суммы (без НДС / НДС / с НДС) считаются на сервере по позициям.

← 200 { success, document }  // status: "draft"

Подписать черновик. signed_xml получают на клиенте через NCALayer.signXml над XML из buildEsfSigningXML() (utils/ncalayer.js) — в подпись входят реальные позиции и суммы, не только факт существования документа.

← 200 { success, document }  // status: "draft" → "signed"

GET ?company_id= — список; GET ?id= — одно определение; POST — создать { company_id, name, doc_type?, graph }; PUT — обновить граф по { id, graph } (версия инкрементируется).

Запустить процесс на документе.

← 200 { success, instance }

Завершить шаг «задача» — { instance_id, node_id, action: "approve"|"decline", actor_id }.

Подтвердить «ознакомление» — { instance_id, node_id, actor_id }.

Путь одного документа по процессу — вся история шагов.

Список запущенных/завершённых процессов компании — экран «Мониторинг».

Активные задачи и ознакомления конкретного пользователя.

Работает без входа в DocHUB и без X-Api-Key. Токен КГД хранится только на сервере. Проверяет контрольную сумму и ищет налогоплательщика, включая компании без записи в реестре НДС. risk=1 добавляет сведения о неблагонадёжности, признаки риска и сумму задолженности из открытых данных с датой их актуальности. «Нет данных» означает отсутствие сведений, а не положительный результат проверки.

← 400 { success:false, valid:false, reason:"length"|"checksum", message }
← 200 { success:true, valid:true, code, source:"local", found:null, registry:{status:"not_configured"} }
← 200 { success:true, valid:true, code, source:"kgd", found:true, name, name_kz,
        registry:{status:"found", registration_date, taxpayer_type},
        checked_at, cached, actuality, activity:{code,name}, tax_regime, tax_regime_since,
        vat:{status:"checked"|"not_found"|"unavailable", is_payer:true|false|null},
        risk?: { unreliable_taxpayer:{status, is_unreliable, categories}, indicators:[{code,title,value,status}],
                 tax_debt:{status, source, actuality, has_debt, total_arrear, currency:"KZT"} } }
← 429 { error:"RATE_LIMITED" }

found:false — запись не найдена; found:null — результат не получен. Проверяйте registry.status и статусы отдельных источников. Ответы могут быть частичными. Кэш успешного поиска — до 5 минут, частичного — 15 секунд; checked_at сохраняет время проверки. Лимит — 30 запросов в минуту на IP.

compliance: { checked_at, checks: [{ id, title, status, found, count,
  records:[{title,date,detail}], checked_at, url, note, neutral?, truncated? }] }

Общие реестры КГД кэшируются на 10 минут. Первый расширенный запрос может занимать до 55 секунд. Пустые, ошибочные и неполные ответы не превращаются в подтверждение отсутствия рисков.

Проверка по точному ИИН: регистрация ИП и записи неблагонадёжных налогоплательщиков, где КГД указал этот ИИН руководителя. Требуется авторизация пользователя компании или настроенная серверная интеграция. ФИО для поиска не используется. Наличие ИП не является негативным признаком. Связь с компанией вводится пользователем и не подтверждает текущие полномочия.

← 200 { success:true, checked_at, company_bin, relation_status:"user_provided",
  identity:{status:"registered"|"not_found"|"unavailable",name,registration_date,deregistration_date},
  related_companies:{status:"checked"|"unavailable",companies:[{code,name,categories}],truncated}, note }
← 401 { error:"AUTH_REQUIRED" }
← 400 { error:"INVALID_BIN_IIN" }
← 429 { error:"RATE_LIMITED" }

Лимит 10 запросов на пользователя в минуту, 4 одновременно. ИИН отправляется в теле POST, результаты не кэшируются. Закрытый профиль физлица/КДП и персональное банкротство этим API не проверяются. Пустая первая страница реестра граждан не является полной проверкой.

Извлекает структурированные поля из фото/PDF счёта, акта, счёта-фактуры или договора. Документ не создаётся — только данные для подстановки в форму создания.

← 200 { success:true, extracted:{ doc_type, number, date, counterparty:{name,bin_iin,address},
        items:[{name,unit,qty,price}], total_amount, currency, confidence, notes } }

«Документ 360» — предварительный обзор ЛЮБОГО делового документа (договор, соглашение, NDA, меморандум, акт, счёт и т.п.) на юридическую И финансово-налоговую чистоту простым языком — не консультация юриста/бухгалтера (см. disclaimer в ответе). Принимает текст ИЛИ файл, не оба сразу.

← 200 { success:true, summary, risk_level:"low"|"medium"|"high",
        findings:[{severity,title,detail,clause_ref}], missing_clauses:[...],
        financial_tax:{ status:"clean"|"attention"|"critical"|"not_applicable", summary, findings:[...] },
        disclaimer }

Адресная книга компании (внешние контакты — без аккаунта в DocHub). GET ?company_id=&q= — список/поиск; POST — создать { company_id, name, email?, phone?, iin_bin?, position?, note? }; PUT — обновить по { id, ... }; DELETE ?id=.

Отдаёт файл из закрытого бакета вложений по временной подписанной ссылке Supabase (s обязан начинаться с /object/sign/) — сам внутренний адрес хранилища наружу не уходит.

Проверяет пользователя, компанию, назначение и очередь. Документ должен содержать одно вложение до 10 МиБ. Подписанту заранее задаётся ИИН/БИН сертификата. Возвращает одноразовый запрос на 120 секунд, хэш оригинала, открытый RSA-ключ и AAD.

{"doc_id":"00000000-0000-4000-8000-000000000001"}

Ответ: challenge_id, doc_id, approver_id, title, file_name, file_sha256, expires_at, public_key_pem, algorithm, aad.

Мобильный клиент шифрует JSON {p12_base64,password} алгоритмом AES-256-GCM со случайным ключом (32 байта), IV (12 байт), тегом (16 байт). AAD — строка из challenge без изменений. AES-ключ шифруется RSA-OAEP с SHA-256/MGF1-SHA-256. Все бинарные поля кодируются стандартным Base64.

{
  "challenge_id": "UUID из первого ответа",
  "encrypted_key": "Base64 RSA-OAEP ciphertext",
  "iv": "Base64 12 bytes",
  "ciphertext": "Base64 encrypted JSON",
  "tag": "Base64 16 bytes"
}

Эти значения — описание формата, не исполняемый пример. Используйте клиент приложения; не вставляйте P12 и пароль в публичную API-консоль. Лимит P12: 256 КиБ, пароль: 1024 байта UTF-8. Успех: {success, all_signed, doc_status, signature_id}.

После проверки доступа возвращает {doc_id,signatures:[]}: для каждой подписи — неизменяемый оригинал original_base64, cms, SHA-256, сведения сертификата и дата. P12 и пароль в ответе и БД отсутствуют. Оригинал + CMS пригодны для независимой проверки средствами, поддерживающими алгоритмы НУЦ РК.