API Documentation - Платформа Lacran

🌐 Базова інформація

Base URL: https://c1.lacran.com/api

Content-Type: application/json

Encoding: UTF-8

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

API використовує Bearer Token аутентифікацію. Додайте токен в заголовок запиту:

Authorization: Bearer YOUR_TOKEN_HERE

🔐 Аутентифікація

POST /api/auth/login

Вхід користувача в систему

Request Body:

{
  "username": "string",  // required
  "password": "string"   // required
}

Success Response (200):

{
  "success": true,
  "token": "abc123def456...",
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "status": 10,
    "org_id": 5
  }
}

Error Response (401):

{
  "success": false,
  "message": "Invalid username or password"
}

cURL Example:

curl -X POST https://c1.lacran.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"john_doe","password":"secret123"}'

POST /api/auth/logout

Вихід користувача з системи (інвалідація токену)

Headers:

Authorization: Bearer YOUR_TOKEN

Success Response (200):

{
  "success": true,
  "message": "Logged out successfully"
}

cURL Example:

curl -X POST https://c1.lacran.com/api/auth/logout \
  -H "Authorization: Bearer abc123def456..."

GET /api/auth/me

Отримання інформації про поточного користувача

Headers:

Authorization: Bearer YOUR_TOKEN

Success Response (200):

{
  "success": true,
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "status": 10,
    "org_id": 5,
    "organization": {
      "id": 5,
      "name": "ТОВ Приклад",
      "edrpou": "12345678"
    }
  }
}

Error Response (401):

{
  "name": "Unauthorized",
  "message": "Unauthorized",
  "code": 0,
  "status": 401
}

cURL Example:

curl -X GET https://c1.lacran.com/api/auth/me \
  -H "Authorization: Bearer abc123def456..."

📄 Документи продажу (DocSell)

POST /api/doc-sell/upload

Завантаження одного або кількох документів продажу

Headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request Body:

{
  "documents": [
    {
      "UUID": "550e8400-e29b-41d4-a716-446655440000",
      "Number": "ПН-001",
      "Date": "15.01.2026 10:30:00",
      "OrgEDRPOU": "12345678",
      "ClientEDRPOU": "87654321",
      "TotalAmount": 15000.50,
   "Items": [
        {
            "external_id": "787383", // External identifier of the item
            "name": "Грудинка Пряна к/в в/с ПОРЦ ", // Name of the item
            "quantity": 2.273, // Quantity of the item
            "uom": "кг", // Unit of measurement
            "price_unit": 500.34, // Price per unit
            "barcode": "2201792100000", // Barcode of the item
            "uktzed": "" // UKTZED code (optional)
        },
        {
            "external_id": "787384", // External identifier of the item
            "name": "Грудинка Пряна к/в в/с ПОРЦ 2", // Name of the item
            "quantity": 2.273, // Quantity of the item
            "uom": "кг", // Unit of measurement
            "price_unit": 500.34, // Price per unit
            "barcode": "2201792100010", // Barcode of the item
            "uktzed": "" // UKTZED code (optional)
        }
    ],
      "Services": [
        {
          "Name": "Доставка",
          "Amount": 500
        }
      ]
    }
  ]
}

Success Response (201):

{
  "success": true,
  "saved": 1,
  "total": 1,
  "created": [
    {
      "UUID": "550e8400-e29b-41d4-a716-446655440000",
      "number": "ПН-001",
      "date": "2026-01-15 10:30:00"
    }
  ],
  "errors": []
}

Error Response (400):

{
  "success": false,
  "saved": 0,
  "total": 1,
  "created": [],
  "errors": [
    {
      "index": 0,
      "message": "Організацію з ЄДРПОУ 12345678 не знайдено",
      "document": {...}
    }
  ]
}

cURL Example:

curl -X POST https://c1.lacran.com/api/doc-sell/upload \
  -H "Authorization: Bearer abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "UUID": "550e8400-e29b-41d4-a716-446655440000",
      "Number": "ПН-001",
      "Date": "15.01.2026 10:30:00",
      "OrgEDRPOU": "12345678",
      "ClientEDRPOU": "87654321",
      "TotalAmount": 15000.50,
      "Items": [{"Name": "Товар 1", "Quantity": 10, "Price": 1000, "Amount": 10000}],
      "Services": []
    }]
  }'

GET /api/doc-sell/list

Отримання списку документів продажу з пагінацією та фільтрами

Headers:

Authorization: Bearer YOUR_TOKEN

Query Parameters:

