Məzmuna keç

İnkişaf etdiricilər

Faktura API

Öz kodunuzdan fakturalarınızı, müştərilərinizi, şirkətlərinizi, ödənişlərinizi, təkrarlanan cədvəllərinizi, yüklənmiş təchizatçı fayllarınızı, ƏDV və ya qalıq borcların müddətlər üzrə hesabatlarınızı və prioritetləşdirilmiş Növbəti addımlarınızı pulsuz oxuyun. Vergi daxil olmaqla 49 € ömürboyu Pro yazma əməliyyatları və çıxış webhook-ları əlavə edir, tək bir ödənişlə, aylıq ödənişsiz və illik yenilənmə tələb etmədən.

Əsas URL

https://freebillgen.com/api/v1

Avtentifikasiya

Hər tələb Bearer tokenindən istifadə edir. Parametrlər → API açarları altında birini yaradın, ona ehtiyac duyduğu resurs üzrə oxu/yazma səlahiyyətlərini verin, istəyə görə etibarlılıq müddəti təyin edin və hər tələbdə onu göndərin:

Authorization: Bearer <your-api-key>

Sorğular açarı yaradan hesaba qarşı autentifikasiya edilir və ona təyin olunmuş səlahiyyətlərlə yoxlanılır. Tokeni gizli saxlayın və o ifşa olunarsa və ya artıq ehtiyac yoxdursa, onu ləğv edin.

Nə edə bilərsiniz

  • Fakturaları, müştəriləri, şirkətləri, ödənişləri və təkrarlanan cədvəlləri oxuyun
  • Onları yaradın və yeniləyin (API yazma - Pro)
  • ƏDV və qalıq borcların müddətlər üzrə hesabatlarını JSON kimi götürün
  • İdarə panelində istifadə olunan eyni məhdud Növbəti addımlar növbəsini oxuyun
  • Təchizatçı e-faktura fayllarını oxuyun, onları Inbox-a (Peppol/e-poçt qəbul nöqtəsi deyil) əl ilə yükləmisiniz
  • Görünüş üçün ümumi OASIS UBL və UN/CEFACT CII uyğunlaşdırmalarını yükləyin (profil yoxlanışı aparılmayıb)
  • Faktura və ödəniş hadisələri üçün webhook son nöqtələrini qeydiyyatdan keçirin (Pro)
  • Dəstəklənən yazılarda Idempotency-Key - eyni açar altında dəyişdirilmiş tələb məlumatı 409 qaytarır
  • Cursor paginasiyası links.next vasitəsilə, per_page (maksimum 100) ilə tənzimlənir
  • AI agentlərinə istənilən paylaşılan fakturanı oxumağa icazə verin - schema.org/Invoice JSON-LD, həmçinin hər imzalanmış paylaşım linkində Accept: application/json və ya text/markdown
  • AI agentləri üçün https://freebillgen.com/api/mcp ünvanında avtorizasiyasız, yalnız oxumaq üçün MCP serveri (get_invoice, verify_invoice)

Qaydalar

İdempotentlik
Dəstəklənən create və action çağırışlarında unikal Idempotency-Key göndərin. Eyni sorğu məlumatlarını yenidən cəhd etmək orijinal uğuru təkrarlayır; dəyişdirilmiş sorğu məlumatları 409 qaytarır.
Səhifələmə
Saxlanmış resursların siyahıları kursorla səhifələnir - links.next keçidini izləyin (və ya ?cursor=... parametrini ötürün), həmçinin ?per_page= parametrini tənzimləyin (maksimum 100). Element sayı məhdud olan Növbəti addımlar lenti öz həddini və qısaldılıb-qısaldılmadığını göstərir.
Pul
Pul məbləğləri valyutanın ISO 4217 miqyasına uyğun dəqiq JSON sətirləridir, məsələn, EUR üçün "121.00" və ya JPY üçün "500". Vahid qiymətlər əlavə daxiletmə dəqiqliyini saxlaya bilər.
ID-lər
Hər bir resurs qeyri-şəffaf ID ilə ünvanlanır, ardıcıl nömrə ilə deyil.

