// документация v1

Парсек API

REST API для извлечения структурированных данных из счетов, УПД, актов, ТОРГ-12 и кассовых чеков. Запросы и ответы в JSON, файлы — multipart/form-data или бинарным телом.

https://api.parsek.example/v1

Форматы	PDF, JPG, PNG, HEIC, TIFF, WEBP
Размер файла	до 20 МБ, до 50 страниц
Кодировка	UTF-8, даты в ISO 8601, суммы — числа в рублях с копейками
OpenAPI	openapi.yaml — импортируйте в Postman или сгенерируйте клиент
Мок-сервер	`node mock-server/server.js` — локальная копия API на порту 4545

Аутентификация

Передавайте секретный ключ в заголовке Authorization. Ключи создаются в консоли.

Authorization: Bearer psk_live_9f3c2a1b7e4d6c8a0b5e

Префикс	Среда
psk_test_	Тестовая. Страницы не списываются, возвращается эталонный ответ для типа документа. Лимит 10 запросов в секунду.
psk_live_	Боевая. Реальное распознавание и тарификация по страницам.

Секретный ключ нельзя использовать в браузере или мобильном приложении. Отправляйте файлы через свой сервер или создавайте ограниченные ключи со scope documents:write и IP-allowlist.

Быстрый старт

Создайте тестовый ключ в консоли.
Отправьте документ с параметром wait=true, чтобы получить результат в том же ответе.
Проверьте validation.passed и сохраните data в учётную систему.

Загрузить документ

POST/v1/documents

Создаёт задачу распознавания. По умолчанию асинхронно: ответ 202 Accepted со статусом processing, результат приходит вебхуком. С wait=true сервер ждёт результата до 30 секунд и отвечает 200 OK.

Параметры запроса

Параметр	Описание
file · обязательно*binary	Файл документа в `multipart/form-data`. Альтернатива — бинарное тело с заголовками `Content-Type` и `X-Filename`.
urlstring	HTTPS-ссылка на файл вместо загрузки. *Нужен `file` или `url`.
typeenum	`auto` (по умолчанию), `invoice`, `upd`, `vat_invoice`, `act`, `torg12`, `receipt`, `company_card`
waitboolean, query	Синхронный режим. По умолчанию `false`.
options[validate]boolean	Проверки реквизитов и арифметики. По умолчанию `true`.
options[return_boxes]boolean	Координаты полей на странице (нормализованные 0..1).
options[egrul_check]boolean	Проверка контрагента в ЕГРЮЛ/ЕГРИП. Тариф «Бизнес» и выше.
options[fns_check]boolean	Проверка кассового чека в ФНС. Тариф «Бизнес» и выше.
metadataobject	До 20 пар ключ-значение, возвращаются в ответе и вебхуке. Например, ID документа в вашей системе.

Пример ответа `200 OK`

Получить документ

GET/v1/documents/{id}

Возвращает объект Document. Пока идёт обработка — status: "processing". Рекомендуем вебхуки вместо опроса; если опрашиваете, делайте это не чаще раза в секунду.

Список документов

GET/v1/documents?limit=20&starting_after=doc_…&status=processed&type=invoice

Курсорная пагинация, сортировка от новых к старым. Ответ: { "object": "list", "data": [...], "has_more": true }.

Удалить документ

DELETE/v1/documents/{id}

Немедленно удаляет файл и результат распознавания. Возвращает { "id": "doc_…", "deleted": true }. Автоматическое удаление настраивается в консоли: файлы — от 0 часов, результаты — до 30 дней.

Объект Document

Поле	Описание
idstring	Идентификатор `doc_…`
statusenum	`processing`, `processed`, `failed`
typeenum	Определённый тип документа, `type_confidence` — уверенность 0..1
pagesinteger	Число тарифицируемых страниц
dataobject	Извлечённые поля по схеме типа
confidenceobject	Уверенность по ключевым полям. Рекомендуемый порог ручной проверки — 0,9
validationobject	`passed`, `warnings`, массив `checks` со статусами `passed` / `warning` / `failed` / `skipped`
errorobject \| null	При `failed`: `code` и `message`
livemodeboolean	`false` для тестовых ключей

Схемы данных

invoice — счёт на оплату

