AploDocs API

API для интеллектуального распознавания первичных бухгалтерских документов (УПД, ТОРГ-12, счета-фактуры) с использованием AI-модели Claude Vision.

Base URL: /api/v1 Формат: JSON Авторизация: API Key

Распознавание

Отправьте фото или скан документа и получите структурированные данные

Валидация

Автоматическая проверка сумм, НДС, ИНН и дат с оценкой уверенности

Экспорт

Получайте данные в формате JSON или Aplosoft для импорта в учётную систему

Diadoc Gateway

Отправляйте и получайте электронные документы через Diadoc, управляйте сотрудниками организации

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

Все запросы к API (кроме /v1/health) требуют передачи API-ключа в заголовке X-API-Key.

API-ключи создаются в панели администратора в разделе API Keys.

curl -H "X-API-Key: aplo_live_ваш_ключ" \
     https://your-domain.com/api/v1/documents

Важно: Храните API-ключ в безопасности. Не передавайте его в URL-параметрах и не публикуйте в открытых репозиториях. При компрометации ключа — деактивируйте его в панели и создайте новый.

Quick Start

Распознайте первый документ за 3 шага:

Получите API-ключ

Зайдите в панель администратора → API Keys → Create New Key

Отправьте документ на распознавание

curl -X POST /api/v1/recognize \
  -H "X-API-Key: aplo_live_ваш_ключ" \
  -F "images[]=@document.jpg" \
  -F "document_type=auto" \
  -F "image_quality=photo" \
  -F "priority=high"

Получите результат

{
  "id": "doc_aB3kF9mNx2Lq",
  "status": "completed",
  "document_type": "upd",
  "processing_time_ms": 4520,
  "confidence": 0.95,
  "warnings": [],
  "data": {
    "document": {
      "number": "123",
      "date": "15.01.2026"
    },
    "seller": {
      "name": "ООО \"Ромашка\"",
      "inn": "7701234567",
      "kpp": "770101001"
    },
    "buyer": {
      "name": "ООО \"Василёк\"",
      "inn": "7709876543",
      "kpp": "770901001"
    },
    "items": [ ... ],
    "totals": {
      "amount_without_nds": 10000.00,
      "nds_amount": 2000.00,
      "amount_with_nds": 12000.00
    }
  }
}

Ошибки

API возвращает ошибки в едином формате:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Описание ошибки"
  }
}

HTTP код	Код ошибки	Описание
`401`	`MISSING_API_KEY`	Не передан заголовок X-API-Key
`401`	`INVALID_API_KEY`	Ключ недействителен или деактивирован
`404`	`NOT_FOUND`	Документ не найден или принадлежит другому ключу
`409`	`DOCUMENT_NOT_READY`	Документ ещё не обработан (для экспорта)
`422`	`VALIDATION_ERROR`	Ошибка валидации параметров запроса
`422`	—	Распознавание не удалось (синхронный режим)

Endpoints

GET /api/v1/health

Проверка состояния сервиса. Не требует аутентификации.

Ответ

{
  "status": "ok",
  "version": "1.0.0",
  "python_worker": "connected",
  "anthropic_api": "ok",
  "database": "connected",
  "redis": "connected",
  "queue_size": 3,
  "avg_processing_time_ms": 4200
}

Возвращает 200 если все компоненты работают, 503 при деградации.

POST /api/v1/recognize

Отправить документ на распознавание. Основной endpoint API.

Параметры (multipart/form-data)

Параметр	Тип	Обязательный	Описание
`images[]`	file	Да	Изображения документа. От 1 до 5 файлов. Форматы: JPEG, PNG, WebP, TIFF, BMP. Макс. 10 МБ каждый.
`document_type`	string	Да	Тип документа: `upd`, `torg12`, `invoice` или `auto` (автоопределение)
`image_quality`	string	Да	Качество изображения: `photo` (фото с телефона), `scan` (сканер), `screenshot` (скриншот)
`output_format`	string	Нет	Формат выходных данных: `json` (по умолчанию), `aplosoft`
`priority`	string	Нет	Приоритет: `high` (синхронный ответ), `normal` (по умолчанию, асинхронный), `batch` (пакетная обработка)
`callback_url`	string	Нет	URL для webhook-уведомления о завершении обработки. Макс. 500 символов.
`client_ref`	string	Нет	Ваш внутренний идентификатор документа для связки. Макс. 255 символов.

