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

Интегрирайте DocServant във вашите системи, за да извличате структурирани данни от документи.

Търсите ръководството за уеб интерфейса?Научете как да създавате шаблони, да изпълнявате извличания и да управлявате справочни данни през нашия интерфейс.
Вижте ръководството
Влезте в профила си, за да генерирате API ключове и да конфигурирате webhooks.Вход

Как работи DocServant API

DocServant използва подход, воден от шаблони, при извличането на данни от документи:

  • Шаблоните дефинират структурата на извлечените данни
  • Шаблоните се създават еднократно в DocServant Studio
  • API обработва документите спрямо даден шаблон
  • Цялата обработка е асинхронна
  • Резултатите се доставят чрез webhooks
Мислете за шаблоните като за договор между вашите документи и структурирания резултат, който получавате. Дефинирайте схемата веднъж и след това обработвайте произволен брой документи спрямо нея.

Шаблони

Шаблоните са основата на модела за извличане на DocServant. Всяка API заявка се позовава на ID на шаблон.

Какво дефинират шаблоните

  • Полетата, които да бъдат извлечени от документите
  • Типовете данни и форматите за всяко поле
  • Как полетата се съпоставят с колоните на таблицата
  • Правила за валидиране и преобразувания

Създаване на шаблони

Шаблоните се създават и управляват в DocServant Studio. Качете примерен документ, дефинирайте колоните си и шаблонът е готов за използване през API.

Шаблоните са многократно използваеми. Създайте веднъж, обработвайте неограничено количество документи. Шаблони не могат да се създават през API — за тях е необходим интерфейсът на Studio.

Бърз старт

Типичният работен процес за интегриране на DocServant:

1

Създайте шаблон в DocServant Studio

Качете примерен документ, дефинирайте колони и конфигурирайте настройките за извличане.

2

Генерирайте API ключ

Отидете в секцията Developers в профила си, за да създавате и управлявате API ключове.

3

Изпратете документи към API с ID на шаблон

Изпратете POST заявка с документите към /run, позовавайки се на вашия шаблон.

4

Получете структурирани резултати чрез webhook

Регистрирайте webhook, за да получавате известия за събития в реално време — изпълнения, шаблони, потребители и други.


Автентикация

Всички API заявки трябва да съдържат вашия API ключ в заглавката Authorization, използвайки схемата Bearer.

Authorization: Bearer sk_<key_id>_<secret>

API ключовете следват формата sk_&lt;uuid&gt;_&lt;random&gt;. Необработеният ключ се връща само веднъж при създаването и не се съхранява — запазете го на сигурно място.

Пазете API ключовете си в тайна. Никога не ги излагайте в код от страна на клиента или в публични хранилища и не ги споделяйте с неоторизирани лица. Ако ключ бъде компрометиран, отменете го незабавно от страницата Developers.

API ключове

API ключовете позволяват на външни услуги да се автентикират без потребителски сесии. Те имат обхват, могат да бъдат отменени и по избор да изтичат. Само собствениците на екипа могат да създават и управляват ключове.

Обхвати

Всеки ключ носи набор от обхвати, които ограничават до какво има достъп. Предоставяйте само това, което интеграцията изисква.

ОбхватРазрешение
read:teamЧетене на данни за екипа
read:runЧетене на изпълнения по документи
read:templateЧетене на шаблони
read:userЧетене на потребителски данни
read:statisticsЧетене на статистика за използването
write:teamПромяна на настройките на екипа
write:runСъздаване/промяна на изпълнения по документи
write:templateСъздаване/промяна на шаблони
write:userСъздаване/промяна на потребители

Крайни точки за управление на ключове

API ключовете се създават и управляват през вашия профил в DocServant Platform, а не чрез самия API ключ.


Крайни точки

Всички крайни точки са относителни спрямо адреса на API:

https://api.platform.docservant.com

Изпълнения

Подаване на изпълнение

POST/v1/run

Подайте документ за извличане чрез определен шаблон.

