← Інтеграція з Billy API

Billy API: практичний гайд

Що треба знати, щоб читати дані з Billy: один токен доступу на компанію, сторінки до 1 000, повʼязані дані через include і суми, що живуть у проводках. Приклади використовують саме ті шляхи й параметри, які викликає JaKonto.

Зміст

  1. Автентифікація: X-Access-Token
  2. Пагінація: page і pageSize
  3. Повʼязані дані: include із sideload або embed
  4. Інвойси: state, isPaid і balance
  5. Проводки: суми живуть у /postings
  6. Граблі, на які ми наступили самі
  7. Або нехай це зробить 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-сервер