API документация
Интегрирайте DocServant във вашите системи, за да извличате структурирани данни от документи.
Как работи DocServant API
DocServant използва подход, воден от шаблони, при извличането на данни от документи:
- Шаблоните дефинират структурата на извлечените данни
- Шаблоните се създават еднократно в DocServant Studio
- API обработва документите спрямо даден шаблон
- Цялата обработка е асинхронна
- Резултатите се доставят чрез webhooks
Шаблони
Шаблоните са основата на модела за извличане на DocServant. Всяка API заявка се позовава на ID на шаблон.
Какво дефинират шаблоните
- Полетата, които да бъдат извлечени от документите
- Типовете данни и форматите за всяко поле
- Как полетата се съпоставят с колоните на таблицата
- Правила за валидиране и преобразувания
Създаване на шаблони
Шаблоните се създават и управляват в DocServant Studio. Качете примерен документ, дефинирайте колоните си и шаблонът е готов за използване през API.
Бърз старт
Типичният работен процес за интегриране на DocServant:
Създайте шаблон в DocServant Studio
Качете примерен документ, дефинирайте колони и конфигурирайте настройките за извличане.
Генерирайте API ключ
Отидете в секцията Developers в профила си, за да създавате и управлявате API ключове.
Изпратете документи към API с ID на шаблон
Изпратете POST заявка с документите към /run, позовавайки се на вашия шаблон.
Получете структурирани резултати чрез webhook
Регистрирайте webhook, за да получавате известия за събития в реално време — изпълнения, шаблони, потребители и други.
Автентикация
Всички API заявки трябва да съдържат вашия API ключ в заглавката Authorization, използвайки схемата Bearer.
Authorization: Bearer sk_<key_id>_<secret>API ключовете следват формата sk_<uuid>_<random>. Необработеният ключ се връща само веднъж при създаването и не се съхранява — запазете го на сигурно място.
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Изпълнения
Подаване на изпълнение
/v1/runПодайте документ за извличане чрез определен шаблон.
Полета на заявката
| Поле | Тип | Описание |
|---|---|---|
template_id* | string | ID на шаблона, който да се използва за извличането |
files* | files | Файлът с документа (PDF, DOCX, PNG, JPG) |
output_mode | string | Определя как се структурират резултатите: „combined“ обединява всички документи в един списък; „single“ запазва данните на всеки документ отделно. По подразбиране се използва output_mode на шаблона. |
store_data | boolean | Дали качените файлове да се запазят след завършване на изпълнението. Задайте 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>"
}
}Извличане на статуса на изпълнение
/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 при работа с чувствителни данни, където изходните документи трябва да се изтриват автоматично след извличането. Ако бъде пропуснато, изпълнението наследява стойността от шаблона.
Екип
Извличане на данни за екипа
/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"
}
}
}Списък с членовете на екипа
/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
}
}
}Шаблон
Списък с шаблони
/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
}
}
}Създаване на шаблон
/v1/templateСъздайте нов шаблон за извличане с листове и колони, които дефинират структурата на данните за извличане.
Полета на заявката
| Поле | Тип | Описание |
|---|---|---|
name* | string | Име на шаблона за показване |
prompt_instructions | string | Общи инструкции за извличане, прилагани към всички листове |
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": []
}
]
}
}
}Статистика
/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
- Собственик на екипа регистрира webhook с HTTPS адрес на крайна точка и тип събитие.
- Когато събитието настъпи, платформата го публикува в AWS EventBridge.
- Правило в EventBridge задейства функцията за доставка, която изпраща полезния товар с POST заявка към вашата крайна точка.
- Заявката се подписва с 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-Type | application/json |
X-Webhook-Signature | sha256=<hex_signature> |
X-Webhook-Timestamp | Unix времеви печат (в секунди) на доставката |
Проверка на подписа
Винаги проверявайте подписа, преди да обработите 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
Бележки за сигурността
- Само 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');
});