SEF e-fakture preko API-ja: integracija sa ERP-om

Ja sam Lazar Milićević, AI inženjer i osnivač BizFlowAI. Deset godina gradim produkcione integracije koje moraju da rade 365 dana godišnje, bez toga da neko svako jutro proverava da li je servis živ. Jedan od proizvoda koji držim je fakturko.io, koji radi u SEF domenu, pa svakodnevno vidim šta puca kad se e-faktura vezuje na interni sistem firme.

Ovaj tekst nije prodaja. Ako vaša firma bira izvođača za povezivanje ERP-a sa SEF-om, hoću da posle ovog teksta znate šta tačno tražite, koja pitanja da postavite i gde se najčešće ćuti o problemima koji će vas kasnije koštati.

Šta "integracija SEF-a preko API-ja" konkretno obuhvata

Kratak odgovor: SEF integracija je dvosmerni kanal između vašeg ERP-a (ili internog programa za fakturisanje) i Sistema elektronskih faktura koji drži Ministarstvo finansija. Nije jedan API poziv, nego skup procesa koji zajedno moraju biti pouzdani.

Ono što se u praksi mora pokriti:

• Slanje izlaznih faktura. ERP generiše fakturu, servis je konvertuje u UBL 2.1 XML, potpisuje i šalje preko SEF API-ja uz autentikaciju API ključem.
• Prijem ulaznih faktura. Redovan polling ili webhook koji povlači fakture od dobavljača, parsira XML i ubacuje ih u ERP kao ulazni dokument, ne kao PDF prilog.
• Statusi dokumenta. Poslato, prihvaćeno, odbijeno, storno. Svaki od tih statusa mora da se vrati u ERP i vidi na kartici fakture. Ovo je najčešće mesto gde integracije "rade", a zapravo ne rade.
• CIR i evidencija PDV-a. U zavisnosti od tipa obveznika i tipa dokumenta, potrebna je pojedinačna ili zbirna evidencija.
• Retry logika. SEF ume da vrati 500 ili timeout. Bez retry sa backoff-om, fakture tiho padnu.
• Arhiviranje XML-a. Original XML koji je otišao na SEF mora da se čuva, ne samo PDF koji vidi računovođa.

Razlika između "demo poziva na SEF" i produkcione integracije je ogromna. Demo je čovek dan posla. Produkciona integracija koja preživi promenu API-ja, pad mreže, restart servera i špic kraja meseca kada firma pošalje 800 faktura odjednom, to je nešto sasvim drugo. Većina firmi ovu razliku shvati tek kad prvi put nešto pukne.

Kako izgleda ozbiljan proces saradnje

Ako izvođač na prvom sastanku već daje fiksnu cenu bez da je video ERP, to je crvena zastava. Redosled koji radi u praksi:

1. Analiza postojećeg sistema. Koji ERP ili program firma koristi (SAP, Pantheon, Kalkulo, Minimax, Datalab, ili nešto custom napravljeno). Ima li API, ima li bazu na koju se mogu okačiti, ili se sve gura preko fajlova.
2. Mapiranje polja. Šifarnik proizvoda, jedinice mere, PDV stope, valute, tipovi dokumenata. Ovaj korak firme podcenjuju. Ako u ERP-u imate 12 različitih PDV stavki na jednom istom proizvodu, mapiranje traje duže od samog razvoja.
3. Test na demo SEF okruženju. SEF ima demo API. Cela integracija se prvo dokazuje tamo, sa realnim primerima faktura iz vaše firme, ne sa "primerom iz dokumentacije".
4. Migracija na produkciju. Postavljanje ključa, prebacivanje endpointa, kontrolisano paralelno slanje prvih dana.
5. Monitoring. Ovaj korak je tačka koja se najčešće preskoči. O njoj sledi cela sledeća sekcija.

Ono što je bitno da zapamtite: bez faze mapiranja i bez monitoringa, ne dobijate integraciju, dobijate skript koji radi sve dok ne padne.

Zašto monitoring pratite po statusu iz baze, ne po logu poziva

Ovde ide priča koju stalno pričam klijentima jer najbolje opisuje o čemu govorim.

Prošle godine sam radio na Supabase projektu gde je Auth Hook trebalo da sinhronizuje korisnike sa internom bazom čim se registruju. Napravio sam dashboard koji je pratio "success rate" hook-a. Sedamnaest dana metrika je pokazivala 99.4% uspeh. Sve zeleno. Osećaj je bio dobar.

Osamnaestog dana klijent zove i pita zašto polovina korisnika ne dobija welcome email. Uđem u bazu, brojim redove. Umesto 2100 novih korisnika za tih 17 dana, u tabeli je bilo 1080. Otprilike pola. Šta se desilo? Hook se zvao samo na status SIGNED_IN, a događaji tipa SIGN_UP_FAILED_THEN_RESET nikad nisu bili u sync listi. Sistem je iskreno prijavljivao 99.4% uspeha, jer je bio uspešan na onome što je gledao. Problem je bio što nije gledao pola levka.

Ista greška se dešava sa SEF integracijom.

Firma pošalje fakturu, API vrati 200 OK, u logu piše "faktura poslata". Sve zeleno. Nedelju dana kasnije kupac zove i pita zašto još nije dobio fakturu. Uđete u SEF portal, faktura je u statusu Odbijena jer je PIB kupca imao razmak, ili je jedinica mere pogrešna, ili nedostaje šifra iz CPV-a. Status "Odbijena" nikad se nije vratio u ERP jer niko nije napravio kod koji pola sata kasnije proverava status, ili webhook nije bio pravilno registrovan.