Полета на заявката

ПолеТипОписание
template_id*stringID на шаблона, който да се използва за извличането
files*filesФайлът с документа (PDF, DOCX, PNG, JPG)
output_modestringОпределя как се структурират резултатите: „combined“ обединява всички документи в един списък; „single“ запазва данните на всеки документ отделно. По подразбиране се използва output_mode на шаблона.
store_databooleanДали качените файлове да се запазят след завършване на изпълнението. Задайте false при работа с чувствителни данни, за да се изтриват изходните файлове автоматично. По подразбиране се използва настройката store_data на шаблона.

cURL пример

curl -X POST https://api.platform.docservant.com/v1/run \
  -H 'Authorization: Bearer <sk_your_live_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "<your-template-uuid>",
    "output_mode": "combined",
    "store_data": true,
    "files": [
      {
        "id": "abc123",
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "file_size": 102400
      }
    ]
  }'

Примерен отговор

{
  "success": true,
  "message": "Successfully generated upload URLs for 1 files",
  "data": {
    "uploads": [
      {
        "document_id": "<document-uuid>",
        "status": "pending",
        "filename": "invoice.pdf",
        "expires_in": 3600,
        "upload_url": "<presigned-s3-upload-url>",
        "upload_fields": {
          "Content-Type": "application/pdf",
          "key": "<s3-upload-key>"
        }
      }
    ],
    "run_id": "<run-uuid>"
  }
}

Извличане на статуса на изпълнение

GET/v1/run/:run_id

Проверете статуса на изпълнение и получете резултатите, когато е завършило.

cURL пример

curl https://api.platform.docservant.com/v1/run/<your-run-uuid> \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json"

Примерен отговор

{
  "success": true,
  "message": "Get Run",
  "data": {
    "run": {
      "run_id": "<run-uuid>",
      "template_id": "<template-uuid>",
      "template_name": "Invoice Extraction",
      "team_id": "<team-uuid>",
      "status": "completed",
      "output_mode": "combined",
      "store_data": true,
      "avg_time_to_process": 9569,
      "completed_at": "2026-04-28T10:41:07.097058+00:00",
      "created_at": "2026-04-28T10:40:58.000960+00:00",
      "updated_at": "2026-04-28T10:41:08.151896+00:00",
      "deleted_at": null,
      "input_tokens": "Total input tokens for this run",
      "output_tokens": "Total output tokens for this run",
      "documents": [
        {
          "document_id": "<document-uuid>",
          "name": "invoice.pdf",
          "status": "completed",
          "pages": 1,
          "bucket_key": "uploads/<team-uuid>/<template-uuid>/<run-uuid>/invoice.pdf",
          "preview_url": "https://s3.amazonaws.com/...",
          "time_to_process": 9569.3,
          "input_tokens": "Amount input tokens for this document",
          "output_tokens": "Amount output tokens for this document",
          "created_at": "2026-04-28T10:40:57.258407+00:00",
          "updated_at": "2026-04-28T10:41:06.827715+00:00",
          "extracted_data": {
            "note": "This object structure depends on your template's defined fields",
            "ExampleGroup": {
              "Field One": "value",
              "Field Two": "value"
            }
          }
        }
      ],
      "extracted_data": [
        {
          "note": "This array structure depends on your template's defined fields",
          "ExampleGroup": {
            "Field One": "value",
            "Field Two": "value"
          }
        }
      ]
    }
  }
}

При неуспешни изпълнения отговорът съдържа поле error с подробности:

{
  "run_id": "<run-uuid>",
  "status": "failed",
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Unable to extract data from document. The file may be corrupted or in an unsupported format."
  }
}

output_mode

Определя как се структурират резултатите от извличането, след като всички документи бъдат обработени. combined (по подразбиране) обединява извличанията от всички документи в един списък, достъпен като extracted_data на нивото на изпълнението. single запазва собственото extracted_data на всеки документ без обединяване на ниво изпълнение. Ако бъде пропуснато в заявката за създаване, изпълнението наследява стойността от шаблона.

