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

Генерація документів з охорони праці через API. Інтегруйте DocEasyCraft у вашу платформу за кілька хвилин.

REST API
JSON
v1

Швидкий старт

1Отримайте API ключ

Зареєструйтесь на doceasycraft.com, перейдіть у Особистий кабінет → вкладка "API ключі""Створити новий ключ".

Ключ показується тільки один раз при створенні. Збережіть його у безпечному місці.

2Поповніть баланс кредитів

Кожна генерація документа коштує 10 кредитів. Поповнити баланс можна у Особистому кабінеті або на сторінці оплати.

Якщо генерація не вдалась — кредити автоматично повертаються на ваш баланс.

3Зробіть перший запит
curl — Створити документ
curl -X POST https://doceasycraft.com/api/v1/op-documents/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docName": "Інструкція з охорони праці для електрика",
    "docType": "2",
    "companyContext": "ТОВ \"Енергопром\", 50 працівників, м. Київ",
    "answers": [
      {
        "question": "Які види робіт виконуються?",
        "answer": "Монтаж та обслуговування електроустаткування до 1000В"
      }
    ]
  }'

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

Всі запити до API потребують заголовок Authorization з вашим API ключем:

Authorization: Bearer ds_prod_5b1d9f6c77bf6a7ccaead3cbcdabf27e

Формат ключа: ds_prod_ + 32 символи.

Ендпоінти

МетодШляхОпис
POST/api/v1/op-documents/createСтворити документ із шаблону без AI
POST/api/v1/op-documents/generateЗапустити AI-генерацію документа
GET/api/v1/op-documents/{id}Отримати статус і контент документа
GET/api/v1/op-documents/listСписок документів з пошуком і фільтрацією
POST
/api/v1/op-documents/generate

Запускає генерацію документа з охорони праці. Повертає відповідь одразу, генерація відбувається у фоновому режимі.

Тіло запиту (JSON)

ПолеТипОпис
docName *stringНазва документа. Наприклад: "Інструкція з ОП для зварника"
docTypestringКатегорія документа (див. таблицю нижче). Обов'язкове, якщо не вказано sourceDocId
sourceDocIdstringID шаблону з бази DocEasyCraft. Якщо вказано — використовується конкретний шаблон та його AI-конфігурація
companyContextstringІнформація про підприємство: назва, вид діяльності, кількість працівників тощо
answersarrayМасив об'єктів { question, answer } — відповіді на питання для кастомізації документа
npaopsarrayМасив назв НПАОП для врахування при генерації

* — обов'язкове поле. Також потрібно вказати або sourceDocId, або docType.

Категорії документів (docType)

docTypeКатегорія
"1"Основні документи з охорони праці
"2"Інструкції з охорони праці
"3"Положення з пожежної безпеки
"4"Посадові інструкції
"5"Документи з пожежної безпеки та цивільного захисту
"6"Інструкції з пожежної безпеки та цивільного захисту
"7"Інші довільні документи
"12"Навчання з охорони праці
"14"Стажування

Відповідь — 202 Accepted

Response
{
  "success": true,
  "documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "generating",
  "statusUrl": "/api/v1/op-documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "viewUrl": "https://doceasycraft.com/document/view/a1b2c3d4-...",
  "estimatedTime": 60
}
GET
/api/v1/op-documents/:documentId

Перевіряє статус генерації документа та повертає HTML-контент коли документ готовий.

Параметри

ПараметрРозміщенняОпис
documentIdURL pathUUID документа, отриманий з відповіді POST

Можливі відповіді

Генерація в процесіstatus: generating
{
  "success": true,
  "documentId": "a1b2c3d4-...",
  "status": "generating",
  "createdAt": "2026-03-18T10:00:00.000Z"
}
Документ готовийstatus: completed
{
  "success": true,
  "documentId": "a1b2c3d4-...",
  "status": "completed",
  "htmlContent": "<h1>Інструкція з охорони праці...</h1>...",
  "documentName": "Інструкція з ОП для електрика",
  "viewUrl": "https://doceasycraft.com/document/view/a1b2c3d4-...",
  "createdAt": "2026-03-18T10:00:00.000Z",
  "completedAt": "2026-03-18T10:01:12.000Z"
}
Помилка генераціїstatus: failed
{
  "success": true,
  "documentId": "a1b2c3d4-...",
  "status": "failed",
  "error": "Generation failed: model timeout",
  "creditsRefunded": true,
  "createdAt": "2026-03-18T10:00:00.000Z"
}
GET
/api/v1/op-documents/list