Пример запроса

curl -X POST /api/v1/recognize \
  -H "X-API-Key: aplo_live_ваш_ключ" \
  -F "images[]=@page1.jpg" \
  -F "images[]=@page2.jpg" \
  -F "document_type=upd" \
  -F "image_quality=scan" \
  -F "priority=high" \
  -F "client_ref=order-2026-001"

Ответ — синхронный (priority=high) 200

{
  "id": "doc_aB3kF9mNx2Lq",
  "status": "completed",
  "document_type": "upd",
  "processing_time_ms": 4520,
  "data": {
    "document": { ... },
    "seller": { ... },
    "buyer": { ... },
    "items": [ ... ],
    "totals": { ... }
  },
  "confidence": 0.95,
  "warnings": []
}

Ответ — асинхронный (normal/batch) 202

{
  "id": "doc_aB3kF9mNx2Lq",
  "status": "queued",
  "poll_url": "/api/v1/documents/doc_aB3kF9mNx2Lq"
}

// Опрашивайте poll_url до получения
// status: "completed" или "failed".
// Либо укажите callback_url для
// получения webhook-уведомления.

priority=high — синхронная обработка, ответ приходит сразу (таймаут ~35 сек). Используйте для единичных документов, когда результат нужен немедленно.
priority=normal — документ ставится в очередь, ответ 202 Accepted. Получите результат через polling или webhook.
priority=batch — документы накапливаются и обрабатываются пакетами (каждые 15 мин). Оптимально для массовой загрузки.

GET /api/v1/documents

Получить список документов, привязанных к вашему API-ключу.

Query-параметры

Параметр	Тип	Описание
`status`	string	Фильтр по статусу: `queued`, `processing`, `completed`, `failed`
`type`	string	Фильтр по типу: `upd`, `torg12`, `invoice`
`from`	date	Начало периода (ISO 8601)
`to`	date	Конец периода (ISO 8601)
`limit`	integer	Количество записей (1–100, по умолчанию 20)
`offset`	integer	Смещение для пагинации (по умолчанию 0)

Пример

curl -H "X-API-Key: aplo_live_ваш_ключ" \
     "/api/v1/documents?status=completed&type=upd&limit=10"

Ответ 200

