← Інтеграція з e-conomic API

e-conomic REST API: практичний гайд

Що треба знати, щоб читати дані з e-conomic: два токени, сторінки до 1 000, фільтри в рядку запиту й проводки, що живуть під обліковим роком. Усі приклади працюють на публічній демо-угоді e-conomic — копіюйте й запускайте.

Зміст

  1. Автентифікація: два токени в кожному запиті
  2. Як клієнт дає доступ вашому застосунку
  3. Пагінація: skippages і pagesize
  4. Фільтри й сортування
  5. Проводки живуть під обліковим роком
  6. Граблі, на які ми наступили самі
  7. Або нехай це зробить JaKonto

Автентифікація: два токени в кожному запиті

Базова адреса — https://restapi.e-conomic.com. Кожен запит надсилає X-AppSecretToken (ідентифікує ваш застосунок — секрет) і X-AgreementGrantToken (дозвіл клієнта на його угоду), а також Content-Type: application/json.

Для тестів e-conomic дає публічну демо-угоду: обидва токени — просто "demo".

curl https://restapi.e-conomic.com/customers?pagesize=5 \
     -H "X-AppSecretToken: demo" \
     -H "X-AgreementGrantToken: demo" \
     -H "Content-Type: application/json"

Як клієнт дає доступ вашому застосунку

У застосунку є публічний токен (appPublicToken). Клієнт відкриває сторінку доступу e-conomic з ним і вашим redirectUrl, входить і погоджує. e-conomic повертає браузер із ?token=… — це X-AgreementGrantToken клієнта. Зберігайте його зашифрованим; він діє, доки клієнт не прибере застосунок.

https://secure.e-conomic.com/secure/api1/requestaccess.aspx
    ?appPublicToken=<APP_PUBLIC_TOKEN>
    &redirectUrl=https://example.com/e-conomic/callback

→ https://example.com/e-conomic/callback?token=<AGREEMENT_GRANT_TOKEN>

Пагінація: skippages і pagesize

Колекції віддають 20 елементів за замовчуванням і щонайбільше 1 000 через pagesize. skippages пропускає цілі сторінки. У відповіді є обʼєкт pagination з results, firstPage, nextPage і lastPage — ідіть за nextPage, доки він є.

import requests

H = {"X-AppSecretToken": "demo", "X-AgreementGrantToken": "demo"}
url = "https://restapi.e-conomic.com/invoices/booked?pagesize=1000"
invoices = []
while url:
    page = requests.get(url, headers=H, timeout=30).json()
    invoices += page["collection"]
    url = page["pagination"].get("nextPage")  # absent on the last page

Фільтри й сортування

Фільтр: ?filter=властивість$оператор:значення. Оператори: $eq, $ne, $gt, $gte, $lt, $lte, $like (підтримує *), $in і $nin (лише числа, напр. customerNumber$in:[2,5,7]). Умови зʼєднуються через $and: і $or:, дужки задають порядок; фільтр завжди URL-кодуйте.

Сортування: ?sort=name, за спаданням — ?sort=-name. Лише властивості, позначені в схемі як filterable/sortable, — інакше API відповідає 400.

Лише зміни з минулого разу: filter=lastUpdated$gt:<час> на, напр., /customers.

Проводки живуть під обліковим роком

Глобального списку /entries для читання за період нема: візьміть /accounting-years, виберіть роки, що перетинаються з вашим періодом, і читайте /accounting-years/{рік}/entries з фільтром за датою. На демо-угоді приклад повертає 138 проводок.

curl -G https://restapi.e-conomic.com/accounting-years/2022/entries \
     --data-urlencode 'filter=date$gte:2022-01-01$and:date$lte:2022-06-30' \
     --data-urlencode 'pagesize=1000' \
     -H "X-AppSecretToken: demo" -H "X-AgreementGrantToken: demo"

Граблі, на які ми наступили самі

  • Булеві поля пропускаються, коли вони false: відсутній barred означає «активний».
  • Суми — у кронах з десятковими; переводьте в ере (цілі), перш ніж додавати.
  • Проводка в іноземній валюті має amount у своїй валюті. Беріть amountInBaseCurrency — інакше ваш P&L не зійдеться з власними підсумками e-conomic.
  • Fair use — близько 50 000 викликів на добу на угоду. Кешуйте й тягніть лише зміни.
  • Idempotency-Key діє лише для записів, не для GET.

Або нехай це зробить JaKonto

JaKonto бере на себе токени, пагінацію, облікові роки, валюти й fair use і віддає інвойси, проводки, рахунки й контакти в тому ж вигляді, що з Billy і Dinero, — плюс ПДВ, P&L і CSV. Спробуйте безкоштовно на демо-компанії e-conomic:

curl -X POST https://jakonto.dk/api/v1/connections/economic-demo \
     -H "X-API-Key: jk_live_…"

curl https://jakonto.dk/api/v1/connections/$ID/invoices \
     -H "X-API-Key: jk_live_…"

Питання

Де офіційна документація API e-conomic?

На restdocs.e-conomic.com. Кожна колекція має JSON-схему, що показує, які поля можна фільтрувати й сортувати.

Чи можна протестувати API e-conomic без підписки?

Так. Поставте X-AppSecretToken і X-AgreementGrantToken у "demo" і викличте, напр., /customers.

Скільки елементів можна взяти за сторінку?

Щонайбільше 1 000 (pagesize=1000). За замовчуванням 20.

Чи пише JaKonto в e-conomic?

Ні. JaKonto лише читає.

Інтеграція з e-conomic API · Інтеграція з Billy API · Інтеграція з Dinero API · MCP-сервер

Отримати безкоштовний API-ключ Документація API JaKonto