API v1
REST API за Factuur.software. Част от Pro абонамента. JSON вход и изход, Bearer удостоверяване.
Удостоверяване
Изпрати своя API ключ в заглавката Authorization:
Authorization: Bearer JOUW_SLEUTEL
Генерирай своя ключ чрез Профил, под API достъп. Ключът е видим само веднъж - след това запазваме само хеш. Загуби го? Отмени го и генерирай нов.
Ограничение на скоростта
1000 заявки на час на потребител. Над това следва HTTP 429.
Endpoints
| Метод | Път | Описание |
|---|---|---|
| GET | /api/v1/me | профил, абонамент, функции и потребление |
| GET | /api/v1/invoices | фактури (неархивирани); заявка: от, до (YYYY-MM-DD), лимит (макс 1000), отместване |
| GET | /api/v1/invoices/{id} | една фактура с редове и клиент |
| POST | /api/v1/invoices | създай фактура; invoice_number празно = автоматично номериране, редове по избор |
| PUT | /api/v1/invoices/{id} | промени статус, invoice_number, issue_date, due_date, notes или customer_id |
| DELETE | /api/v1/invoices/{id} | архивира фактурата (фискално задължение за съхранение, без окончателно изтриване) |
| GET | /api/v1/customers | клиенти; запитване: лимит, отместване |
| GET | /api/v1/customers/{id} | един клиент |
| POST | /api/v1/customers | създай клиент; името е задължително |
| PUT | /api/v1/customers/{id} | промени полетата на клиента |
| DELETE | /api/v1/customers/{id} | изтрий клиент; 409 докато все още има фактури свързани |
| GET | /api/v1/expenses | разходи; запитване: от, до (ГГГГ-ММ-ДД), лимит, отместване |
| GET | /api/v1/expenses/{id} | един разход |
| POST | /api/v1/expenses | създай разход |
| PUT | /api/v1/expenses/{id} | промени разход; сумите и ДДС ще бъдат преизчислени |
| DELETE | /api/v1/expenses/{id} | изтрий разход |
Статус кодове
200/201успешно401Липсва Bearer токен или е невалиден403абонаментът не дава достъп до API404не е намерен409конфликт, например изтриване на клиент с фактури422невалиден payload429надвишен лимит на скоростта
Примери
curl -H "Authorization: Bearer JOUW_SLEUTEL" https://factuur.software/api/v1/me
curl "https://factuur.software/api/v1/invoices?from=2026-01-01&limit=50" -H "Authorization: Bearer JOUW_SLEUTEL"
curl -X POST -H "Authorization: Bearer JOUW_SLEUTEL" -H "Content-Type: application/json" -d '{"customer_id":1,"lines":[{"description":"Consultancy","quantity":8,"unit_price":95,"tax_rate":21}]}' https://factuur.software/api/v1/invoices
curl -X PUT -H "Authorization: Bearer JOUW_SLEUTEL" -H "Content-Type: application/json" -d '{"status":"betaald"}' https://factuur.software/api/v1/invoices/123