number, date	Номер и дата счёта (ISO 8601)
supplier	`name`, `inn`, `kpp`, `address`, `bank { name, bik, account, corr_account }`
buyer	`name`, `inn`, `kpp`
items[]	`name`, `quantity`, `unit`, `price`, `amount`, `vat_rate`
total, vat_rate, vat_amount, amount_due	Итоги. `vat_rate`: `22%`, `10%`, `0%`, `none`
payment_purpose	Готовое назначение платежа для платёжного поручения

upd — УПД

status	`1` — счёт-фактура и передаточный документ, `2` — только передаточный документ
seller, buyer	Реквизиты сторон, `kpp` может быть `null` для ИП
items[]	`name`, `code` (ОКЕИ), `unit`, `quantity`, `price`, `amount_without_vat`, `vat_rate`, `vat_amount`, `amount`
total_without_vat, vat_amount, total	Итоги
basis, shipped_at	Основание передачи и дата отгрузки

receipt — кассовый чек

seller	`name`, `inn`, `address`
datetime, operation, tax_system	Дата и время с часовым поясом, признак расчёта, система налогообложения
items[], total, payment	Позиции, итог, `payment { cash, card }`
fiscal, qr	`fn`, `fd`, `fp` и строка QR-кода для проверки в ФНС

Вебхуки

Добавьте HTTPS-адрес в консоли. События: document.processed, document.failed, usage.threshold (80% и 100% лимита).

Проверка подписи

Заголовок Parsek-Signature: t=1757849525,v1=5d2c…. Подпись — HMAC-SHA256 от строки {t}.{тело запроса} с секретом эндпоинта. Отклоняйте события старше 5 минут.

import crypto from 'node:crypto';

export function verifyParsek(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Повторные попытки при ответе не 2xx: через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 24 ч. Отвечайте 200 в течение 10 секунд, тяжёлую обработку выполняйте в фоне. Событие может прийти повторно — используйте event.id для дедупликации.

Идемпотентность

Передайте заголовок Idempotency-Key (до 255 символов) в POST /v1/documents. Повтор с тем же ключом в течение 24 часов вернёт исходный ответ без повторной тарификации. Повтор с тем же ключом, но другим телом — 409 idempotency_conflict.

Ошибки

HTTP	code	Что делать
400	invalid_request	Проверьте параметры, подробности в `error.param`
401	unauthorized	Неверный или отозванный ключ
402	quota_exceeded	Закончились страницы на бесплатном тарифе
403	forbidden	Нет scope или IP не в allowlist
404	not_found	Документ не найден или удалён
409	idempotency_conflict	Ключ идемпотентности использован с другим телом
413	file_too_large	Файл больше 20 МБ или больше 50 страниц
415	unsupported_media_type	Формат файла не поддерживается
422	unprocessable_document	Документ не распознан (пустая страница, не финансовый документ). Не тарифицируется
429	rate_limited	Повторите после `Retry-After` секунд
5xx	server_error	Повторите с экспоненциальной задержкой и тем же `Idempotency-Key`

Лимиты

Тариф	Запросов в секунду	Параллельных задач
Тестовые ключи	10	5
Бесплатный / Старт	5	10
Бизнес	30	50
Корпоративный	по договору	по договору

Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset и X-Request-Id — указывайте его при обращении в поддержку.

Использование

GET/v1/usage?period=2026-09

Страницы и запросы за месяц: { "period": "2026-09", "pages": 2841, "included": 10000, "overage_pages": 0, "requests": 3310 }. Требуется scope usage:read.

Версии и изменения

Мажорная версия в URL (/v1). Обратно совместимые изменения — новые поля и типы документов — выпускаются без смены версии: не полагайтесь на фиксированный набор полей. Об удалении полей сообщаем за 6 месяцев.

2026-09-01	Ставка НДС 22% во всех схемах, поле `payment_purpose` в счёте
2026-07-15	Тип `company_card`, опция `egrul_check`
2026-05-20	Бета `bank_statement`, вебхук `usage.threshold`
2026-03-02	Проверка QR-кода кассового чека, ускорение p95 на 35%

Парсек API

Аутентификация

Быстрый старт

Загрузить документ

Параметры запроса

Пример ответа 200 OK

Получить документ

Список документов

Удалить документ

Объект Document

Схемы данных

invoice — счёт на оплату

upd — УПД

receipt — кассовый чек

Вебхуки

Проверка подписи

Идемпотентность

Ошибки

Лимиты

Использование

Версии и изменения

Пример ответа `200 OK`