Osnovna URL adresa
https://freebillgen.com/api/v1Autentifikacija
Svaki zahtjev koristi Bearer token. Stvorite ga pod Postavke → API ključevi, dodijelite mu potrebne opsege za čitanje/pisanje po resursu, postavite neobavezni rok isteka i pošaljite ga uz svaki zahtjev:
Authorization: Bearer <your-api-key>Zahtjevi se autentificiraju prema korisničkom računu koji je stvorio ključ i provjeravaju se u odnosu na njegove dodijeljene opsege. Token držite tajnim i opozovite ga ako je izložen ili vam više nije potreban.
Što možete učiniti
- Čitajte račune, klijente, tvrtke, uplate i ponavljajuće rasporede
- Stvarajte ih i ažurirajte (API za pisanje - Pro)
- Preuzmite izvještaje o PDV-u i starosti potraživanja kao JSON
- Pročitajte isti ograničeni red radnji Next koji koristi nadzorna ploča
- Čitajte datoteke e-računa dobavljača koje ste ručno učitali u Inbox (nije Peppol/e-mail krajnja točka za primanje)
- Preuzmite generička preslikavanja za OASIS UBL i UN/CEFACT CII za pregled (nisu provjerena profilom)
- Registrirajte krajnje točke webhooka za događaje vezane uz račune i uplate (Pro)
- Idempotency-Key na podržanim zapisima - promjena podataka zahtjeva pod istim ključem vraća 409
- Paginacija kursorom putem links.next, prilagodljiva pomoću per_page (maks. 100)
- Omogućite AI agentima čitanje svakog dijeljenog računa - schema.org/Invoice JSON-LD, uz Accept: application/json ili text/markdown na svakoj potpisanoj poveznici za dijeljenje
- MCP poslužitelj bez autentifikacije i samo za čitanje na https://freebillgen.com/api/mcp (get_invoice, verify_invoice) za AI agente
Konvencije
- Idempotencija
- Na podržanim pozivima za stvaranje i izvršavanje pošaljite jedinstveni Idempotency-Key. Ponovno slanje istih podataka o zahtjevu reproducira izvorni uspjeh; promjena podataka o zahtjevu vraća 409.
- Paginacija
- Pohranjeni popisi resursa paginirani su kursorom - slijedite links.next (ili proslijedite ?cursor=...) i prilagodite ?per_page= (maks. 100). Ograničeni niz radnji javlja svoje ograničenje i skraćeno stanje.
- Novac
- Novčani iznosi točni su JSON nizovi znakova oblikovani prema broju decimalnih mjesta valute definiranom standardom ISO 4217, kao što su "121.00" za EUR ili "500" za JPY. Jedinične cijene mogu zadržati dodatnu preciznost unosa.
- ID-ovi
- Svaki resurs adresira se pomoću neprozirnog ID-a, nikada uzastopnog broja.
Primjer: navedite svoje račune
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"Otvorite cjelovitu interaktivnu referencu API-ja →
Pitanja o API-ju za račune
Je li API za račune besplatan?
Da - API za čitanje uključen je u besplatni paket bez ikakve naknade. API za pisanje i odlazni webhookovi uključeni su u jednokratni paket Lifetime Pro od 49 € s uključenim porezom: jedno plaćanje, bez mjesečne naknade ili godišnjeg obnavljanja.
Kako se mogu autentificirati?
Stvorite Bearer token pod Postavke -> API ključevi, dodijelite mu opsege čitanja/pisanja po resursu i pošaljite ga kao zaglavlje Authorization: Bearer u svakom zahtjevu. Ključevi su ograničeni na vaš račun i mogu se opozvati ili isteći.
Mogu li programski stvarati račune?
Da, putem API-ja za pisanje, koji je dio Pro dodatka. On generira iste profesionalne račune kao i web aplikacija, s uzastopnim numeriranjem i konfigurabilnim obračunom PDV-a primijenjenim na strani poslužitelja. API ne potvrđuje usklađenost s lokalnim zakonima.
Kako mogu izbjeći stvaranje duplikata računa pri ponovnom pokušaju?
Pošaljite jedinstveni Idempotency-Key u pozivu za stvaranje. Ponovno slanje istih podataka o zahtjevu s tim ključem vraća izvorni rezultat. Ponovna upotreba istog ključa s izmijenjenim podacima o zahtjevu vraća 409 umjesto tihog ponavljanja drugog računa.
Mogu li pročitati račune koje sam primio?
Da, besplatno. GET /api/v1/inbox navodi podržane UBL/CII datoteke dobavljača koje ste ručno učitali, a koje je FreeBillGen analizirao, pri čemu je original sačuvan za reviziju; GET /api/v1/inbox/{id} vraća jednu. Prepoznavanje sintakse nije provjera profila, a ove krajnje točke ne čine FreeBillGen krajnjom točkom za Peppol, vladinu mrežu ili primanje e-pošte.
Može li AI agent pročitati račun bez korisničkog računa?
Da. Svaki račun koji podijelite putem potpisane javne poveznice čitljiv je agentima na istoj URL adresi: stranica uključuje schema.org/Invoice JSON-LD, a slanje zaglavlja Accept: application/json vraća strukturirani račun (stranke, stavke, ukupni iznosi, preostali iznos, opcije plaćanja), dok zaglavlje Accept: text/markdown vraća čisti prikaz s manjim brojem tokena. Također postoji poslužitelj Model Context Protocol (MCP) bez autentifikacije i samo za čitanje na https://freebillgen.com/api/mcp s alatima get_invoice i verify_invoice. Potpis poveznice je pristupni token. Smatrajte cijeli URL tajnim jer svatko tko ga primi može otvoriti račun.