Zato monitoring mora da bude po stanju u bazi, ne po logu API poziva:

• Broj faktura u statusu "Poslato" starijem od 2 sata bez konačnog statusa: alarm.
• Broj faktura u statusu "Odbijena" u poslednjih 24h: alarm.
• Broj ulaznih faktura koje čekaju parsing više od 30 min: alarm.

Log poziva vam kaže da je vaš server živ. Status iz baze vam kaže da posao stvarno teče. To su dve različite stvari, i firme to razlikuju tek kad ih ujede.

Od čega zavise rok i cena

Neću vam dati brojeve u dinarima ili danima, jer bi bilo neozbiljno bez da vidim vaš sistem. Ali evo faktora koji realno određuju obim posla:

Ako neko daje fiksnu ponudu za dve nedelje bez da je pogledao vaš sistem, znate šta kupujete: rizik.

7 pitanja koja morate postaviti izvođaču

Ovo su pitanja koja bih ja postavio da sam na vašem mestu. Odgovori vam mnogo govore.

1. Ko drži API ključ za SEF i gde je sačuvan? Ispravan odgovor: u secret manageru (AWS Secrets Manager, HashiCorp Vault, environment varijable sa restrikcijom pristupa), ne u kodu i ne u konfiguracionom fajlu na deljenom disku.
2. Šta se dešava kad SEF vrati 500 ili timeout? Ispravan odgovor uključuje retry sa eksponencijalnim backoff-om, red čekanja (queue), i alarm ako pokušaj traje duže od X vremena.
3. Da li integracija čeka status "Prihvaćena" pre nego što fakturu obeleži kao završenu? Ako ne čeka, imate isti problem kao ja sa Supabase hook-om.
4. Gde se čuvaju originalni XML fajlovi i koliko dugo? Zakonski minimum je 10 godina za poresku dokumentaciju. Ne "on zna gde".
5. Ko dobija alarm kad integracija padne, i kako? Email nije alarm. Slack, SMS, PagerDuty, pozivi, to su alarmi. I ko je odgovoran da reaguje.
6. Ko održava kad SEF promeni verziju API-ja? SEF povremeno menja specifikaciju. Da li imate ugovor za održavanje, ili plaćate posebno svaki put.
7. Postoji li SLA i šta pokriva? Vreme odziva na kvar, vreme za popravku, radni sati podrške. Bez SLA, u trenutku kada vam integracija padne 25. u mesecu, nemate na koga da se pozovete.

Ako izvođač nema odgovore na bar 5 ovih pitanja, ne kupujete integraciju, kupujete obećanje.

Česte greške koje viđam

Oslanjanje na Excel export/import umesto API-ja. Ovo se prodaje kao "brzo rešenje" i u prva 2 meseca izgleda kao da radi. Onda neko zaboravi da uveze fajl, ili verzija Excel-a promeni format datuma, ili računovođa ide na odmor. API integracija sa retry logikom nema te probleme.

Nema alarma na neuspele fakture. Sistem šalje fakture, ali niko ne gleda status "Odbijena". Firma sazna za problem od kupca. Do tad je već prošao rok za korekciju.

Čuvanje API ključa u kodu ili u repozitorijumu. Video sam nekoliko puta ključ zakucan u config.php koji je u Git repo-u sa main branchom javno dostupnim. Ako neko dobije taj ključ, može da šalje fakture u vaše ime.

Bez arhive XML-a. PDF nije original. SEF traži XML kao pravno validan dokument. Ako ga niste sačuvali, u slučaju spora nemate čime da dokažete šta ste poslali.

Jedan cron job koji sve radi. "Svake noći se povuku ulazne fakture." U redu, ali šta ako je jedna faktura hitna? Šta ako cron ne krene? Ozbiljan setup ima queue, više workera, i monitoring stanja reda.

Šta bih ja uradio

Ako danas krećete u ovu priču, konkretan redosled:

1. Ne birajte izvođača na osnovu cene, birajte na osnovu odgovora na 7 pitanja iznad. Razlika u ceni od 20-30% između ozbiljnog i neozbiljnog izvođača se višestruko vrati čim prvi put nešto pukne.
2. Insistirajte na demo okruženju pre produkcije. Barem dve nedelje paralelnog rada, gde se fakture šalju i na SEF demo i na staru rutinu, pa se rezultati porede.
3. Tražite dashboard koji vi možete da otvorite. Ne "izveštaj koji vam pošaljemo mesečno". Nešto što vaš računovođa može da pogleda u 9 ujutru i vidi da li su sve jučerašnje fakture prošle.
4. Ugovor o održavanju je deo integracije, ne poseban proizvod. Firma koja vam integraciju napravi i ode, nije partner.

Kako izgleda prvi razgovor

Ako želite da popričamo o vašem konkretnom slučaju, prvi razgovor je 30 minuta, bez obaveza. Prođemo kroz vaš ERP, kroz to šta tačno radite sa fakturama sada, i realno procenim šta je posao. Ako niste za mene ili ja nisam za vas, reći ću vam iskreno.

Kontakt ide preko lazar-milicevic.com/#contact ili direktno preko bizflowai.io. Ne prodajem paket, prodajem rešenje koje ćete i za dve godine hteti da imate.