Yours Invoice

API Yours Invoice

REST, JSON, один ключ у заголовку. Виставляйте рахунки з CRM, сайту чи Make — і отримуйте вебхук, щойно клієнт оплатив. Доступне на тарифі Business.

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

  1. Створіть ключКабінет → Налаштування → API → «Створити ключ». Повний ключ показується один раз.
  2. Перевірте доступЗапит нижче має повернути дані вашого кабінету.
  3. Створіть рахунокУ відповіді буде url — посилання, яке надсилаєте клієнту.
curl https://invoice.yours.ua/api/v1/me \
  -H "Authorization: Bearer yi_ВАШ_КЛЮЧ"

Основи

Базова адресаhttps://invoice.yours.ua/api/v1
АвтентифікаціяAuthorization: Bearer yi_… (або X-Api-Key)
ФорматJSON, UTF-8. Тіло запиту — Content-Type: application/json
Ліміт120 запитів на хвилину на ключ
Помилки{"error":{"code":"…","message":"…"}}, код HTTP 4xx/5xx
ТарифBusiness. На інших тарифах — 403 plan_required

Рахунки

POST /invoices — створити

Клієнта можна передати як customer_id (вже є в кабінеті) або об'єктом customer — тоді він створиться або знайдеться за кодом/поштою. Тип (фізособа / ФОП / компанія) визначається довжиною коду: 10 цифр — ФОП, 8 — компанія.

curl -X POST https://invoice.yours.ua/api/v1/invoices \
  -H "Authorization: Bearer yi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "ТОВ «Альфа Трейд»",
      "tax_id": "41234567",
      "address": "01001, м. Київ, вул. Хрещатик, 1",
      "email": "buh@alfa.ua"
    },
    "due_days": 7,
    "note": "Після оплати надішлемо акт",
    "items": [
      { "name": "Розробка лендингу", "qty": 1, "unit": "послуга", "price": 25000 },
      { "name": "Підтримка", "qty": 3, "unit": "міс", "price": 1500 }
    ]
  }'

Поля: customer_id | customer{name,tax_id,address,email,phone,contact_name}, issued_at, due_at або due_days, discount, note, comment, items[]{name,qty,unit,price} — обов'язкові лише items з назвою і ціною.

Відповідь 201

{
  "data": {
    "id": 128,
    "number": "INV-0042",
    "status": "sent",
    "url": "https://invoice.yours.ua/i/8F72K",
    "pdf_url": "https://invoice.yours.ua/i/8F72K/pdf",
    "total": 29500,
    "due_amount": 29500,
    "due_at": "2026-10-27",
    "purpose": "Оплата за рахунком №INV-0042 від 20.10.2026, код YI-7KQ2M. Без ПДВ.",
    "customer": { "id": 7, "name": "ТОВ «Альфа Трейд»", "type": "company", … },
    "items": [ … ]
  }
}

GET /invoices — список

Параметри: status (open, paid, overdue, cancelled, all), from, to (дати рахунку), customer_id, limit (до 100), page.

curl "https://invoice.yours.ua/api/v1/invoices?status=open&limit=50" \
  -H "Authorization: Bearer yi_ВАШ_КЛЮЧ"

GET /invoices/{id} — один рахунок

Замість id можна передати номер: /invoices/INV-0042.

POST /invoices/{id}/pay — відмітити оплату

Для інтеграцій із касою чи власним обліком. Поля: amount (за замовчуванням — залишок), paid_at, note. Якщо підключений банк, статус і так ставиться сам.

POST /invoices/{id}/cancel — скасувати

Оплачений рахунок не скасовується — 422 already_paid.

Клієнти

GET /customers?q=пошук — список. POST /customers — створити; якщо клієнт із таким кодом або поштою вже є, повернеться наявний (без дублів).

Вебхуки

Додаються в кабінеті: Налаштування → API → «Додати вебхук». Ми надсилаємо POST з JSON на вашу адресу.

ПодіяКоли
invoice.createdРахунок створено
invoice.viewedКлієнт відкрив рахунок
invoice.paidРахунок оплачено
invoice.partialЧасткова оплата
invoice.cancelledРахунок скасовано

Тіло та заголовки

POST /ваш-обробник HTTP/1.1
X-Yours-Event: invoice.paid
X-Yours-Delivery: 1842
X-Yours-Timestamp: 1792000000
X-Yours-Signature: 9f2c…        ← HMAC-SHA256 тіла вашим секретом

{
  "event": "invoice.paid",
  "created_at": "2026-10-20T14:03:11+03:00",
  "data": { "invoice": { "id": 128, "number": "INV-0042", "status": "paid", … } }
}

Перевірка підпису

// PHP
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_YOURS_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
# Python
import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Yours-Signature', '')):
    abort(401)

Відповідайте 200 швидко. Ми чекаємо 10 секунд. Якщо сервер відповів помилкою або не відповів — повторимо 6 разів зі зростаючою паузою (1 хв, 5 хв, 30 хв, 2 год, 6 год). Після 20 невдач поспіль вебхук вимикається, щоб не стукати в мертву адресу. Події можуть прийти повторно — звіряйте за X-Yours-Delivery або номером рахунку.

Коди помилок

КодHTTPЩо означає
unauthorized401Немає заголовка з ключем
invalid_key401Ключ недійсний або відкликаний
plan_required403Потрібен тариф Business
not_found404Рахунок, клієнт або адреса не знайдені
validation_failed422Помилки в полях — дивіться error.fields
no_requisites422У кабінеті не заповнені назва, код і IBAN
limit_reached422Вичерпано ліміт тарифу на місяць
already_paid / not_open422Дія несумісна зі статусом рахунку
rate_limited429Понад 120 запитів на хвилину

Що варто знати

Потрібна інтеграція, якої тут немає?Напишіть — додамо, якщо це корисно не лише вам.
Написати в Telegram