store_data

Определя дали оригиналните качени файлове се пазят в хранилището след завършване на изпълнението. При true (по подразбиране) файловете се запазват и всеки документ включва подписан preview_url. При false файловете се изтриват от хранилището, след като изпълнението достигне крайно състояние, и preview_url не се връща. Използвайте store_data: false при работа с чувствителни данни, където изходните документи трябва да се изтриват автоматично след извличането. Ако бъде пропуснато, изпълнението наследява стойността от шаблона.


Екип

Извличане на данни за екипа

GET/v1/team

Получете подробности за екипа на автентикирания потребител, включително информация за плана и използваната квота.

cURL пример

curl https://api.platform.docservant.com/v1/team \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json"

Примерен отговор

{
  "success": true,
  "message": "Successfully get team",
  "data": {
    "team_id": "<team-uuid>",
    "name": "Your Team Name",
    "api_access_enabled": true,
    "preferred_model": "gpt-5.4-mini",
    "is_custom_plan": 0,
    "webhook_mask": "wh_xxx***...***xxx",
    "created_at": "2026-03-13T13:38:55.387267+00:00",
    "updated_at": "2026-04-28T10:41:07.096285+00:00",
    "deleted_at": null,
    "plan": {
      "key": "docservant_platform_standard",
      "name": "DocServant Platform - Standard",
      "type": "STANDARD",
      "token_quota": 5000000,
      "current_token_usage": 40944,
      "last_reported_token_usage": 0,
      "overage_allowed": true,
      "overage_cost_per_token": 0.00008,
      "overage_unit_size": 50000,
      "overage_cost_per_unit": 4.0,
      "price_monthly": 25,
      "recurring": false,
      "start_date": "2026-04-06T09:07:56.549326+00:00",
      "expiration_date": "2026-05-06T09:07:56.549326+00:00",
      "created_at": "2026-04-06T09:07:56.549326+00:00",
      "updated_at": "2026-04-06T09:07:56.549326+00:00"
    }
  }
}

Списък с членовете на екипа

GET/v1/user

Получете страниран списък с всички членове на екипа на автентикирания потребител.

cURL пример

curl https://api.platform.docservant.com/v1/user \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json"

Примерен отговор

{
  "success": true,
  "message": "Successfully get list of users",
  "data": {
    "items": [
      {
        "user_id": "<user-uuid>",
        "team_id": "<team-uuid>",
        "email": "owner@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "role": "owner",
        "status": "active",
        "email_verified": true,
        "last_login": "2026-04-29T14:31:05.154539+00:00",
        "created_at": "2026-03-13T13:38:56.749083+00:00",
        "updated_at": "2026-04-29T14:31:04.435744+00:00",
        "deleted_at": null
      },
      {
        "user_id": "<user-uuid>",
        "team_id": "<team-uuid>",
        "email": "member@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "role": "admin",
        "status": "pending",
        "email_verified": false,
        "last_login": "2026-03-18T08:18:05.714621+00:00",
        "created_at": "2026-03-18T08:16:56.736167+00:00",
        "updated_at": "2026-03-18T08:18:05.714639+00:00",
        "deleted_at": null
      }
    ],
    "pagination": {
      "current_page": 1,
      "all_pages": 1,
      "total_items": 2
    }
  }
}

Шаблон

Списък с шаблони

GET/v1/template

Получете страниран списък с всички шаблони за извличане на вашия екип.

cURL пример

curl https://api.platform.docservant.com/v1/template \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json"

Примерен отговор

