Документация API АДРЕ

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

Каждый запрос к /api/v1/* должен содержать заголовок x-api-key с вашим ключом. Ключ выдаётся индивидуально - обратитесь к нам через форму записи на демо, чтобы получить доступ.

Распознавание документа

POST /api/v1/recognize принимает один документ (изображение в base64 или PDF) и возвращает структурированные поля. Параметр docType необязателен - без него тип документа определяется автоматически; если он передан и совпадает с одним из поддерживаемых типов, распознавание идёт быстрее и точнее.

Запрос

POST /api/v1/recognize
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "image": "<base64>",
  "mimeType": "image/jpeg",
  "docType": "Справка"
}

Ответ

{
  "documentType": "Справка",
  "text": "...",
  "fields": [
    { "label": "ФИО", "value": "Асанов Азамат", "confidence": 97 },
    { "label": "Дата выдачи", "value": "01.03.2026", "confidence": 92 }
  ],
  "items": [],
  "confidence": 94
}

confidence - самооценка модели (0-100) в целом по документу и отдельно по каждому полю: не гарантия точности, но полезный сигнал, что стоит перепроверить вручную. Поддерживаемые форматы файла: image/png, image/jpeg, image/webp, application/pdf, до ~4 МБ на файл.

Пакетная обработка

Если вы обрабатываете группу документов и хотите получить уведомление по её завершении - откройте пакет, передавайте полученный batchId в поле "batchId" каждого вызова /api/v1/recognize из этой группы, затем закройте пакет.

Открыть пакет

POST /api/v1/batch
x-api-key: YOUR_API_KEY

{}

→ { "batchId": "batch_abc123", "createdAt": "2026-09-08T10:00:00Z" }

Закрыть пакет

POST /api/v1/batch
x-api-key: YOUR_API_KEY

{ "batchId": "batch_abc123", "finish": true }

→ {
  "batchId": "batch_abc123",
  "documentCount": 24,
  "errorCount": 0,
  "docTypeCounts": { "Справка": 24 },
  "webhookAttempted": true,
  "webhookDelivered": true
}

Вебхук завершения пакета

Если для вашего ключа настроен адрес вебхука, при закрытии пакета на него автоматически уходит POST-запрос со сводкой. При сбое доставки - до 3 попыток с задержкой; повторный вызов закрытия уже закрытого пакета не отправляет вебхук повторно.

POST <ваш webhookUrl>
X-Tamga-Event: batch.completed
X-Tamga-Signature: sha256=<HMAC-SHA256 тела запроса>

{
  "event": "batch.completed",
  "batchId": "batch_abc123",
  "documentCount": 24,
  "errorCount": 0,
  "docTypeCounts": { "Справка": 24 },
  "createdAt": "2026-09-08T10:00:00Z",
  "closedAt": "2026-09-08T10:04:12Z",
  "deliveredAt": "2026-09-08T10:04:12Z"
}

Заголовок X-Tamga-Signature присутствует, только если для вашего ключа задан секрет подписи - сверьте его с HMAC-SHA256 от сырого тела запроса на своей стороне, чтобы убедиться, что вебхук пришёл от АДРЕ.

Коды ошибок

Ответ с ошибкой всегда содержит { "error": "текст ошибки" } и соответствующий HTTP-статус.

Ограничения

Максимальный размер файла - около 4 МБ на документ/страницу. Пропускная способность обсуждается индивидуально в зависимости от тарифа - напишите нам, если планируете большой объём.

Поддерживаемые типы документов

Свыше 20 стандартных типов (удостоверения личности, акты гражданского состояния, дипломы, договоры, банковские и бухгалтерские документы и другие - см. раздел "Поддерживаемые документы" на главной странице), а также произвольные типы, которые ваша компания может задать самостоятельно через панель управления.