Billy API: практичний гайд
Що треба знати, щоб читати дані з Billy: один токен доступу на компанію, сторінки до 1 000, повʼязані дані через include і суми, що живуть у проводках. Приклади використовують саме ті шляхи й параметри, які викликає JaKonto.
Зміст
Автентифікація: X-Access-Token
Базова адреса — https://api.billysbilling.com/v2, лише HTTPS. Токен доступу передається в заголовку X-Access-Token.
Токен створюється в Billy: Налаштування → Токени доступу → Створити токен. Він належить одній компанії й не спливає — для кількох компаній потрібен окремий токен на кожну. Зберігайте його зашифрованим.
curl https://api.billysbilling.com/v2/organization \
-H "X-Access-Token: <ACCESS_TOKEN>" \
-H "Content-Type: application/json"
Пагінація: page і pageSize
Списки приймають page і pageSize. pageSize — щонайбільше 1 000, і це ж значення за замовчуванням. У відповіді є meta.paging з page, pageCount, pageSize, total і nextUrl — продовжуйте, доки page не дійде до pageCount.
import requests
H = {"X-Access-Token": "<ACCESS_TOKEN>"}
invoices, page = [], 1
while True:
data = requests.get("https://api.billysbilling.com/v2/invoices", headers=H, timeout=30,
params={"page": page, "pageSize": 1000}).json()
invoices += data["invoices"]
if page >= data["meta"]["paging"]["pageCount"]:
break
page += 1
Повʼязані дані: include із sideload або embed
Через include=ресурс.поле:режим повʼязані обʼєкти приходять у тій самій відповіді. sideload (за замовчуванням) кладе їх окремим списком поруч — напр., contacts поруч з invoices; embed вкладає в кожен обʼєкт.
Корінь відповіді — в однині чи множині: {"invoice": {…}} для одного обʼєкта, {"invoices": […]} для списку.
curl -G https://api.billysbilling.com/v2/invoices \
--data-urlencode 'include=invoice.contact:sideload' \
-H "X-Access-Token: <ACCESS_TOKEN>"
→ {"meta": {…}, "invoices": [{"contactId": "…", …}], "contacts": [{"id": "…", "name": "…"}]}
Інвойси: state, isPaid і balance
state буває лише draft, approved або voided. Чи оплачено інвойс, видно не зі state, а з isPaid (true/false), а неоплачений залишок — у balance. Обидва поля лише для читання й змінюються, коли реєструють оплату.
Прострочені інвойси — це approved з isPaid=false і dueDate раніше сьогодні.
Проводки: суми живуть у /postings
Сума, рахунок і сторона (дебет/кредит) — у /postings, не в /transactions. Період задають minEntryDate і maxEntryDate (РРРР-ММ-ДД), анульовані відкидає isVoided=false, рахунок і документ підтягує include.
curl -G https://api.billysbilling.com/v2/postings \
--data-urlencode 'minEntryDate=2026-01-01' \
--data-urlencode 'maxEntryDate=2026-06-30' \
--data-urlencode 'isVoided=false' \
--data-urlencode 'include=posting.account:sideload,posting.transaction:sideload' \
-H "X-Access-Token: <ACCESS_TOKEN>"
Граблі, на які ми наступили самі
- Невідомі чи з помилкою написані параметри тихо ігноруються — приходить увесь список без фільтра. Напр., entryDatePeriod пишеться dates:2026-01-01...2026-06-30 з трьома крапками; з комою повертаються всі проводки.
- Оплачений інвойс досі має state approved. Дивлячись лише на state, ви порахуєте всі оплачені інвойси як відкриту дебіторку.
- Суми — у кронах з десятковими; переводьте в ере (цілі), перш ніж додавати.
- Документованих вебхуків у Billy нема. Зміни треба тягнути плановою синхронізацією.
- Billy не документує rate limits. Беріть великі сторінки (pageSize=1000) і не робіть паралельних викликів до однієї компанії.
Або нехай це зробить JaKonto
JaKonto бере на себе токен, пагінацію, sideload, статус оплати й проводки і віддає інвойси, проводки, рахунки й контакти в тому ж вигляді, що з e-conomic і Dinero, — плюс ПДВ, P&L і CSV. Інтеграція з Billy — у беті. Підключіться своїм токеном:
curl -X POST https://jakonto.dk/api/v1/connections \
-H "X-API-Key: jk_live_…" -H "Content-Type: application/json" \
-d '{"system": "billy", "credentials": {"access_token": "<ACCESS_TOKEN>"}}'
curl https://jakonto.dk/api/v1/connections/$ID/invoices \
-H "X-API-Key: jk_live_…"
Питання
Де офіційна документація API Billy?
На billy.dk/api. Там описано кожен ресурс, його поля й фільтри, які приймає список.
Де взяти токен доступу Billy?
У Billy: Налаштування → Токени доступу. Токен належить одній компанії й не спливає.
Скільки елементів можна взяти за сторінку?
Щонайбільше 1 000 (pageSize=1000), і це ж значення за замовчуванням.
Чи має Billy вебхуки?
Документованих — ні. Зміни тягнуться регулярною синхронізацією.
Чи пише JaKonto в Billy?
Ні. JaKonto лише читає.
Інтеграція з e-conomic API · Інтеграція з Billy API · Інтеграція з Dinero API · MCP-сервер