Параметр	Тип	Опис
`page`	integer	Номер сторінки (за замовчуванням: 1)
`per-page`	integer	Кількість записів на сторінці (за замовчуванням: 20)
`number`	string	Пошук за номером документа
`date_from`	date	Дата початку періоду (YYYY-MM-DD)
`date_to`	date	Дата кінця періоду (YYYY-MM-DD)

Success Response (200):

{
  "success": true,
  "data": [
    {
      "UUID": "550e8400-e29b-41d4-a716-446655440000",
      "number": "ПН-001",
      "date": "2026-01-15 10:30:00",
      "org": {
        "id": 1,
        "name": "ТОВ Постачальник",
        "edrpou": "12345678"
      },
      "bayer": {
        "id": 2,
        "name": "ТОВ Клієнт",
        "edrpou": "87654321"
      },
      "total_amount": "15000.50"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

cURL Example:

curl -X GET "https://c1.lacran.com/api/doc-sell/list?page=1&per-page=20&date_from=2026-01-01" \
  -H "Authorization: Bearer abc123..."

GET /api/doc-sell/view

Отримання детальної інформації про документ продажу

Headers:

Authorization: Bearer YOUR_TOKEN

Query Parameters:

Параметр	Тип	Обов'язковий	Опис
`uuid`	string	Так	UUID документа

Success Response (200):

{
  "success": true,
  "data": {
    "UUID": "550e8400-e29b-41d4-a716-446655440000",
    "number": "ПН-001",
    "date": "2026-01-15 10:30:00",
    "org": {
      "id": 1,
      "name": "ТОВ Постачальник",
      "edrpou": "12345678"
    },
    "bayer": {
      "id": 2,
      "name": "ТОВ Клієнт",
      "edrpou": "87654321"
    },
    "total_amount": "15000.50",
    "items": [
      {
        "Name": "Товар 1",
        "Quantity": 10,
        "Price": 1000,
        "Amount": 10000
      }
    ],
    "services": [
      {
        "Name": "Доставка",
        "Amount": 500
      }
    ]
  }
}

Error Response (404):

{
  "success": false,
  "message": "Document not found"
}

cURL Example:

curl -X GET "https://c1.lacran.com/api/doc-sell/view?uuid=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer abc123..."

📦 Products API - Завантаження каталогу

API для завантаження каталогу товарів в систему AI-EDO Matcher Pro через чергу завдань.

ℹ️ Процес обробки:

Завантаження JSON масиву товарів через API
Валідація даних та створення завдання в черзі
Індексація в AI системі
Збереження векторів для швидкого пошуку
Оновлення статусу завдання (completed/failed)

POST /products/api-upload

Завантаження каталогу товарів для індексації в AI системі

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
Cookie: _identity=your-session-cookie  // альтернатива Bearer

Request Body:

{
  "products": [
    {
      "id": "PROD-001",          // required - ваш ID товару
      "name": "Молоко 2.5% 1л",  // required - назва для AI matching
      "barcode": "4820012345678", // optional - штрих-код
      "price": 35.50              // optional - ціна
    },
    {
      "id": "PROD-002",
      "name": "Хліб білий нарізний",
      "barcode": "4820098765432",
      "price": 25.00
    }
  ],
  "priority": 1  // optional (1-10), default: 1
}

Success Response (200):

{
  "success": true,
  "task_id": 123,
  "products_count": 2,
  "skipped_count": 0,
  "message": "Catalog indexing task created successfully",
  "errors": []
}

Error Response (400):

{
  "success": false,
  "error": "Missing or invalid \"products\" array in request",
  "code": 400
}

Error Response (401):

{
  "success": false,
  "error": "Authentication required",
  "code": 401
}

Error Response (403):

{
  "success": false,
  "error": "User is not assigned to an organization",
  "code": 403
}

cURL Example:

curl -X POST https://c1.lacran.com/products/api-upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "products": [
      {
        "id": "1",
        "name": "Молоко 2.5% 1л",
        "barcode": "4820012345678",
        "price": 35.50
      }
    ],
    "priority": 1
  }'

PHP Example:

$ch = curl_init('https://c1.lacran.com/products/api-upload');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $token
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'products' => [
            [
                'id' => '1',
                'name' => 'Молоко 2.5% 1л',
                'barcode' => '4820012345678',
                'price' => 35.50
            ]
        ],
        'priority' => 1
    ])
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    echo "Task ID: " . $result['task_id'];
}

Python Example:

import requests

