Pagrindinis URL
https://freebillgen.com/api/v1Autentifikavimas
Kiekvienai užklausai naudojamas Bearer prieigos raktas. Susikurkite jį skiltyje Nustatymai → API raktai, suteikite reikiamas konkretaus ištekliaus skaitymo / rašymo teises, jei norite, nustatykite galiojimo pabaigos laiką ir siųskite jį su kiekviena užklausa:
Authorization: Bearer <your-api-key>Užklausų tapatybė nustatoma pagal paskyrą, kurioje buvo sukurtas raktas, ir tikrinama pagal jam priskirtas prieigos teises. Laikykite raktą paslaptyje ir panaikinkite jo galiojimą, jei jis tapo viešai prieinamas arba nebėra reikalingas.
Ką galite daryti
- Skaityti sąskaitas faktūras, klientus, įmones, mokėjimus ir pasikartojančių sąskaitų faktūrų grafikus
- Sukurti ir atnaujinti juos (API rašymo funkcija - Pro)
- Gauti PVM ir senumo ataskaitas JSON formatu
- Skaityti tą pačią apribotą „Kiti veiksmai“ eilę, kurią naudoja informacinė panelė
- Skaityti tiekėjų e. sąskaitų faktūrų failus, kuriuos rankiniu būdu įkėlėte į „Inbox“ (ne į „Peppol“ ar el. pašto priėmimo galinį tašką)
- Atsisiųsti bendruosius OASIS UBL ir UN/CEFACT CII atitikmenis peržiūrai (nepatvirtintus pagal profilį)
- Registruoti „webhook“ galinius taškus sąskaitų faktūrų ir mokėjimų įvykiams (Pro)
- „Idempotency-Key“ palaikomuose įrašymuose - pakeisti užklausos duomenys su tuo pačiu raktu grąžina 409
- Puslapių numeracija naudojant „links.next“, reguliuojama parametru „per_page“ (maks. 100)
- Leiskite AI agentams skaityti bet kurią bendrinamą sąskaitą - schema.org/Invoice JSON-LD, taip pat „Accept: application/json“ arba „text/markdown“ kiekvienoje pasirašytoje bendrinimo nuorodoje
- Tik skaitymui skirtas MCP serveris be autentifikavimo adresu https://freebillgen.com/api/mcp (get_invoice, verify_invoice) - AI agentams
Konvencijos
- Idempotentiškumas
- Atliekant palaikomus kūrimo ir veiksmų iškvietimus, siųskite unikalų „Idempotency-Key“. Pakartotinai siunčiant identiškus užklausos duomenis, pakartojamas pirminis sėkmingas atsakymas; pakeitus užklausos duomenis, grąžinamas 409 kodas.
- Puslapių numeravimas
- Išsaugoti išteklių sąrašai yra suskirstyti pagal žymeklį - sekite „links.next“ (arba perduokite ?cursor=...) ir nustatykite ?per_page= (maks. 100). Ribotas veiksmų srautas praneša apie savo ribą ir sutrumpintą būseną.
- Pinigai
- Piniginės sumos yra tikslios JSON eilutės, suformatuotos pagal valiutos ISO 4217 mastelį, pavyzdžiui, „121.00“ EUR arba „500“ JPY. Vienetinės kainos gali išlaikyti papildomą įvesties tikslumą.
- ID
- Kiekvienas išteklius identifikuojamas nepermatomu identifikatoriumi, o ne eilės numeriu.
Pavyzdys: išvardykite savo sąskaitas faktūras
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"Atidarykite išsamų interaktyvų API žinyną →
Klausimai apie sąskaitų faktūrų API
Ar sąskaitų faktūrų API yra nemokamas?
Taip - skaitymo API yra įtrauktas į nemokamą planą be jokio mokesčio. Rašymo API ir išeinantys „webhooks“ yra įtraukti į „Lifetime Pro“ planą už 49 eurus su mokesčiais: vienkartinis mokėjimas, be mėnesinio mokesčio ar metinio atnaujinimo.
Kaip prisijungti?
Sukurkite „Bearer“ žetoną meniu „Nustatymai“ → „API raktai“, priskirkite jam skaitymo ir rašymo teises pagal išteklius ir siųskite jį kaip „Authorization: Bearer“ antraštę kiekviename užklausime. Raktai galioja tik jūsų paskyrai ir gali būti atšaukti arba pasibaigti.
Ar galiu kurti sąskaitas faktūras programiškai?
Taip, per rašymo API, kuris yra „Pro“ papildinio dalis. Jis sukuria tokias pačias profesionalias sąskaitas faktūras kaip ir internetinė programa, su eilės numeracija ir konfigūruojamu PVM apdorojimu, taikomu serverio pusėje. API nepatvirtina atitikties vietos įstatymams.
Kaip išvengti sąskaitų faktūrų dubliavimo bandant pakartotinai?
Siųskite unikalų idempotentiškumo raktą (Idempotency-Key) atlikdami sukūrimo iškvietą. Pakartotinai siunčiant identiškus užklausos duomenis su tuo raktu, grąžinamas pirminis rezultatas. Pakartotinai naudojant jį su pakeistais užklausos duomenimis, grąžinamas kodas 409, o ne tyliai pakartojama kita sąskaita.
Ar galiu perskaityti gautas sąskaitas faktūras?
Taip, nemokamai. GET /api/v1/inbox pateikia sąrašą palaikomų UBL/CII tiekėjų failų, kuriuos įkėlėte rankiniu būdu ir kuriuos „FreeBillGen“ išanalizavo, o originalai išsaugoti audito tikslais; GET /api/v1/inbox/{id} grąžina vieną failą. Sintaksės atpažinimas nėra profilio patvirtinimas, ir šie galiniai taškai nereiškia, kad „FreeBillGen“ yra „Peppol“, vyriausybinio tinklo ar el. pašto priėmimo galinis taškas.
Ar DI agentas gali perskaityti sąskaitą faktūrą neturėdamas paskyros?
Taip. Kiekvieną sąskaitą faktūrą, kuria dalijatės naudodami jos pasirašytą viešąją nuorodą, agentas gali perskaityti tuo pačiu URL adresu: puslapyje įterptas „schema.org/Invoice“ JSON-LD, o nusiuntus „Accept: application/json“ grąžinama struktūrizuota sąskaita faktūra (šalys, eilutės, sumos, mokėtina suma, mokėjimo galimybės), o nusiuntus „Accept: text/markdown“ grąžinamas švarus, mažai leksemų (žetonų) reikalaujantis atvaizdavimas. Taip pat yra autentifikavimo nereikalaujantis, tik skaitymo režimu veikiantis „Model Context Protocol“ (MCP) serveris adresu https://freebillgen.com/api/mcp su įrankiais „get_invoice“ ir „verify_invoice“. Nuorodos parašas yra prieigos žetonas. Laikykite visą URL adresą paslaptyje, nes bet kas, kas jį gaus, galės atidaryti sąskaitą faktūrą.