Zašto je API integracija neophodna?
Portal eotpremnica.mfin.gov.rs ima web interfejs za ručno kreiranje otpremnica, ali za firme koje šalju više od 5-10 otpremnica dnevno, ručni unos je neodrživ. API integracija omogućava:
- Automatsko kreiranje e-otpremnica iz vašeg ERP/DMS sistema
- Automatski prijem i potvrda prijemnica
- Sinhronizacija statusa — pratite status otpremnica u vašem sistemu
- Eliminacija duplih unosa — podaci idu direktno iz vaše baze
- Smanjenje grešaka — nema ručnog prepisivanja
Arhitektura sistema
Sistem e-otpremnica koristi REST API za komunikaciju sa eksternim sistemima:
- Protokol: HTTPS (TLS 1.2+)
- Format: JSON (zahtevi i odgovori)
- Autentifikacija: Kvalifikovani elektronski sertifikat (mutual TLS) + API ključ
- Dokumentacija: Dostupna na portalu nakon registracije
Koraci za API integraciju
1. Registracija i dobijanje API pristupa
- Registrujte firmu na portalu (ako još niste)
- U podešavanjima izaberite "API pristup"
- Generišite API ključ
- Preuzmite tehničku dokumentaciju (Swagger/OpenAPI specifikacija)
2. Autentifikacija
API koristi dvostruku autentifikaciju:
- Mutual TLS — vaš server mora da prezentuje kvalifikovani sertifikat
- API ključ — šalje se u header-u svakog zahteva
Ovo obezbeđuje da samo ovlašćeni sistemi mogu da kreiraju otpremnice u ime vaše firme.
3. Osnovni API endpointi
| Endpoint | Metoda | Opis |
|---|---|---|
| /api/v1/otpremnice | POST | Kreiranje nove e-otpremnice |
| /api/v1/otpremnice/{id} | GET | Pregled jedne otpremnice |
| /api/v1/otpremnice | GET | Lista otpremnica (sa filterima) |
| /api/v1/prijemnice | POST | Kreiranje e-prijemnice (potvrda prijema) |
| /api/v1/otpremnice/{id}/status | GET | Status otpremnice |
| /api/v1/otpremnice/{id}/pdf | GET | PDF verzija za štampu |
4. Struktura podataka e-otpremnice
Minimalni skup podataka za kreiranje e-otpremnice:
- Pošiljalac — PIB, naziv, adresa, lokacija otpreme
- Primalac — PIB, naziv, adresa prijema
- Prevoznik — PIB, naziv, registracija vozila, ime vozača
- Stavke — opis robe, količina, jedinica mere, tarifa
- Datum otpreme — mora biti pre početka transporta
Integracija sa popularnim ERP sistemima
SAP
SAP korisnici mogu koristiti SAP PI/PO ili SAP Integration Suite za povezivanje sa API-jem. Mapiranje se radi iz SD modula (Shipping/Delivery document) na API format.
Microsoft Dynamics
Dynamics 365 korisnici koriste Power Automate ili custom konektore za integraciju. Podaci se mapiraju iz Sales Order / Transfer Order na API.
Domaći ERP sistemi
Većina domaćih ERP rešenja (Pantheon, Lidder, Bild, 4D) već radi na integraciji ili ima module za e-otpremnice. Proverite sa vašim dobavljačem ERP-a.
Česti problemi pri integraciji
- Sertifikat nije pravilno konfigurisan — najčešći problem. Proverite da li je sertifikat instaliran na serveru, ne samo na radnoj stanici
- Pogrešan format datuma — API očekuje ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
- Nedostatak obaveznih polja — API vraća grešku 400 sa listom polja koja fale
- PIB primaoca ne postoji — primalac mora biti registrovan u sistemu
- Timeout pri velikim pošiljkama — ako imate 100+ stavki, delite na više otpremnica
Webhook notifikacije
Portal podržava webhook notifikacije za praćenje statusa:
- Kad primalac potvrdi prijem → vaš sistem dobija notifikaciju
- Kad primalac prihvati/odbije otpremnicu → notifikacija
- Kad istekne rok za potvrdu → upozorenje
Webhooks eliminišu potrebu za konstantnim polling-om API-ja.
Testiranje integracije
- Koristite DEMO okruženje za sve testove
- Testirajte svaki endpoint pojedinačno (Postman, Insomnia)
- Simulirajte greške — šta se dešava kad API nije dostupan?
- Testirajte sa realnim podacima — ali na DEMO okruženju
- Proverite performance — koliko otpremnica možete da kreirate u minuti?
Zaključak
API integracija je jedini održiv način za firme sa većim obimom otpremnica. Investicija u integraciju se vraća kroz eliminaciju ručnog rada, smanjenje grešaka i brži proces otpreme.
Arhivix ima gotovu integraciju sa portalom e-otpremnica — ne morate da razvijate ništa sami. Povežite vaš ERP sa Arhivix-om, a on komunicira sa portalom za vas.
