API для розпізнавання документів

Встановіть BASE як адресу Rahunko, виберіть робочий простір і використайте Bearer-ключ із потрібним правом. Послідовність проводить один незмінний файл через завантаження, обробку, перевірку та експорт.

Як працювати з документами

011. Підготуйте завантаження

Підготуйте локально точні метадані файла, запишіть їх у intent.json і надішліть запит із правом запису. У відповіді буде upload.id для наступного кроку.

Idempotency key має від 8 до 128 символів із дозволеного набору.
Заявлений хеш є SHA-256 точних байтів файла.
Повторення того самого тіла відтворює попередню відповідь. Інше тіло дає конфлікт.

BASE="https://your-rahunko-origin.example"
WORKSPACE_ID="ws_123"
API_KEY="rk_replace_with_your_key"
BYTE_LENGTH=$(wc -c < march.pdf | tr -d ' ')
SHA256=$(shasum -a 256 march.pdf | awk '{print $1}')

cat > intent.json <<JSON
{
  "fileName": "march.pdf",
  "mediaType": "application/pdf",
  "byteLength": $BYTE_LENGTH,
  "sha256": "$SHA256",
  "sourceKind": "pdf"
}
JSON

curl -X POST "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: march-2026-upload-01" \
  -H "Content-Type: application/json" \
  --data-binary @intent.json

022. Надішліть байти та завершіть

Надішліть ті самі байти, довжину й digest яких ви вказали, а потім завершіть завантаження порожнім JSON-об’єктом. Finalize повертає 202, документ, job і початкову revision.

Content-Length має збігатися із заявленою довжиною.
Неправильні довжина, MIME, сигнатура або хеш відхиляються.
Finalize приймає порожній JSON-об’єкт {}.

UPLOAD_ID="upload_from_intent_response"

curl -X PUT "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads/$UPLOAD_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "X-Content-SHA256: $SHA256" \
  --data-binary "@march.pdf"

curl -X POST "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads/$UPLOAD_ID/finalize" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

033. Стежте за статусом та експортуйте

Стежте за job до завершення обробки, прочитайте документ і використайте поточну однакову revision для експорту. Відповідь експорту є самим файлом, тому команда зберігає його напряму.

Замініть 3 на поточну revision документа й перевірки.
Скасуйте через POST .../documents/{documentId}/cancel із {"revision":N}.
Видаліть через DELETE .../documents/{documentId} із тією самою revision.

JOB_ID="job_from_finalize_response"
DOCUMENT_ID="document_from_finalize_response"
REVISION=3

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $API_KEY"

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/documents/$DOCUMENT_ID/export?format=csv&revision=$REVISION" \
  -H "Authorization: Bearer $API_KEY" \
  -o march.csv

Помилки API повертаються як JSON зі стабільним code. Зазвичай 401 означає неправильний ключ, 403 означає відсутнє право, 409 означає конфлікт стану або revision, а 422 означає неприйняті байти.