{
  "success": true,
  "message": "Successfully get list of jobs",
  "data": {
    "items": [
      {
        "template_id": "<template-uuid>",
        "team_id": "<team-uuid>",
        "name": "Invoice Extraction",
        "output_mode": "single",
        "prompt_instructions": "Extract all relevant invoice data",
        "store_data": false,
        "total_runs": 4,
        "last_run": "2026-04-28T10:41:08.320130+00:00",
        "created_at": "2026-04-28T10:22:49.194772+00:00",
        "created_by": "<user-uuid>",
        "updated_at": "2026-04-28T13:44:48.346157+00:00",
        "updated_by": "<user-uuid>",
        "deleted_at": null,
        "sheets": [
          {
            "sheet_id": "<sheet-uuid>",
            "name": "Invoice",
            "prompt_instructions": "",
            "included_in_extraction": true,
            "single_object_extraction": false,
            "parent_sheet_id": null,
            "parent_sheet_name": null,
            "parent_sheet_column_id": null,
            "parent_sheet_column_name": null,
            "created_at": "2026-04-28T10:22:49.193908+00:00",
            "created_by": "<user-uuid>",
            "updated_at": "2026-04-28T10:22:49.193908+00:00",
            "updated_by": "<user-uuid>",
            "columns": [
              {
                "column_id": "<column-uuid>",
                "name": "Invoice Number",
                "data_type": "string",
                "enabled": true,
                "prompt_instructions": "",
                "enabled_reference_mapping": false,
                "reference_data_set_id": null,
                "return_data_set_field_id": null,
                "created_at": "2026-04-28T10:22:49.193908+00:00",
                "created_by": "<user-uuid>",
                "updated_at": "2026-04-28T10:22:49.193908+00:00",
                "updated_by": "<user-uuid>"
              }
            ],
            "children": []
          }
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "all_pages": 1,
      "total_items": 1
    }
  }
}

Създаване на шаблон

POST/v1/template

Създайте нов шаблон за извличане с листове и колони, които дефинират структурата на данните за извличане.

Полета на заявката

ПолеТипОписание
name*stringИме на шаблона за показване
prompt_instructionsstringОбщи инструкции за извличане, прилагани към всички листове
output_mode*stringРежим на изход при извличането. В повечето случаи използвайте „single“
store_data*booleanДали извлечените данни да се съхраняват на сървъра
sheets*arrayМасив от обекти за листове, дефиниращи схемата на извличане (вижте по-долу)

cURL пример

curl -X POST https://api.platform.docservant.com/v1/template \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Data Extraction Template",
    "prompt_instructions": "Extract all relevant financial information from invoices with high accuracy",
    "output_mode": "single",
    "store_data": true,
    "sheets": [
      {
        "name": "Invoice Header",
        "prompt_instructions": "Extract the main invoice header information",
        "included_in_extraction": true,
        "single_object_extraction": true,
        "columns": [
          { "name": "Invoice Number", "enabled": true, "prompt_instructions": "Extract the unique invoice number or ID" },
          { "name": "Invoice Date",   "enabled": true, "prompt_instructions": "Extract the invoice date in YYYY-MM-DD format" },
          { "name": "Total Amount",   "enabled": true, "prompt_instructions": "Extract the total amount due" }
        ],
        "children": []
      },
      {
        "name": "Line Items",
        "prompt_instructions": "Extract all individual line items from the invoice",
        "included_in_extraction": true,
        "single_object_extraction": false,
        "columns": [
          { "name": "Item Description", "enabled": true, "prompt_instructions": "Extract the description of the product or service" },
          { "name": "Quantity",         "enabled": true, "prompt_instructions": "Extract the quantity ordered" },
          { "name": "Unit Price",       "enabled": true, "prompt_instructions": "Extract the price per unit" },
          { "name": "Line Total",       "enabled": true, "prompt_instructions": "Extract or calculate the total for this line item" }
        ],
        "children": []
      }
    ]
  }'

Примерен отговор

{
  "success": true,
  "message": "Created Template",
  "data": {
    "template": {
      "template_id": "<template-uuid>",
      "team_id": "<team-uuid>",
      "name": "Invoice Data Extraction Template",
      "output_mode": "single",
      "prompt_instructions": "Extract all relevant financial information from invoices with high accuracy",
      "store_data": true,
      "total_runs": 0,
      "last_run": null,
      "created_at": "2026-04-29T15:41:45.442903+00:00",
      "created_by": "<user-uuid>",
      "updated_at": "2026-04-29T15:41:45.442903+00:00",
      "updated_by": "<user-uuid>",
      "deleted_at": null,
      "sheets": [
        {
          "sheet_id": "<sheet-uuid>",
          "name": "Invoice Header",
          "prompt_instructions": "Extract the main invoice header information",
          "included_in_extraction": true,
          "single_object_extraction": true,
          "parent_sheet_id": null,
          "parent_sheet_name": null,
          "parent_sheet_column_id": null,
          "parent_sheet_column_name": null,
          "created_at": "2026-04-29T15:41:45.441983+00:00",
          "created_by": "<user-uuid>",
          "updated_at": "2026-04-29T15:41:45.441983+00:00",
          "updated_by": "<user-uuid>",
          "columns": [
            {
              "column_id": "<column-uuid>",
              "name": "Invoice Number",
              "data_type": "string",
              "enabled": true,
              "prompt_instructions": "Extract the unique invoice number or ID",
              "enabled_reference_mapping": false,
              "reference_data_set_id": null,
              "return_data_set_field_id": null,
              "created_at": "2026-04-29T15:41:45.441983+00:00",
              "created_by": "<user-uuid>",
              "updated_at": "2026-04-29T15:41:45.441983+00:00",
              "updated_by": "<user-uuid>"
            }
          ],
          "children": []
        }
      ]
    }
  }
}

Статистика

GET/v1/statistics

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

cURL пример

curl https://api.platform.docservant.com/v1/statistics \
  -H "Authorization: Bearer <sk_your_live_api_key>" \
  -H "Content-Type: application/json"

Примерен отговор

{
  "success": true,
  "message": "Successfully fetched dashboard statistics",
  "data": {
    "templates": 10,
    "extractions": 39,
    "tokens": 40944,
    "documents": 128,
    "daily": [
      {
        "date": "2026-01-24",
        "tokens_used": 1200,
        "documents_used": 3,
        "is_active": true
      }
    ],
    "avg_processing_time_in_seconds": 21.0,
    "overage": {
      "allowed": true,
      "tokens_left": 459056,
      "overage_tokens": 0,
      "cost_per_token": 0.00008,
      "overage_unit_size": 50000,
      "overage_cost": 0.0,
      "overage_cost_per_unit": 4.0
    }
  }
}

Webhooks

Webhooks изпращат известия за събития в реално време към вашия сървър при всяка промяна — създадено изпълнение, актуализиран шаблон, премахнат потребител и т.н.

Как работят webhooks

  1. Собственик на екипа регистрира webhook с HTTPS адрес на крайна точка и тип събитие.
  2. Когато събитието настъпи, платформата го публикува в AWS EventBridge.
  3. Правило в EventBridge задейства функцията за доставка, която изпраща полезния товар с POST заявка към вашата крайна точка.
  4. Заявката се подписва с HMAC-SHA256, за да можете да проверите, че идва от DocServant.

Типове събития

СъбитиеЗадейства се, когато
create.userНов потребител бъде добавен към екипа
update.userПотребителски запис бъде променен
delete.userПотребител бъде премахнат
create.templateНов шаблон бъде създаден
update.templateШаблон бъде променен
delete.templateШаблон бъде изтрит
create.runИзпълнение по документи бъде стартирано
update.runИзпълнение бъде актуализирано
delete.runИзпълнение бъде изтрито

Формат на полезния товар

Всяка доставка е HTTP POST заявка с Content-Type: application/json.

{
  "event": "create.run",
  "team_id": "your-team-uuid",
  "data": {
    // full object data for the affected resource
  }
}

Заглавки на заявката

ЗаглавкаОписание
Content-Typeapplication/json
X-Webhook-Signaturesha256=<hex_signature>
X-Webhook-TimestampUnix времеви печат (в секунди) на доставката

Проверка на подписа

Винаги проверявайте подписа, преди да обработите webhook. Изчислете HMAC-SHA256 върху {timestamp}.{raw_body}, използвайки тайния ключ за webhook на вашия екип, където timestamp е стойността от X-Webhook-Timestamp.

// Node.js
const crypto = require("crypto");

function verifyWebhook(secret, timestamp, body, signatureHeader) {
  const message = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(message, "utf8")
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}
# Python
import hmac, hashlib

def verify_webhook(secret, timestamp, body, signature_header):
    message = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)
