Pereiti prie turinio

Kūrėjams

Sąskaitų faktūrų API

Nemokamai skaitykite savo sąskaitas faktūras, klientus, įmones, mokėjimus, pasikartojančių sąskaitų grafikus, įkeltus tiekėjų failus, PVM ar skolų senėjimo ataskaitas bei prioritetinį tolesnių veiksmų sąrašą tiesiai iš savo kodo. Lifetime Pro už 49 € (mokesčiai įskaičiuoti) suteikia rašymo operacijas ir išeinančius „webhook" pranešimus už vieną mokėjimą, be mėnesinio mokesčio ir be metinio pratęsimo.

Bazinis URL

https://freebillgen.com/api/v1

Autentifikacija

Kiekvienai užklausai naudojamas Bearer prieigos raktas. Sukurkite jį skiltyje Nustatymai → API raktai, suteikite reikiamas kiekvieno ištekliaus skaitymo ar rašymo teises, pasirinktinai nustatykite galiojimo pabaigą ir siųskite su kiekviena užklausa:

Authorization: Bearer <your-api-key>

Užklausos tapatybė susiejama su raktą sukūrusia paskyra, o veiksmai tikrinami pagal suteiktas teises. Laikykite raktą paslaptyje ir atšaukite, jei jis buvo atskleistas arba tapo nebereikalingas.

Ką galite daryti

  • Skaityti sąskaitas faktūras, klientus, įmones, mokėjimus ir pasikartojančių sąskaitų grafikus
  • Kurti ir atnaujinti juos (rašymo API – Pro)
  • Gauti PVM ir skolų senėjimo ataskaitas JSON formatu
  • Skaityti tą patį ribotą tolesnių veiksmų sąrašą, kuris rodomas valdymo skydelyje
  • Skaityti tiekėjų e. sąskaitų failus, kuriuos rankiniu būdu įkėlėte į gautųjų aplanką (tai nėra Peppol ar el. pašto priėmimo taškas)
  • Atsisiųsti bendruosius OASIS UBL ir UN/CEFACT CII susiejimus peržiūrai (profilis nepatikrintas)
  • Registruoti „webhook" adresus sąskaitų faktūrų ir mokėjimų įvykiams (Pro)
  • Idempotency-Key palaikomoms rašymo užklausoms – pakeisti duomenys su tuo pačiu raktu grąžina 409
  • Kursoriaus puslapiavimas per links.next, reguliuojamas per per_page (ne daugiau kaip 100)
  • Leisti DI agentams skaityti bet kurią pasidalintą sąskaitą faktūrą – schema.org/Invoice JSON-LD, taip pat Accept: application/json arba text/markdown kiekvienoje pasirašytoje dalijimosi nuorodoje
  • Be autentifikacijos, tik skaitymo MCP serveris adresu https://freebillgen.com/api/mcp (get_invoice, verify_invoice) DI agentams

Susitarimai

Idempotentiškumas
Palaikomoms kūrimo ir veiksmo užklausoms siųskite unikalų Idempotency-Key. Pakartojus tuos pačius duomenis grąžinamas pirminis sėkmingas atsakymas, o pakeisti duomenys grąžina 409.
Puslapiavimas
Išsaugotų išteklių sąrašai puslapiuojami kursoriumi – sekite links.next (arba perduokite ?cursor=...) ir reguliuokite ?per_page= (ne daugiau kaip 100). Ribotas veiksmų sąrašas pateikia limit ir truncated reikšmes.
Sumos
Piniginės sumos pateikiamos kaip tikslios JSON eilutės, suformatuotos pagal ISO 4217 valiutos tikslumą, pavyzdžiui, „121.00" EUR arba „500" JPY. Vieneto kainose gali būti išsaugotas papildomas įvesties tikslumas.
ID
Kiekvienas išteklius adresuojamas neskaidriu id, niekada – nuosekliu numeriu.

Pavyzdys: išvardyti savo sąskaitas faktūras

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

Atidaryti visą interaktyvią API dokumentaciją →

Klausimai apie sąskaitų faktūrų API

Ar sąskaitų faktūrų API nemokama?

Taip – skaitymo API įeina į nemokamą planą be jokio mokesčio. Rašymo API ir išeinantys „webhook" pranešimai įtraukti į Lifetime Pro už 49 € (mokesčiai įskaičiuoti): vienas mokėjimas, be mėnesinio mokesčio ar metinio pratęsimo.

Kaip autentifikuotis?

Sukurkite Bearer prieigos raktą skiltyje Nustatymai -> API raktai, kiekvienam ištekliui priskirkite skaitymo arba rašymo teises ir su kiekviena užklausa siųskite jį antraštėje Authorization: Bearer. Raktai susieti su Jūsų paskyra, juos galima atšaukti arba nustatyti jų galiojimo pabaigą.

Ar galiu išrašyti sąskaitas faktūras programiškai?

Taip, per rašymo API, kuri yra Pro priedo dalis. Ji generuoja tokias pačias profesionalias sąskaitas faktūras kaip ir interneto programa, o nuoseklus numeravimas ir konfigūruojamas PVM apdorojimas pritaikomi serveryje. API nepatvirtina atitikties vietos įstatymų reikalavimams.

Kaip išvengti besidubliuojančių sąskaitų faktūrų pakartojus užklausą?

Kūrimo užklausoje siųskite unikalų Idempotency-Key. Pakartojus tuos pačius duomenis su tuo raktu, API grąžina pirminį rezultatą. Jei duomenys pakeisti, grąžinamas 409, o ne tyliai sukuriama kita sąskaita faktūra.

Ar galiu skaityti gautas sąskaitas faktūras?

Taip, nemokamai. GET /api/v1/inbox pateikia palaikomus UBL/CII tiekėjų failus, kuriuos rankiniu būdu įkėlėte ir kuriuos FreeBillGen apdorojo, o originalas išsaugomas auditui; GET /api/v1/inbox/{id} grąžina vieną failą. Sintaksės atpažinimas nėra profilio patikra, ir šie API galiniai taškai nepaverčia FreeBillGen Peppol, valstybinio tinklo ar el. pašto priėmimo tašku.

Ar DI agentas gali perskaityti sąskaitą faktūrą be paskyros?

Taip. Kiekviena sąskaita faktūra, kuria dalijamasi per pasirašytą viešą nuorodą, yra perskaitoma agento tuo pačiu URL: puslapyje įterpta schema.org/Invoice JSON-LD, o siunčiant Accept: application/json grąžinama struktūrinė sąskaita faktūra (šalys, eilutės, sumos, mokėtinas likutis, mokėjimo parinktys), tuo tarpu Accept: text/markdown grąžina švarų, mažai žetonų naudojantį atvaizdavimą. Taip pat yra be autentifikacijos veikiantis, tik skaitymui skirtas Model Context Protocol (MCP) serveris adresu https://freebillgen.com/api/mcp su get_invoice ir verify_invoice įrankiais. Nuorodos parašas yra prieigos raktas. Visą URL laikykite paslaptyje, nes bet kas, jį gavęs, gali atverti sąskaitą faktūrą.

Gaukite API raktą nemokamai

Susikurkite paskyrą, atidarykite Nustatymai -> API raktai ir pradėkite naudoti skaitymo API nemokamai. Kortelė nebūtina. Jei vėliau prireiks rašymo operacijų ar išeinančių „webhook“ pranešimų, „Lifetime Pro“ visam laikui kainuoja 49 € (mokesčiai įskaičiuoti), be pratęsimo.

Susikurti paskyrą