đź“– API Dokumentacija

Endpointi:
Metoda Endpoint Opis
POST /invarchive/store Pohrani raÄŤun u arhivu (JSON + base64 XML)
Query parametar: ?forceupdate=true za overwrite postojećeg računa
Incoming raÄŤun (default) - koristi sender:
{
  "data": {
    "id": 5717,
    "name": "419/2/1",
    "sender": {"name": "DobavljaÄŤ d.o.o.", "oib": "92779136888"},
    "issueDate": "2026-01-19",
    "dueDate": "2026-02-19",
    "payableAmount": 382.00,
    "currency": "EUR",
    "status": "DELIVERED",
    "paymentStatus": null,
    "direction": "incoming"
  },
  "xml": "PD94bWwgdmVyc2lvbj0iMS4wIj8+Li4uIChiYXNlNjQp"
}
Outgoing raÄŤun - koristi receiver:
{
  "data": {
    "id": 999188,
    "name": "R-2026-TEST-118",
    "receiver": {"name": "Kupac d.o.o.", "oib": "12345678901"},
    "issueDate": "2026-01-29",
    "dueDate": "2026-02-28",
    "payableAmount": 1250.50,
    "currency": "EUR",
    "status": "SENT",
    "paymentStatus": null,
    "direction": "outgoing"
  },
  "xml": "PD94bWwgdmVyc2lvbj0iMS4wIj8+Li4uIChiYXNlNjQp"
}
Napomena: direction field automatski određuje da li se koristi sender (incoming) ili receiver (outgoing). Default je incoming.
⚠️ XML mora biti Base64 enkodiran string u "xml" fieldu.
GET /invarchive/search PretraĹľi raÄŤune po razliÄŤitim kriterijima
Parametri: name, sender, senderOib, dateFrom, dateTo, status, direction, limit, offset
GET /invarchive/get/{id} Dohvati kompletan raÄŤun (metadata + XML sadrĹľaj)
GET /invarchive/getxml/{id} Dohvati samo XML sadrĹľaj raÄŤuna (Content-Type: application/xml)
GET /invarchive/getids Dohvati listu ID-ova raÄŤuna za period
Default: prvi dan tekućeg mjeseca → zadnji dan tekućeg mjeseca
Parametri: dateFrom, dateTo (YYYY-MM-DD)
Response: [435973, 435974, 435975]
GET /invarchive/getnames Dohvati listu raÄŤuna sa osnovnim podacima (id, name, issueDate)
Default: prvi dan tekućeg mjeseca → zadnji dan tekućeg mjeseca
Parametri: dateFrom, dateTo (YYYY-MM-DD)
Response: [{"id": 435973, "name": "R-2026-001", "issueDate": "2026-01-29"}]
DELETE /invarchive/delete/{id} Obriši pojedinačni račun (XML fajl + zapis u bazi)
Podržava i POST metodu. Fajl se briše prvo, zatim zapis iz baze.
POST /invarchive/delete Masovno brisanje selektiranih raÄŤuna
Koristi se za DataTables multi-select delete
Response: status za svaki ID (deleted/notFound/failed)
Body primjer:
{"ids": [123, 456, 789]}
GET /invarchive/verify Provjera integriteta arhive
Vraća report o "broken records" (zapisi bez XML fajlova)
Response: lista raÄŤuna koji imaju zapis u bazi ali nemaju XML fajl
POST /invarchive/cleanup Automatsko brisanje orphan zapisa
Briše SVE zapise čiji XML fajlovi ne postoje
Koristi se nakon preseljenja fajlova u drugu arhivu
POST / PUT /invarchive/update/{id} GeneriÄŤki update bilo kojih polja
Parcijalno aĹľuriranje zapisa bez potrebe za XML-om
Path primjer: /invarchive/update/5717
Body primjer:
{"paymentStatus": "PLACENO", "lastStatus": "DELIVERED"}
Dozvoljeni fieldi: name, sender, senderOib, issueDate, dueDate, payableAmount, currency, lastStatus, paymentStatus, direction
GET /invarchive/stats Statistika baze (ukupno računa, veličina, top 10 pošiljatelja)
GET /invarchive/ping Health check (provjera konekcije sa bazom)
🔍 Use Case primjeri:
đź’ľ Scenario 1: Pohrana novog raÄŤuna
1. Kreiraj JSON Pripremi data objekt + Base64 XML
2. POST /store Pohrani raÄŤun u arhivu
3. Provjeri response Dobij xmlPath i potvrdu pohrane

🔎 Scenario 2: Pretraga i brisanje
1. GET /search Pronađi račune po kriterijima
2. Selektiraj raÄŤune Korisnik selektira retke u DataTables
3. POST /delete Pošalji array ID-ova za brisanje
4. Provjeri response Vidi koji su obrisani, koji failed

🧹 Scenario 3: Nakon ručnog preseljenja arhive
1. GET /verify Provjeri integritet prije preseljenja
2. Preseli fajlove Kopiraj XML fajlove u drugu arhivu
3. GET /verify Provjeri koji zapisi su ostali orphan
4. POST /cleanup Obriši orphan zapise iz baze

🔄 Scenario 4: Ažuriranje statusa plaćanja
1. Zaprimi obavijest Račun je plaćen (webhook, manual check, itd.)
2. POST /update/5717 AĹľuriraj samo paymentStatus polje:
{"paymentStatus": "PLACENO"}
3. Provjeri response Potvrda koja polja su aĹľurirana
Konfiguracija (f2archive.ini):
XMLSTORAGEPATH=./F2INVOICES
DBPATH=./data/f2archive
DBPASSWORD=
LOGLEVEL=ERROR
ENABLED=true
DEFAULTLIMIT=100
MAXLIMIT=1000
Struktura XML pohranjivanja:
F2INVOICES/
  ├── 1_2026/          (siječanj 2026)
  │   ├── R-2026-001.xml
  │   ├── R-2026-002.xml
  │   └── ...
  ├── 2_2026/          (veljača 2026)
  │   └── ...
  └── 12_2025/         (prosinac 2025)
      └── ...
đź’ľ Preseljenje arhive na drugi disk

Arhiva se moĹľe bezbolno preseliti bez izmjene baze!

U bazi se pohranjuje samo relativna putanja (npr. 1_2026/R-2026-001.xml), dok se base folder (XMLSTORAGEPATH) ÄŤita iz konfiguracije svaki put.

Koraci za preseljenje:
  1. Zaustavi HrFiskalizator
  2. Kopiraj cijeli folder na novu lokaciju:
    xcopy /E /I F2INVOICES Z:\NAS_ARCHIVE\F2INVOICES
  3. AĹľuriraj u posvkama plugina ili f2archive.ini:
    XMLSTORAGEPATH=Z:\NAS_ARCHIVE\F2INVOICES
  4. Pokreni HrFiskalizator
  5. Testiraj: GET /invarchive/verify (sve mora biti OK)
  6. Obriši stari folder (nakon što potvrdiš da sve radi)

âś… Baza ostaje ista - ni jedan UPDATE nije potreban!

đź”— Korisni linkovi