Използвайте сравнение с постоянно време (timingSafeEqual / compare_digest), за да предотвратите атаки чрез измерване на времето.

Поведение при доставка

  • Метод: HTTP POST, таймаут: 30 секунди
  • Без автоматични повторни опити — неуспешните доставки се записват, но не се изпращат отново
  • Всеки webhook записва последния опит за доставка в last_delivery
Направете обработчика си идемпотентен и обмислете периодични заявки към API за пропуснати събития, ако гаранциите за наличност са критични.

Бележки за сигурността

  • Само HTTPS крайни точки — нешифрован HTTP не се приема
  • Проверявайте X-Webhook-Signature при всяка доставка, преди да се доверите на полезния товар
  • Сменяйте тайния ключ, ако някога бъде разкрит
  • За да спрете доставките временно, задайте is_active: false, вместо да изтривате

Обработка на грешки

Изпълненията може да се провалят заради нечетими документи, невалидни шаблони или грешки при обработката. Клиентите трябва да обработват повторните опити, където това е уместно.

HTTP кодове на състоянието

КодЗначение
200Успех
400Невалидна заявка — Проверете тялото или параметрите на заявката
401Неоторизиран — Невалиден или липсващ API ключ
403Забранено — Ключът е неактивен, отменен, изтекъл или няма нужния обхват
404Не е намерено — Ключът, изпълнението или шаблонът не съществува
429Ограничение на заявките — Твърде много заявки, намалете темпото
500Грешка на сървъра — Възникна проблем от наша страна

