Fiscomm API — dokumentacija
Fiscomm ima REST API za fiskalizaciju. Šalješ podatke o porudžbini, dobijaš fiskalni račun — broj, QR kod, PDF i link za proveru. Bez uređaja i bez kucanja.
Puna referenca svih endpointa, sa primerima zahteva i odgovora, je na api.fiscomm.rs/docs.
Otvori api.fiscomm.rs/docs
Kako da počneš
Odeljak „Kako da počneš“Treba ti troje:
- Fiscomm nalog — otvoriš ga sam (otvori nalog).
- API ključ — vezan je za jedan shop, nađeš ga u nalogu.
- Bezbednosni element — sadrži tvoj sertifikat i njime se potpisuje svaki račun. Tražiš ga od Poreske uprave preko portala ePorezi; za Fiscomm ti treba tip „sertifikat“, koji stiže kao fajl.
Za test ti bezbednosni element ne treba: u nalogu zatraži demo, i kad ga odobrimo, u demo firmi napravi DEMO API ključ. Bezbednosni element treba tek kad izdaješ prave račune.
Autentikacija
Odeljak „Autentikacija“API ključ šalješ kao Bearer token u standardnom Authorization zaglavlju.
Authorization: Bearer <tvoj-api-kljuc>Bazni URL je https://api.fiscomm.rs — isti za test i za produkciju. Ne postoji poseban test host.
| Nalog | Šta se dobija |
|---|---|
| DEMO nalog | test sertifikat, računi idu u sandbox Poreske uprave, nisu pravi |
| Produkcijski nalog | tvoj pravi sertifikat, računi su pravi fiskalni dokumenti |
Provera da ključ radi:
curl -X POST https://api.fiscomm.rs/auth/verify-api-token \ -H "Authorization: Bearer $FISCOMM_API_KEY"Provera na koju firmu i shop je ključ vezan:
curl https://api.fiscomm.rs/auth/api-key/me \ -H "Authorization: Bearer $FISCOMM_API_KEY"Prvi račun u test modu
Odeljak „Prvi račun u test modu“invoiceType = training — račun prolazi ceo tok, ali nije pravi fiskalni račun.
POST https://api.fiscomm.rs/receipt/training/saleAuthorization: Bearer $FISCOMM_API_KEYContent-Type: application/json
{ "orderNumber": "TEST-1001", "items": [ { "name": "Konsultacije, 1h", "quantity": 1, "unitPrice": 6000, "totalAmount": 6000, "labels": ["F"] } ], "payments": [ { "type": "cash", "amount": 6000 } ], "metaFields": { "order_id": "1001" }}Odgovor sadrži invoiceNumber (PFR broj), invoicePdfUrl i verificationUrl (link za proveru kod Poreske uprave). Sliku QR koda povuci sa GET /archive/receipts/{invoiceNumber}.
Poreske oznake ne upisuj u kod. Povuci ih sa GET /receipt/tax-rates za nalog kojim se autentikuješ. Oznake DEMO naloga (A, E, F) ne postoje na produkciji, gde su Ђ, Е, Г i А. Oznaka koja ne postoji na nalogu vraća ERR_01010.
Prelazak na živo
Odeljak „Prelazak na živo“Promeniš training u normal i koristiš ključ produkcijskog naloga — istog hosta, istog oblika zahteva. Ono što uz to mora da se promeni su poreske oznake: iz odgovora GET /receipt/tax-rates tog naloga, a ne one iz primera iznad.
POST /receipt/normal/salePre nego što to uradiš, proveri troje:
- Bezbednosni element je u nalogu i shop je aktivan.
orderNumberdolazi iz tvog sistema i zaista je jedinstven.- Iznosi u
itemsipaymentsse slažu — server ih poredi.
Česta pitanja pri prelasku (gde je ključ, demo nasuprot produkcije, timeout) su u bazi znanja: API ključ, test i produkcija.
Ako ne mogu da se slože zbog zaokruživanja, postoji settings.skipAmountValidation. Koristi ga samo ako moraš — postoji zbog sistema koji računaju cene drugačije, ne zbog grešaka u podacima.
Storno
Odeljak „Storno“Storno je isti poziv sa refund umesto sale:
POST /receipt/normal/refundZa storno je referentDocumentNumber obavezan — to je invoiceNumber računa koji storniraš. buyerId je takođe obavezan kod storna, u formatu tip:identifikator (npr. 10:123456789).
Ako storniraš ceo račun, ima kraći put — proslediš samo broj računa:
POST /receipt/{invoiceNumber}/refund/fullŠta još postoji
Odeljak „Šta još postoji“| Šta ti treba | Endpoint |
|---|---|
| Ne želiš da čekaš odgovor | POST /receipt/{invoiceType}/{transactionType}/async |
| Više računa odjednom | POST /receipt/{invoiceType}/{transactionType}/bulk |
| Račun u pripremi, izdaješ ga kasnije | POST /receipt/drafts |
| Avansi | POST /receipt/advance/finalize |
| Pregled izdatih računa | GET /archive/receipts |
| Provera da li je porudžbina fiskalizovana | POST /archive/receipts/fiscalization-lookup |
| Slanje računa kupcu na mejl | POST /receipt/send-email |
fiscalization-lookup je najkorisniji kad radiš integraciju. Pošalješ listu svojih brojeva porudžbina i dobiješ nazad koje su fiskalizovane. Time proveravaš da ti se ništa nije izgubilo, bez čuvanja stanja na tvojoj strani.
Ako integraciju piše AI
Odeljak „Ako integraciju piše AI“Postoji uputstvo pisano za jezičke modele — ne za čoveka. Ako integraciju radiš uz Claude, ChatGPT, Cursor ili sličan alat, daj mu ovaj link i dobićeš tačniji kod nego ako model pogađa iz primera:
- api.fiscomm.rs/llms-full.txt — ceo vodič: autentikacija, poreske oznake, idempotencija, avansni lanac, greške i zamke
- api.fiscomm.rs/llms.txt — kraća verzija, za kontekst manjeg obima
- api.fiscomm.rs/openapi.json — mašinski čitljiva OpenAPI specifikacija, sa svim poljima i tipovima
Za TypeScript postoji i SDK: github.com/Fiscomm/fiscomm-sdk-ts.
Otvori nalog i uzmi DEMO ključ.
Ceo tok iznad radi bez bezbednosnog elementa.