Иштеп чыгуучулар

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

Документтерди классификациялоо, түзүмдүү маалымат чыгаруу жана аяктоо вебхугу менен топтомдук иштетүү үчүн ачык REST API.

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

/api/v1/* багытына ар бир суроо-талап x-api-key аталышындагы башчыны (header) сиздин ачкычыңыз менен камтышы керек. Ачкычтар өзүнчө берилет - жеткиликтүүлүк алуу үчүн демого жазылуу формасын колдонуңуз.

Документти таануу

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 МБга чейин.

Топтомдук иштетүү

Документтердин тобун иштетип, аяктаганда билдирүү алгыңыз келсе - топтомду ачыңыз, ошол топтомдогу ар бир /api/v1/recognize чакырыгынын "batchId" талаасына алынган batchId-ди бериңиз, андан кийин топтомду жабыңыз.

Топтомду ачуу

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 башчысы ачкычыңыз үчүн кол коюу сыры (secret) жөндөлгөн учурда гана болот - вебхук чын эле АДРЕден келгенин ырастоо үчүн, аны өз тарабыңызда сурамдын чийки денесинин HMAC-SHA256 маанисине салыштырыңыз.

Ката коддору

Каталуу жооп ар дайым { "error": "билдирүү" } жана тиешелүү HTTP-статусту камтыйт.

401Туура эмес же жок x-api-key

400Туура эмес сурам дениси - мисалы, mimeType көрсөтүлгөн эмес же колдоого алынбайт

413Файл өлчөм чегинен ашкан (~4 МБ)

404Бул batchId менен топтом табылган жок

403Бул топтом башка x-api-key менен түзүлгөн

500Сервердин ички катасы - бир аздан кийин кайра аракет кылыңыз

Чектөөлөр

Максималдуу файл өлчөмү - документ/бет башына болжол менен 4 МБ. Өткөрүү жөндөмдүүлүгү тарифиңизге жараша өзүнчө талкууланат - чоң көлөмдү пландасаңыз, биз менен байланышыңыз.

Колдоого алынган документ түрлөрү

20дан ашык стандарттуу документ түрү (жеке документтер, жарандык абал актылары, дипломдор, келишимдер, банктык жана бухгалтердик документтер жана башкалар - башкы беттеги "Колдоого алынган документтер" бөлүмүн караңыз), ошондой эле компанияңыз башкаруу панели аркылуу өзү аныктай турган өз түрлөрү.