Məsələn: fakturalarınızı siyahıya alın

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

Tam interaktiv API istinadını açın →

Faktura API sualları

Faktura API pulsuzdurmu?

Bəli - oxuma API-si pulsuz plana heç bir ödəniş olmadan daxildir. Yazma API-si və çıxan webhook-lar vergi daxil 49 € Lifetime Pro-ya daxildir: birdəfəlik ödəniş, aylıq haqq və ya illik yenilənmə yoxdur.

Necə autentifikasiya edim?

Tənzimləmələr -> API açarları altında Bearer tokeni yaradın, onu hər bir resurs üzrə oxu/yazma səlahiyyətləri ilə təyin edin və hər sorğuda Authorization: Bearer başlığı ilə göndərin. Açarlar yalnız sizin hesabınıza məxsusdur və ləğv edilə və ya etibarlılıq müddəti bitə bilər.

Fakturaları proqram təminatı vasitəsilə yarada bilərəmmi?

Bəli, Pro əlavəsinin bir hissəsi olan write API vasitəsilə. O, veb tətbiqdə olduğu kimi ardıcıl nömrələnmə və server tərəfində tənzimlənə bilən ƏDV idarəetməsi ilə eyni peşəkar fakturaları yaradır. API yerli qanunlara uyğunluğu təsdiqləmir.

Təkrar cəhd zamanı dublikat fakturaların yaranmasının qarşısını necə ala bilərəm?

Yaradılma çağırışında unikal Idempotency-Key göndərin. Eyni sorğu məlumatları ilə həmin açar vasitəsilə yenidən cəhd etmək ilkin nəticəni qaytarır. Həmin açardan dəyişdirilmiş sorğu məlumatları ilə yenidən istifadə etdikdə sistem fərqli faktura ilə səssizcə cavab vermək əvəzinə 409 səhv kodu qaytarır.

Aldığım fakturaları oxuya bilərəmmi?

Bəli, pulsuzdur. GET /api/v1/inbox dəstəklənən UBL/CII təchizatçı fayllarını siyahıya alır ki, siz onları əl ilə yükləmisiniz və FreeBillGen analiz edib, audit üçün orijinal saxlanılıb; GET /api/v1/inbox/{id} birini qaytarır. Sintaksis tanıma profilin təsdiqi deyil və bu son nöqtələr FreeBillGen-i Peppol, dövlət şəbəkəsi və ya e-poçt qəbul edən son nöqtə etmir.

AI agenti hesab olmadan fakturanı oxuya bilərmi?

Bəli. İmzalanmış ictimai linki vasitəsilə paylaşdığınız hər bir fakturanı eyni URL-də agent oxuya bilər: səhifə schema.org/Invoice JSON-LD-ni yerləşdirir və Accept: application/json göndərmək strukturlaşdırılmış fakturanı (tərəflər, xətt elementləri, cəmlər, ödənilməli balans, ödəniş variantları) qaytarır, Accept: text/markdown isə təmiz, az tokenli təqdimatı qaytarır. Həmçinin https://freebillgen.com/api/mcp ünvanında autentifikasiyasız, yalnız oxumağa icazə verilən Model Context Protocol (MCP) serveri mövcuddur; burada get_invoice və verify_invoice alətləri yerləşir. Linkin imzası giriş tokenidir. Tam URL-i gizli sayın, çünki onu əldə edən hər kəs fakturanı aça bilər.

API açarını pulsuz əldə edin

Hesab yaradın, Tənzimləmələr -> API açarları bölməsinə keçin və oxu API-si ilə pulsuz başlayın. Kart tələb olunmur. Əgər sonradan yazı əməliyyatlarına və ya xarici webhook-lara ehtiyacınız olarsa, ömürlük Pro lisenziyası bir dəfə 49 €, vergilər daxil olmaqla, yenilənmədən əldə edilir.

Pulsuz başla