Повертає список документів користувача з можливістю фільтрації, пошуку та сортування. Доступна для зовнішніх сервісів без додаткових платежів.

Query параметри

ПараметрЗа замовч.Опис
docTypeФільтр за типом (1, 2, 3, 4, 5, 6, 7, 12, 14)
searchПошук за назвою документа (case-insensitive)
limit10Максимум результатів на сторінку
skip0Кількість результатів для пропуску
sortBycreatedAtПоле сортування: createdAt, updatedAt, name
sortOrderdescПорядок: asc, desc

Приклади запитів

curl
# Усі документи користувача
curl https://doceasycraft.com/api/v1/op-documents/list \
  -H "Authorization: Bearer YOUR_API_KEY"

# Фільтр за типом 2 (Інструкції з ОП)
curl "https://doceasycraft.com/api/v1/op-documents/list?docType=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Пошук + паджинація
curl "https://doceasycraft.com/api/v1/op-documents/list?search=зварник&limit=20&skip=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Відповідь — 200 OK

Response
{
  "success": true,
  "data": [
    {
      "documentId": "a1b2c3d4-...",
      "name": "Інструкція з ОП для зварника",
      "docType": 2,
      "status": "completed",
      "createdAt": "2026-03-18T10:00:00.000Z",
      "viewUrl": "https://doceasycraft.com/document/view/a1b2c3d4-..."
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "skip": 0,
    "count": 1,
    "hasMore": true
  }
}

Приклад інтеграції

Повний приклад на TypeScript/JavaScript — запуск генерації та polling результату:

integration-example.ts
const API_URL = "https://doceasycraft.com";
const API_KEY = "ds_prod_YOUR_KEY_HERE";

async function generateDocument() {
  // 1. Запускаємо генерацію
  const response = await fetch(`${API_URL}/api/v1/op-documents/generate`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      docName: "Інструкція з охорони праці для зварника",
      docType: "2",
      companyContext: "ТОВ \"МеталПром\", виробництво металоконструкцій, 120 працівників",
      answers: [
        {
          question: "Які види зварювання використовуються?",
          answer: "Електродугове та газове зварювання"
        },
        {
          question: "Чи проводяться роботи на висоті?",
          answer: "Так, до 10 метрів"
        }
      ]
    }),
  });

  const { documentId } = await response.json();
  console.log("Генерація запущена:", documentId);

  // 2. Polling — перевіряємо статус кожні 5 секунд
  let result;
  while (true) {
    await new Promise(resolve => setTimeout(resolve, 5000));

    const statusRes = await fetch(
      `${API_URL}/api/v1/op-documents/${documentId}`,
      { headers: { "Authorization": `Bearer ${API_KEY}` } }
    );
    result = await statusRes.json();

    if (result.status === "completed") {
      console.log("Документ готовий!");
      console.log("HTML:", result.htmlContent.substring(0, 200) + "...");
      break;
    }

    if (result.status === "failed") {
      console.error("Помилка:", result.error);
      console.log("Кредити повернуто:", result.creditsRefunded);
      break;
    }

    console.log("Очікуємо... статус:", result.status);
  }

  return result;
}

generateDocument();

Кредити та оплата

10

кредитів за документ

Auto

повернення при помилці

Лог

всіх транзакцій у кабінеті

Коди помилок

HTTP кодЗначенняЩо робити
202Генерація запущенаВикористовуйте GET для перевірки статусу
400Невалідний запитПеревірте обов'язкові поля та формат JSON
401Невалідний API ключПеревірте заголовок Authorization
402Недостатньо кредитівПоповніть баланс у особистому кабінеті
404Шаблон або документ не знайденоПеревірте sourceDocId або documentId
500Внутрішня помилка сервераСпробуйте пізніше або зверніться до підтримки

Потрібна допомога?

Якщо у вас виникли питання щодо інтеграції або ви хочете обговорити індивідуальні умови — зв'яжіться з нами: