API документація
Генерація документів з охорони праці через API. Інтегруйте DocEasyCraft у вашу платформу за кілька хвилин.
Швидкий старт
Зареєструйтесь на doceasycraft.com, перейдіть у Особистий кабінет → вкладка "API ключі" → "Створити новий ключ".
Ключ показується тільки один раз при створенні. Збережіть його у безпечному місці.
Кожна генерація документа коштує 10 кредитів. Поповнити баланс можна у Особистому кабінеті або на сторінці оплати.
Якщо генерація не вдалась — кредити автоматично повертаються на ваш баланс.
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 | Список документів з пошуком і фільтрацією |
/api/v1/op-documents/generateЗапускає генерацію документа з охорони праці. Повертає відповідь одразу, генерація відбувається у фоновому режимі.
Тіло запиту (JSON)
| Поле | Тип | Опис |
|---|---|---|
| docName * | string | Назва документа. Наприклад: "Інструкція з ОП для зварника" |
| docType | string | Категорія документа (див. таблицю нижче). Обов'язкове, якщо не вказано sourceDocId |
| sourceDocId | string | ID шаблону з бази DocEasyCraft. Якщо вказано — використовується конкретний шаблон та його AI-конфігурація |
| companyContext | string | Інформація про підприємство: назва, вид діяльності, кількість працівників тощо |
| answers | array | Масив об'єктів { question, answer } — відповіді на питання для кастомізації документа |
| npaops | array | Масив назв НПАОП для врахування при генерації |
* — обов'язкове поле. Також потрібно вказати або sourceDocId, або docType.
Категорії документів (docType)
| docType | Категорія |
|---|---|
| "1" | Основні документи з охорони праці |
| "2" | Інструкції з охорони праці |
| "3" | Положення з пожежної безпеки |
| "4" | Посадові інструкції |
| "5" | Документи з пожежної безпеки та цивільного захисту |
| "6" | Інструкції з пожежної безпеки та цивільного захисту |
| "7" | Інші довільні документи |
| "12" | Навчання з охорони праці |
| "14" | Стажування |
Відповідь — 202 Accepted
{
"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
}/api/v1/op-documents/:documentIdПеревіряє статус генерації документа та повертає HTML-контент коли документ готовий.
Параметри
| Параметр | Розміщення | Опис |
|---|---|---|
| documentId | URL path | UUID документа, отриманий з відповіді POST |
Можливі відповіді
{
"success": true,
"documentId": "a1b2c3d4-...",
"status": "generating",
"createdAt": "2026-03-18T10:00:00.000Z"
}{
"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"
}{
"success": true,
"documentId": "a1b2c3d4-...",
"status": "failed",
"error": "Generation failed: model timeout",
"creditsRefunded": true,
"createdAt": "2026-03-18T10:00:00.000Z"
}/api/v1/op-documents/listПовертає список документів користувача з можливістю фільтрації, пошуку та сортування. Доступна для зовнішніх сервісів без додаткових платежів.
Query параметри
| Параметр | За замовч. | Опис |
|---|---|---|
| docType | — | Фільтр за типом (1, 2, 3, 4, 5, 6, 7, 12, 14) |
| search | — | Пошук за назвою документа (case-insensitive) |
| limit | 10 | Максимум результатів на сторінку |
| skip | 0 | Кількість результатів для пропуску |
| sortBy | createdAt | Поле сортування: createdAt, updatedAt, name |
| sortOrder | desc | Порядок: asc, desc |
Приклади запитів
# Усі документи користувача
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
{
"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 результату:
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 | Внутрішня помилка сервера | Спробуйте пізніше або зверніться до підтримки |
Потрібна допомога?
Якщо у вас виникли питання щодо інтеграції або ви хочете обговорити індивідуальні умови — зв'яжіться з нами:
- Telegram: @op_digital_bot
- Телефон: +380 63 640 29 39