url = 'https://c1.lacran.com/products/api-upload'
headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {token}'
}
data = {
    'products': [
        {
            'id': '1',
            'name': 'Молоко 2.5% 1л',
            'barcode': '4820012345678',
            'price': 35.50
        }
    ],
    'priority': 1
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result['success']:
    print(f"Task ID: {result['task_id']}")

📊 Параметри товару

Поле	Тип	Обов'язкове	Опис
`id`	string	✅	Унікальний ідентифікатор товару у вашій системі
`name`	string	✅	Назва товару (використовується для AI matching)
`barcode`	string	❌	Штрих-код товару (EAN-13, UPC, тощо)
`price`	number	❌	Ціна товару (використовуйте крапку: 35.50)

📈 Статуси завдань

Статус	Опис
`pending`	Завдання створено і очікує обробки
`processing`	Завдання обробляється AI системою
`completed`	Каталог успішно проіндексовано
`failed`	Помилка при обробці (перегляньте деталі)

✅ Рекомендації для Products API:

Використовуйте UTF-8 кодування для кирилиці
Поле id обов'язкове для ідентифікації товарів
Розбивайте великі каталоги (>10,000 товарів) на частини
Максимальний розмір JSON: 50 MB
Для відстеження статусу зберігайте task_id
Час обробки: 1-30 хвилин залежно від розміру

🔗 Веб-інтерфейс:

Також доступна веб-форма для завантаження каталогу:

https://c1.lacran.com/products/upload

Детальна документація: https://c1.lacran.com/api-docs.html

📊 Моделі даних

User Object

Поле	Тип	Опис
`id`	integer	Унікальний ідентифікатор користувача
`username`	string	Ім'я користувача для входу
`email`	string	Email адреса
`status`	integer	Статус користувача (10 = активний)
`org_id`	integer\|null	ID організації користувача

Organization Object

Поле	Тип	Опис
`id`	integer	Унікальний ідентифікатор організації
`name`	string	Назва організації
`edrpou`	string	Код ЄДРПОУ

DocSell Document Object

Поле	Тип	Опис
`UUID`	string	Унікальний ідентифікатор документа (UUID v4)
`Number`	string	Номер документа
`Date`	string	Дата та час документа (формат: DD.MM.YYYY HH:MM:SS)
`OrgEDRPOU`	string	ЄДРПОУ організації-постачальника
`ClientEDRPOU`	string	ЄДРПОУ організації-клієнта
`TotalAmount`	number	Загальна сума документа
`Items`	array	Масив товарів
`Services`	array	Масив послуг (необов'язково)

Item Object (у масиві Items)

Поле	Тип	Опис
`Name`	string	Назва товару
`Quantity`	number	Кількість
`Price`	number	Ціна за одиницю
`Amount`	number	Сума (Quantity × Price)

Service Object (у масиві Services)

Поле	Тип	Опис
`Name`	string	Назва послуги
`Amount`	number	Вартість послуги

⚠️ Коди помилок

HTTP Code	Опис	Приклад
`200`	Успішний запит	Дані повернуто успішно
`400`	Невірний запит	Відсутні обов'язкові поля
`401`	Не авторизовано	Невірний токен або відсутня авторизація
`404`	Не знайдено	Ресурс не існує
`500`	Внутрішня помилка	Помилка на сервері

💡 Рекомендації

🔒 Безпека:

Завжди використовуйте HTTPS у production
Зберігайте токени в безпечному місці
Не передавайте токени в URL параметрах

✅ Best Practices:

Завжди перевіряйте статус відповіді перед обробкою даних
Використовуйте timeout для запитів (рекомендовано 30 секунд)
Обробляйте помилки мережі та таймаути
Логінтесь знову якщо отримали 401 помилку

❌ Що НЕ робити:

Не зберігайте токени у localStorage (якщо можливо XSS)
Не використовуйте GET для конфіденційних операцій
Не ігноруйте SSL сертифікати

🧪 Тестування

PowerShell приклад:

# Login
$body = @{
    username = "john_doe"
    password = "secret123"
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://c1.lacran.com/api/auth/login" `
    -Method POST `
    -Body $body `
    -ContentType "application/json"

$token = $response.token

# Get current user
$headers = @{
    Authorization = "Bearer $token"
}

Invoke-RestMethod -Uri "https://c1.lacran.com/api/auth/me" `
    -Headers $headers

JavaScript приклад:

// Login
const response = await fetch('https://c1.lacran.com/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'john_doe',
    password: 'secret123'
  })
});

const data = await response.json();
const token = data.token;

// Get current user
const userResponse = await fetch('https://c1.lacran.com/api/auth/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const userData = await userResponse.json();