{
  "data": [
    {
      "id": "doc_aB3kF9mNx2Lq",
      "status": "completed",
      "document_type": "upd",
      "created_at": "2026-02-27T10:30:00+00:00",
      "client_ref": "order-2026-001",
      "completed_at": "2026-02-27T10:30:04+00:00",
      "data": { ... },
      "confidence": 0.95,
      "warnings": [],
      "processing_time_ms": 4520
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET /api/v1/documents/{id}

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

Пример

curl -H "X-API-Key: aplo_live_ваш_ключ" \
     /api/v1/documents/doc_aB3kF9mNx2Lq

Ответ 200

// Если обработка завершена:
{
  "id": "doc_aB3kF9mNx2Lq",
  "status": "completed",
  "document_type": "upd",
  "created_at": "2026-02-27T10:30:00+00:00",
  "client_ref": "order-2026-001",
  "completed_at": "2026-02-27T10:30:04+00:00",
  "data": { ... },
  "confidence": 0.95,
  "warnings": [],
  "processing_time_ms": 4520
}

// Если ещё в обработке:
{
  "id": "doc_aB3kF9mNx2Lq",
  "status": "processing",
  "document_type": "upd",
  "created_at": "2026-02-27T10:30:00+00:00",
  "client_ref": null
}

DELETE /api/v1/documents/{id}

Удалить документ и все связанные файлы (изображения, PDF).

curl -X DELETE -H "X-API-Key: aplo_live_ваш_ключ" \
     /api/v1/documents/doc_aB3kF9mNx2Lq

Ответ 200

{
  "deleted": true
}

GET /api/v1/documents/{id}/export

Экспортировать данные распознанного документа в нужном формате. Документ должен иметь статус completed.

Query-параметры

Параметр	Тип	Описание
`format`	string	`json` (по умолчанию) — сырые распознанные данные. `aplosoft` — формат для импорта в Aplosoft.

format=json

{
  "document": {
    "number": "123",
    "date": "15.01.2026"
  },
  "seller": {
    "name": "ООО \"Ромашка\"",
    "inn": "7701234567",
    "kpp": "770101001"
  },
  "buyer": { ... },
  "items": [ ... ],
  "totals": {
    "amount_without_nds": 10000.00,
    "nds_amount": 2000.00,
    "amount_with_nds": 12000.00
  }
}

format=aplosoft

{
  "aplosoft_version": "1.0",
  "source_service": "aplodocs",
  "document_id": "doc_aB3kF9mNx2Lq",
  "recognized_at": "2026-02-27T...",
  "document_type": "upd",
  "confidence": 0.95,
  "counterparty": {
    "inn": "7701234567",
    "kpp": "770101001",
    "name": "ООО \"Ромашка\"",
    "role": "seller"
  },
  "items": [ ... ],
  "totals": {
    "amount_with_nds": 12000.00,
    "currency": "RUB"
  },
  "raw_data": { ... }
}

Diadoc Gateway

AploDocs работает как шлюз (gateway) к сервису электронного документооборота Диадок (Контур). Через единый API вы можете отправлять и получать юридически значимые электронные документы, а также управлять сотрудниками организации.

Настройка: Для работы с Diadoc необходимо настроить OAuth-подключение через панель администратора (/admin/settings) с указанием DIADOC_CLIENT_ID, DIADOC_CLIENT_SECRET, DIADOC_BOX_ID. Авторизация выполняется через OpenID Connect (Kontur Identity).

GET /api/v1/diadoc/health

Проверка подключения к Diadoc API.

{
  "status": "connected",
  "authenticated": true,
  "organizations_count": 1,
  "box_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Документы Diadoc

GET /api/v1/diadoc/documents

Получить список документов из Diadoc с фильтрацией.

Параметр	Обяз.	Описание
`filterCategory`	Да	Категория фильтра: `Any.Inbound`, `Any.Outbound`, `Any.InboundNotFinished` и др.
`counteragentBoxId`	Нет	Фильтр по контрагенту
`fromDocumentDate`	Нет	Начало периода (dd.MM.yyyy)
`toDocumentDate`	Нет	Конец периода (dd.MM.yyyy)

curl -H "X-API-Key: aplo_live_ваш_ключ" \
     "/api/v1/diadoc/documents?filterCategory=Any.Inbound"

GET /api/v1/diadoc/documents/{messageId}/{entityId}

Получить конкретный документ по ID сообщения и ID сущности.

GET /api/v1/diadoc/documents/{messageId}/{entityId}/content

Скачать содержимое документа (бинарный файл).

POST /api/v1/diadoc/documents/send

Отправить документ через Diadoc.

curl -X POST /api/v1/diadoc/documents/send \
  -H "X-API-Key: aplo_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "ToBoxId": "контрагент-box-id",
    "DocumentAttachments": [
      {
        "TypeNamedId": { "Name": "UniversalTransferDocument", "Version": "utd820_05_01_02_hyphen" },
        "SignedContent": { "Content": "base64-content..." }
      }
    ]
  }'

POST /api/v1/diadoc/documents/search

Полнотекстовый поиск по документам.

curl -X POST /api/v1/diadoc/documents/search \
  -H "X-API-Key: aplo_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{ "query": "ООО Ромашка" }'

DELETE /api/v1/diadoc/documents/{messageId}

Удалить сообщение/документ из Diadoc.

GET /api/v1/diadoc/events

Получить ленту событий (новые/изменённые документы). Параметр afterEventId для пагинации.

Сотрудники организации (Diadoc)

GET /api/v1/diadoc/employees

Список сотрудников организации. Параметры: page, count.

GET /api/v1/diadoc/employees/me

Текущий авторизованный пользователь как сотрудник.

GET /api/v1/diadoc/employees/{userId}

Получить конкретного сотрудника по ID.

POST /api/v1/diadoc/employees

Создать нового сотрудника.

curl -X POST /api/v1/diadoc/employees \
  -H "X-API-Key: aplo_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "Credentials": {
      "Login": "user@example.com",
      "FullName": {
        "LastName": "Иванов",
        "FirstName": "Иван",
        "MiddleName": "Иванович"
      }
    },
    "Position": "Бухгалтер",
    "Permissions": {
      "IsAdministrator": false,
      "DocumentAccessLevel": "SelectedDepartments"
    }
  }'

PUT /api/v1/diadoc/employees/{userId}

Обновить данные сотрудника.

DELETE /api/v1/diadoc/employees/{userId}

Удалить сотрудника из организации.

Организации (Diadoc)

GET /api/v1/diadoc/organizations

Список организаций авторизованного пользователя.

GET /api/v1/diadoc/organizations/current

Текущая организация (по настроенному box ID).

GET /api/v1/diadoc/organizations/search?inn=7701234567

Поиск организаций по ИНН/КПП.

GET /api/v1/diadoc/counteragents

Список контрагентов организации.

Webhooks

При указании callback_url в запросе на распознавание, система отправит POST-запрос на указанный URL после завершения обработки.

Payload webhook-а

POST https://your-server.com/webhook/aplodocs
Content-Type: application/json

{
  "event": "document.completed",
  "document_id": "doc_aB3kF9mNx2Lq",
  "status": "completed",
  "document_type": "upd",
  "confidence": 0.95,
  "data": {
    "document": { ... },
    "seller": { ... },
    "buyer": { ... },
    "items": [ ... ],
    "totals": { ... }
  },
  "warnings": [],
  "completed_at": "2026-02-27T10:30:04+00:00"
}

Retry-политика:

До 3 попыток доставки
Интервалы между попытками: 5 сек, 30 сек, 2 мин
Ваш endpoint должен вернуть 2xx для подтверждения получения
Таймаут подключения: 10 секунд

Типы документов

Тип	Название	Описание
`upd`	УПД	Универсальный передаточный документ
`torg12`	ТОРГ-12	Товарная накладная
`invoice`	Счёт-фактура	Счёт-фактура на оплату
`auto`	Автоопределение	Система автоматически определит тип документа

Формат распознанных данных

Поле data в ответе содержит структурированные данные документа:

{
  "document": {
    "number": "123",             // Номер документа
    "date": "15.01.2026"         // Дата в формате DD.MM.YYYY
  },
  "seller": {
    "name": "ООО \"Ромашка\"",   // Наименование продавца
    "inn": "7701234567",          // ИНН (10 или 12 цифр)
    "kpp": "770101001",           // КПП
    "address": "г. Москва, ..."   // Адрес (если есть)
  },
  "buyer": {
    "name": "ООО \"Василёк\"",   // Наименование покупателя
    "inn": "7709876543",
    "kpp": "770901001",
    "address": "г. Москва, ..."
  },
  "items": [
    {
      "number": 1,                // Порядковый номер строки
      "name": "Товар А",         // Наименование товара/услуги
      "product_code": "ABC-001",  // Код товара (если есть)
      "unit": {
        "code": "796",            // Код единицы измерения
        "name": "шт"              // Единица измерения
      },
      "quantity": 10,             // Количество
      "price": 1000.00,           // Цена за единицу без НДС
      "amount_without_nds": 10000.00,  // Сумма без НДС
      "nds_rate": 20,             // Ставка НДС (0, 10 или 20)
      "nds_amount": 2000.00,      // Сумма НДС
      "amount_with_nds": 12000.00 // Сумма с НДС
    }
  ],
  "totals": {
    "amount_without_nds": 10000.00,  // Итого без НДС
    "nds_amount": 2000.00,           // Итого НДС
    "amount_with_nds": 12000.00      // Итого с НДС
  }
}

Валидация и уверенность

После распознавания система автоматически проверяет данные и вычисляет оценку уверенности (confidence: от 0.10 до 1.00).

Проверки

Проверка	Описание
Математика строк	`amount_without_nds + nds_amount = amount_with_nds` и `quantity * price = amount_without_nds`
Итоги	Сумма строк совпадает с указанными итогами
ИНН	Формат ИНН продавца и покупателя (10 или 12 цифр)
Даты	Формат даты документа (DD.MM.YYYY)
Ставки НДС	Стандартные ставки: 0%, 10%, 20%

Расчёт confidence

Базовое значение: 1.00
Каждое предупреждение: -0.05
Пустое критическое поле (ИНН продавца, ИНН покупателя, итого с НДС): -0.10
Несовпадение итогов: дополнительно -0.10
Минимальное значение: 0.10

Рекомендация: При confidence < 0.80 рекомендуем ручную проверку документа. Массив warnings содержит конкретные замечания с указанием проблемного поля.