API документація JDOC

Зміст

Базові правила

У Postman не задавайте вручну Content-Type для multipart: Postman сам поставить boundary.

1. Завантажити один документ

curl --location 'https://jdoc.net.ua/api/v1/operations' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: upload-one-001' \
  --form 'files[]=@document.pdf'

Поля form-data

2. Завантажити кілька документів

Можна передати до 100 файлів за один запит. Усі файли передаються з однаковим ключем files[].

curl --location 'https://jdoc.net.ua/api/v1/operations' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: upload-batch-001' \
  --form 'files[]=@invoice.pdf' \
  --form 'files[]=@act.pdf' \
  --form 'files[]=@scan.png'

3. Завантажити з webhook для конкретної операції

curl --location 'https://jdoc.net.ua/api/v1/operations' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: upload-webhook-001' \
  --form 'files[]=@document.pdf' \
  --form 'webhook_url=https://example.com/jdoc/webhook'

4. Відповідь на створення операції

{
  "operation_id": "op_xxx",
  "status": "ACCEPTED",
  "files_total": 1,
  "documents": [
    {
      "document_id": "doc_xxx",
      "filename": "document.pdf",
      "status": "QUEUED"
    }
  ],
  "webhook_enabled": false,
  "created_at": "2026-05-10T10:00:00+00:00"
}

5. Отримати операцію і JSON-результат

curl --location 'https://jdoc.net.ua/api/v1/operations/op_xxx' \
  --header 'Authorization: Bearer <API_KEY>'

Коли статус PROCESSED або PROCESSED_WITH_WARNINGS, результат буде в documents[].result.

6. Отримати результати операції окремо

curl --location 'https://jdoc.net.ua/api/v1/operations/op_xxx/results' \
  --header 'Authorization: Bearer <API_KEY>'

7. Отримати результат конкретного документа

curl --location 'https://jdoc.net.ua/api/v1/documents/doc_xxx/result' \
  --header 'Authorization: Bearer <API_KEY>'

8. Отримати список доступних artifacts і final JSON

curl --location 'https://jdoc.net.ua/api/v1/documents/doc_xxx/artifacts' \
  --header 'Authorization: Bearer <API_KEY>'

curl --location 'https://jdoc.net.ua/api/v1/documents/doc_xxx/artifacts/final_json/signed-url' \
  --header 'Authorization: Bearer <API_KEY>'

9. Webhook: налаштування і формат доставки

Webhook потрібен, якщо ваша система має автоматично отримувати повідомлення після завершення обробки. Його можна налаштувати в кабінеті у розділі Webhook.

Поля webhook у кабінеті

Що приходить на webhook

JDOC надсилає HTTP POST з Content-Type: application/json. Є два типи подій: по операції та по документу.

Заголовки webhook-запиту

Підпис webhook

Підпис потрібен для перевірки справжності запиту. Алгоритм:

signed_payload = X-DocParser-Timestamp + "." + raw_body
expected = "sha256=" + HMAC_SHA256(secret, signed_payload)

Порівняйте expected з X-DocParser-Signature. Також перевіряйте, що timestamp не старіший за кілька хвилин.

Payload події операції

{
  "event_type": "operation.completed",
  "event": "operation.completed",
  "event_id": "evt_xxx",
  "operation_id": "op_xxx",
  "status": "PROCESSED",
  "summary": {
    "files_total": 1,
    "processed": 1,
    "processed_with_warnings": 0,
    "rejected": 0,
    "failed": 0,
    "cancelled": 0
  },
  "created_at": "2026-05-10T10:00:00+00:00",
  "completed_at": "2026-05-10T10:01:00+00:00",
  "documents": [
    {
      "document_id": "doc_xxx",
      "filename": "document.pdf",
      "status": "PROCESSED",
      "pages_count": 2,
      "document_type_code": "act",
      "structure_type_code": "structured",
      "billing": {
        "billable": true,
        "documents_charged": 1
      },
      "created_at": "2026-05-10T10:00:00+00:00",
      "completed_at": "2026-05-10T10:01:00+00:00"
    }
  ]
}

Payload події документа

{
  "event_type": "document.processed",
  "event": "document.processed",
  "event_id": "evt_xxx",
  "operation_id": "op_xxx",
  "document_id": "doc_xxx",
  "status": "PROCESSED",
  "document": {
    "document_id": "doc_xxx",
    "filename": "document.pdf",
    "status": "PROCESSED",
    "pages_count": 2,
    "billing": {
      "billable": true,
      "documents_charged": 1
    }
  },
  "created_at": "2026-05-10T10:00:00+00:00",
  "completed_at": "2026-05-10T10:01:00+00:00"
}

Webhook-повідомлення є сигналом, що результат готовий. Повний JSON результату забирайте через GET /api/v1/operations/{operation_id} або GET /api/v1/documents/{document_id}/result.

Перевірити webhook status

curl --location 'https://jdoc.net.ua/api/v1/operations/op_xxx/webhook' \
  --header 'Authorization: Bearer <API_KEY>'

Формат відповіді операції

Формат result

Статуси операції

Статуси документа

Статуси webhook-доставки

Формат помилки

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "Operation not found."
  }
}

Питання по інтеграції можна надсилати на support@jdoc.net.ua.