REST, JSON, один ключ у заголовку. Виставляйте рахунки з CRM, сайту чи Make — і отримуйте вебхук, щойно клієнт оплатив. Доступне на тарифі Business.
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 |
Клієнта можна передати як 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 з назвою і ціною.
{
"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": [ … ]
}
}
Параметри: 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_ВАШ_КЛЮЧ"
Замість id можна передати номер: /invoices/INV-0042.
Для інтеграцій із касою чи власним обліком. Поля: amount (за замовчуванням — залишок), paid_at, note. Якщо підключений банк, статус і так ставиться сам.
Оплачений рахунок не скасовується — 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 | Що означає |
|---|---|---|
unauthorized | 401 | Немає заголовка з ключем |
invalid_key | 401 | Ключ недійсний або відкликаний |
plan_required | 403 | Потрібен тариф Business |
not_found | 404 | Рахунок, клієнт або адреса не знайдені |
validation_failed | 422 | Помилки в полях — дивіться error.fields |
no_requisites | 422 | У кабінеті не заповнені назва, код і IBAN |
limit_reached | 422 | Вичерпано ліміт тарифу на місяць |
already_paid / not_open | 422 | Дія несумісна зі статусом рахунку |
rate_limited | 429 | Понад 120 запитів на хвилину |
source: "api" — їх видно в кабінеті нарівні з іншими.url можна зберігати у себе./v1): поля можуть додаватись, але наявні не зникнуть без нової версії.