Sklado API для розробників

1. Отримати API-токен

Зайдіть у Налаштування → API-токени → «Створити». Токен показується лише раз — збережіть його у password manager. Можна обмежити токен скоупами (тільки read-only або лише products), задати TTL (термін дії) і відкликати у будь-який момент.

Передавайте токен у HTTP-заголовку:

Authorization: Bearer sklado_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Список товарів

curl 'https://api.sklado.com.ua/api/v1/products?limit=20' \
  -H 'Authorization: Bearer sklado_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Створити контрагента (нове ТОВ)

curl 'https://api.sklado.com.ua/api/v1/counterparties' \
  -X POST \
  -H 'Authorization: Bearer sklado_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "name": "ТОВ \"Ромашка\"",
    "kind": "LEGAL",
    "edrpou": "12345678",
    "phone": "+380501234567"
  }'

Усі тіла запитів і відповідей — JSON у UTF-8. Пагінація: query-параметри limit і offset. Відповідь: { data: [...], total, limit, offset }.

3. Скоупи (права токена)

При створенні токена можна обмежити його скоупами. Без обмежень — токен має всі права юзера, що його створив.

• products.read / products.write

  Каталог: товари, варіанти, групи

• counterparties.read / counterparties.write

  Клієнти і постачальники

• warehouses.read / warehouses.write

  Склади

• organizations.read / organizations.write

  Юр.особи (ФОП / ТОВ)

• documents.read / documents.write

  Документи (рахунки, накладні, ордери)

• payments.read / payments.write

  Платежі (вхідні / вихідні)

• stock.read

  Залишки на складах

• settings.read / settings.write

  Webhooks, токени, налаштування

4. Webhooks

Sklado шле POST-запити на ваш URL у відповідь на події. Створіть webhook у Налаштування → Webhooks. При створенні ви отримаєте secret (показується раз) — він використовується для перевірки підпису.

Підтримувані події

• document.created

  Створено новий документ (будь-якого типу)

• document.posted

  Документ проведено (рух залишків / податків зафіксовано)

• document.unposted

  Документ розпроведено (повернуто у draft)

• document.deleted

  Документ видалено (soft-delete)

• payment.received

  Зареєстровано вхідний платіж

• product.created

  Додано новий товар

• counterparty.created

  Додано нового контрагента

• low_stock

  Залишок товару впав до або нижче minStock

Приклад payload

{
  "event": "document.posted",
  "tenantId": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "2026-04-28T10:15:00.000Z",
  "data": {
    "id": "doc-uuid",
    "number": "INV-2026-00042",
    "type": "INVOICE_OUT",
    "totalAmount": 12450.00,
    "currency": "UAH"
  }
}

Заголовки запиту, який вам прийде

• Content-Type: application/json
• X-Sklado-Signature: <hmac-sha256(body, secret)>
• User-Agent: Sklado-Webhook/1.0

Timeout: 10 секунд. Після 10 поспіль невдалих доставок webhook автоматично деактивується — і ви побачите його у /settings/webhooks з помилкою. Можна знов увімкнути після фіксу.

Перевірка підпису — Node.js / Express

import { createHmac, timingSafeEqual } from 'crypto';

// Express middleware for verifying Sklado webhook signatures.
// Save the secret you got when creating the webhook (returned ONCE).
const SKLADO_SECRET = process.env.SKLADO_WEBHOOK_SECRET!;

export function verifySkladoSignature(req, res, next) {
  const sig = req.header('X-Sklado-Signature');
  if (!sig) return res.status(401).send('missing signature');

  const expected = createHmac('sha256', SKLADO_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  // timingSafeEqual prevents timing attacks
  const a = Buffer.from(sig, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).send('invalid signature');
  }
  next();
}

Перевірка підпису — Python / Flask

import hmac, hashlib, json

SKLADO_SECRET = b"<webhook secret from Sklado>"

def verify_sklado_signature(body: bytes, signature_header: str) -> bool:
    expected = hmac.new(SKLADO_SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

# Flask example
# @app.post("/sklado/webhook")
# def sklado_webhook():
#     if not verify_sklado_signature(request.get_data(), request.headers.get("X-Sklado-Signature")):
#         abort(401)
#     event = request.json
#     ...

5. Rate limits / ліміти

Поточний ліміт: 60 запитів на хвилину на токен. У разі перевищення повертаємо 429 Too Many Requests. Якщо ваша інтеграція потребує більше — напишіть на sklado.com.ua@gmail.com.

6. Підтримка

Знайшли баг, маєте feature-request, або щось не виходить? Пишіть: sklado.com.ua@gmail.com. Відповідаємо якнайшвидше.