Към съдържанието

Разработчици

API за фактури

Четете безплатно от своя код фактури, клиенти, фирми, плащания, периодични графици, качени файлове от доставчици, отчети за ДДС и просрочия и приоритизираните следващи действия. Lifetime Pro за 49 € с включени данъци добавя операции за запис и изходящи уебхукове с едно плащане, без месечна такса и без годишно подновяване.

Базов URL

https://freebillgen.com/api/v1

Удостоверяване

Всяка заявка използва Bearer токен. Създайте го от Настройки → API ключове, дайте му нужните права за четене или запис за всеки ресурс, задайте срок по желание и го изпращайте с всяка заявка:

Authorization: Bearer <your-api-key>

Заявките се удостоверяват към акаунта, създал ключа, и се проверяват спрямо зададените права. Пазете токена в тайна и го отменете, ако бъде разкрит или вече не е нужен.

Какво можете да правите

  • Четене на фактури, клиенти, фирми, плащания и периодични графици
  • Създаване и актуализиране на тези ресурси чрез API за запис (Pro)
  • Извличане на справки за ДДС и просрочия като JSON
  • Четене на същата ограничена опашка със следващи действия, която използва таблото
  • Четене на файлове с електронни фактури от доставчици, които сте качили ръчно във Входящи (това не е крайна точка за получаване по Peppol или имейл)
  • Изтегляне на общи OASIS UBL и UN/CEFACT CII съпоставяния за преглед (без валидиране по профил)
  • Регистриране на крайни точки за уебхукове при събития с фактури и плащания (Pro)
  • Idempotency-Key при поддържаните операции за запис. Променени данни в заявката със същия ключ връщат 409
  • Странициране с курсор чрез links.next и настройка чрез per_page (до 100)
  • Четене на споделени фактури от AI агенти чрез JSON-LD по schema.org/Invoice и Accept: application/json или text/markdown за всяка подписана връзка
  • MCP сървър без удостоверяване и само за четене на https://freebillgen.com/api/mcp с инструментите get_invoice и verify_invoice за AI агенти

Конвенции

Идемпотентност
При поддържаните заявки за създаване и действия изпращайте уникален Idempotency-Key. Повторение със същите данни връща първоначалния успешен резултат, а различни данни връщат 409.
Странициране
Списъците със запазени ресурси използват странициране с курсор. Следвайте links.next или подайте ?cursor=... и задайте ?per_page= до 100. Ограниченият поток с действия посочва лимита си и дали е съкратен.
Парични суми
Паричните суми са точни JSON низове, форматирани според десетичната точност на валутата по ISO 4217, например "121.00" за EUR или "500" за JPY. Единичните цени могат да запазят допълнителна точност от входните данни.
Идентификатори
Всеки ресурс се адресира чрез непрозрачен ID, а не чрез последователен номер.

Пример: списък на вашите фактури

curl https://freebillgen.com/api/v1/invoices \
  -H "Authorization: Bearer $FREEBILLGEN_API_KEY"

Отворете пълната интерактивна документация за API →

Въпроси за API за фактури

Безплатен ли е API за фактури?

Да. API за четене е включен безплатно. API за запис и изходящите уебхукове са включени в Lifetime Pro за 49 € с включени данъци, едно плащане, без месечна такса и без годишно подновяване.

Как се удостоверявам?

Създайте Bearer токен от Настройки > API ключове, задайте му права за четене или запис за нужните ресурси и го изпращайте в HTTP заглавката Authorization: Bearer при всяка заявка. Ключовете важат само за собствения ви акаунт, могат да имат срок и могат да бъдат отменени.

Мога ли да създавам фактури програмно?

Да, чрез API за запис, който е част от Pro. Той създава същите професионални фактури като уеб приложението, с поредно номериране и настройваемо третиране на ДДС от страна на сървъра. API не удостоверява съответствие с местното право.

Как да избегна създаването на дублирани фактури при повторен опит?

Изпратете уникален Idempotency-Key при заявката за създаване. Повторение със същите данни връща първоначалния резултат. Повторна употреба с променени данни връща 409, вместо без предупреждение да върне резултат за друга фактура.

Мога ли да чета получените фактури?

Да, безплатно. GET /api/v1/inbox изброява поддържаните UBL и CII файлове от доставчици, които сте качили ръчно и FreeBillGen е анализирал, като оригиналът се пази за одит. GET /api/v1/inbox/{id} връща един запис. Разпознаването на синтаксиса не е валидиране по профил и тези крайни точки не превръщат FreeBillGen в крайна точка за получаване по Peppol, държавна мрежа или имейл.

Може ли AI агент да прочете фактура без акаунт?

Да. Всяка фактура, споделена чрез подписаната публична връзка, може да се чете от агент на същия URL. Страницата вгражда JSON-LD по schema.org/Invoice. Accept: application/json връща структурирана фактура с участници, редове, общи и дължими суми и начини за плащане, а Accept: text/markdown връща кратък текстов изглед. На https://freebillgen.com/api/mcp има и MCP сървър без удостоверяване и само за четене с инструменти get_invoice и verify_invoice. Подписът във връзката е токенът за достъп. Пазете целия URL в тайна, защото всеки, който го получи, може да отвори фактурата.

Вземете API ключ безплатно

Създайте акаунт, отворете Настройки > API ключове и започнете безплатно с API за четене. Не е нужна карта. Ако по-късно са ви нужни операции за запис или изходящи уебхукове, Lifetime Pro струва 49 € еднократно с включени данъци и без подновяване.

Създайте акаунт