Примери

Извличане на фактури в JSON

Подайте фактура за извличане и получете структурирания JSON резултат:

# Submit the invoice
curl -X POST https://api.docservant.com/v1/run \
  -H "Authorization: Bearer sk_<key_id>_<secret>" \
  -F "templateId=tpl_invoices" \
  -F "file=@invoice.pdf"

# Response: { "run_id": "run_abc123", "status": "queued" }

# Poll for completion (or use webhooks)
curl https://api.docservant.com/v1/run/run_abc123 \
  -H "Authorization: Bearer sk_<key_id>_<secret>"

# When status is "completed", fetch the JSON output
curl "https://storage.docservant.com/outputs/run_abc123.json?token=..."

Масово качване

Когато подадете няколко документа с един и същ шаблон, всяко изпълнение създава свои собствени изходни файлове. За да консолидирате резултатите, изтеглете отделните JSON резултати и ги обединете в приложението си или изтеглете всеки XLSX и обединете листовете програмно.

# Submit multiple documents
for file in invoices/*.pdf; do
  curl -X POST https://api.docservant.com/v1/run \
    -H "Authorization: Bearer sk_<key_id>_<secret>" \
    -F "templateId=tpl_invoices" \
    -F "file=@$file"
done

Обработка на webhook доставка (Node.js)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' })); // raw body needed for signature

app.post('/webhooks/docservant', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const rawBody = req.body.toString('utf8');

  // Verify signature
  const message = `${timestamp}.${rawBody}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(message, 'utf8')
    .digest('hex');
  const received = signature.replace('sha256=', '');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.status(401).send('Invalid signature');
  }

  const { event, team_id, data } = JSON.parse(rawBody);

  if (event === 'create.run') {
    console.log(`New run started for team ${team_id}`, data);
  }

  res.status(200).send('OK');
});