📧 HrFiskalizator - MER Plugin API Dokumentacija

📋 Pregled

MER (Moj-eRačun) plugin omogućava slanje i primanje elektroničkih računa putem moj-eracun.hr posredničkog servisa. Plugin podržava automatsku autentifikaciju i potpunu integraciju s MER API-jem.

ℹ️ Važno: Plugin prosljeđuje sve zahtjeve prema moj-eracun.hr API-ju s automatskim dodavanjem autentifikacijskih podataka. Plugin vraća HTTP 200 OK za uspješne proxy zahtjeve (originalni status MER servera je unutar response-a), ili HTTP 500 za proxy greške (timeout, connection error).

Osnovne Značajke

Automatska autentifikacija - Username, Password, CompanyId, CompanyBu, SoftwareId
3 Response formata - RAW (JSON), INI (sekcijski), SIMPLE (key=value)
RETURNONLY mod - Debug mod bez slanja prema serveru
URL parametar override - ?response=INI/SIMPLE/RAW

🔧 Konfiguracija Plugin-a

Postavke u HrFiskalizatoru

Konfiguraciju podešavate kroz HrFiskalizator sučelje (POSTAVKE MER):

Parametar	Vrijednost	Opis
MODE	`TESTNI` `PRODUKCIJSKI` `RETURNONLY`	Okruženje (demo/produkcija/debug)
USERNAME	Korisničko ime	MER korisničko ime (različito za test/prod)
PASSWORD	Lozinka	MER lozinka (različito za test/prod)
COMPANYID	OIB	OIB tvrtke (različito za test/prod)
COMPANYBU	Poslovnica	Oznaka poslovnice (opcionalno)
TIMEOUT	`30000` ms	Vrijeme čekanja odgovora
RESPONSEFORMAT	`RAW` / `INI` / `SIMPLE`	Defaultni format odgovora

Endpointi

TESTNI: https://demo.moj-eracun.hr
PRODUKCIJSKI: https://www.moj-eracun.hr

⚠️ RETURNONLY mod: U ovom modu plugin samo formatira zahtjev i prikazuje ga, ali ga ne šalje prema serveru. Koristi se za debugging.

🏥 1. Provjera Dostupnosti Servisa (Ping)

POST /mer/ping

Provjerava dostupnost MER API servisa.

� AJAX Primjer

$.ajax({
    url: 'mer/ping',
    method: 'GET'
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP
mer/ping

application/json; charset=utf-8

📥 Response OK (RAW format)

{
  "Status": "ok",
  "Message": "Service is up"
}

📥 Response OK (INI format)

OK

[RESPONSE]
status=200

status=ok
message=Service is up

📤 2. Slanje eRačuna

POST /mer/send

Šalje UBL 2.1 Invoice ili CreditNote prema MER servisu.

Request Body

Parametar	Tip	Status	Opis
`File`	string	OBAVEZNO	UBL 2.1 XML kao string

ℹ️ Napomena: Autentifikacijski podaci (Username, Password, CompanyId, CompanyBu) se automatski dodaju u request.

� AJAX Primjer

$.ajax({
    url: 'mer/send',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        File: xmlString
    })
}).done(function(response) {
    console.log(response);
});

📄 FILE Request (POST JSON)

HTTP:NOENCODEPOST
mer/send
{"File":"<?xml version=\"1.0\"?>..."}
application/json; charset=utf-8

📄 FILE Request (POST FILE)

HTTP:NOENCODEPOST
mer/send
FILE=invoice_send.json
application/json; charset=utf-8

📥 Response OK

{
  "ElectronicId": 394167,
  "DocumentNr": "20156256",
  "DocumentTypeId": 1,
  "DocumentTypeName": "Račun",
  "StatusId": 20,
  "StatusName": "Obrađen",
  "RecipientBusinessNumber": "99999999927",
  "RecipientBusinessUnit": "",
  "RecipientBusinessName": "Test Klising d.o.o.",
  "Created": "2016-04-18T08:23:08.5879877+02:00",
  "Sent": "2016-04-18T08:23:09.6730491+02:00",
  "Modified": "2016-04-18T08:23:09.6840519+02:00",
  "Delivered": null
}

📤 3. Slanje Raw XML (Iz Editora)

POST /mer/sendxmlinvoice

Šalje čist XML dokument direktno iz editora. Automatski se wrapuje u JSON format sa auth podacima.

⚠️ Važno: XML mora biti URL enkodiran (encodeURIComponent()) prije slanja zbog base64 podataka i specijalnih karaktera.

� AJAX Primjer

var xmlData = $('#editor').val();

$.ajax({
    url: 'mer/sendxmlinvoice',
    method: 'POST',
    contentType: 'text/plain; charset=utf-8',
    data: encodeURIComponent(xmlData)
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP:NOENCODEPOST
mer/sendxmlinvoice
FILE=invoice_raw.xml
text/plain; charset=utf-8

Napomena: XML datoteka se automatski URL enkodira prije slanja.

📥 Response OK

Kao u prethodnom primjeru

📋 4. Popis Poslanih Dokumenata (Query Outbox)

POST /mer/queryOutbox

Dohvaća listu poslanih dokumenata u određenom datumskom rasponu.
ℹ️ Prihvača i sve druge parametre iz MER apija.

Request Body

Parametar	Tip	Status	Opis
`DateFrom`	string	OBAVEZNO	Datum od (format: YYYY-MM-DD)
`DateTo`	string	OBAVEZNO	Datum do (format: YYYY-MM-DD)

� AJAX Primjer

$.ajax({
    url: 'mer/queryOutbox',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        DateFrom: '2026-01-01',
        DateTo: '2026-01-31'
    })
}).done(function(response) {
    console.log(response);
});

📄 FILE Request (POST JSON)

HTTP:NOENCODEPOST
mer/queryOutbox
{"DateFrom":"2026-01-01","DateTo":"2026-01-31"}
application/json; charset=utf-8

📄 FILE Request (POST FILE)

HTTP:NOENCODEPOST
mer/queryOutbox
FILE=query_dates.json
application/json; charset=utf-8

📨 5. Popis Primljenih Dokumenata (Query Inbox)

POST /mer/queryInbox

Dohvaća listu primljenih dokumenata u određenom datumskom rasponu.
ℹ️ Prihvača i sve druge parametre iz MER apija.

Request Body

Parametar	Tip	Status	Opis
`DateFrom`	string	OBAVEZNO	Datum od (format: YYYY-MM-DD)
`DateTo`	string	OBAVEZNO	Datum do (format: YYYY-MM-DD)

� AJAX Primjer

$.ajax({
    url: 'mer/queryInbox',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        DateFrom: '2026-01-01',
        DateTo: '2026-01-31'
    })
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP:NOENCODEPOST
mer/queryInbox
{"DateFrom":"2026-01-01","DateTo":"2026-01-31"}
application/json; charset=utf-8

📄 6. Primanje Dokumenta (Receive)

POST /mer/receive?ElectronicId={id}

Dohvaća puni XML sadržaj dokumenta prema ElectronicId.

URL Parametri

Parametar	Tip	Status	Opis
`ElectronicId`	string	OBAVEZNO	Jedinstveni identifikator dokumenta

ℹ️ Napomena: Iako se ElectronicId šalje kao query parametar, plugin ga prebacuje u JSON body prije slanja na MER server (MER API zahtijeva POST body).

� AJAX Primjer

$.ajax({
    url: 'mer/receive?ElectronicId=' + electronicId,
    method: 'POST',
    contentType: 'application/json',
    data: '{}'
}).done(function(xmlDocument) {
    console.log('XML primljen:', xmlDocument);
    // Parsiraj XML ili prikaži u editoru
});

📄 FILE Request

HTTP
mer/receive?ElectronicId=3227383
{}
application/json; charset=utf-8

Napomena: Prazan JSON {} je potreban za POST metodu.

📥 Response OK (XML Document)

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>1/2026</cbc:ID>
  ...
</Invoice>

🔍 7. Status Poslanog Dokumenta (Status Outbox)

POST /mer/statusOutbox

Provjerava status fiskalizacije poslanog dokumenta.
ℹ️ Prihvaća i sve druge parametre iz MER apija.

Request Body

Parametar	Tip	Status	Opis
`DocumentId`	integer	OBAVEZNO	ID dokumenta iz MER baze

� AJAX Primjer

$.ajax({
    url: 'mer/statusOutbox',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        DocumentId: 12345678
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP:NOENCODEPOST
mer/statusOutbox
{"DocumentId":12345678}
application/json; charset=utf-8

🔍 8. Status Primljenog Dokumenta (Status Inbox)
ℹ️ Prihvaća i sve druge parametre iz MER apija.

POST /mer/statusInbox

Provjerava status fiskalizacije primljenog dokumenta.

Request Body

Parametar	Tip	Status	Opis
`DocumentId`	integer	OBAVEZNO	ID dokumenta iz MER baze

💰 9. Označi Kao Plaćeno (Mark Paid)

POST /mer/markPaid

Označava dokument kao plaćen.

Request Body

Parametar	Tip	Status	Opis
`DocumentId`	integer	OBAVEZNO	ID dokumenta
`PaymentDate`	string	OPCIONO	Datum uplate (YYYY-MM-DD)

� AJAX Primjer

$.ajax({
    url: 'mer/markPaid',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
      "electronicId": 101,
      "paymentDate": "2024-06-01T00:00:00",
       "paymentAmount": 500.00,
       "paymentMethod": "T"
}
    })
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP:NOENCODEPOST
mer/markPaid
{ "electronicId": 101, "paymentDate": "2024-06-01T00:00:00", "paymentAmount": 500.00, "paymentMethod": "T" }
    
application/json; charset=utf-8

❌ 10. Odbijanje Dokumenta (Reject)

POST /mer/reject

Odbija primljeni dokument s obrazloženjem.

Request Body

Parametar	Tip	Status	Opis
`DocumentId`	integer	OBAVEZNO	ID dokumenta
`ReasonCode`	string	OBAVEZNO	Šifra razloga odbijanja
`ReasonText`	string	OBAVEZNO	Tekstualni opis razloga

AJAX Primjer

$.ajax({
    url: 'mer/reject',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
       "electronicId": 201,
       "rejectionDate": "2024-06-01T10:05:00",
       "rejectionReasonType": "N",
       "rejectionReasonDescription": "Data mismatch without tax impact"
    })
}).done(function(response) {
    console.log(response);
});

📄 FILE Request

HTTP:NOENCODEPOST
mer/reject
FILE=reject_request.json
application/json; charset=utf-8

Sadržaj reject_request.json:

{
  "electronicId": 201,
  "rejectionDate": "2024-06-01T10:05:00",
  "rejectionReasonType": "N",
  "rejectionReasonDescription": "Data mismatch without tax impact"
}

📊 Response Formati

MER plugin podržava 3 formata odgovora:

1. RAW Format (Default)

Čisti JSON odgovor kako stigne s MER servera.

Primjer

{
  "DocumentId": 12345678,
  "ElectronicId": "3227383",
  "ProcessStatus": "SENT"
}

2. INI Format

Strukturiran format sa sekcijama. Aktivira se: RESPONSEFORMAT=INI ili ?response=INI

Primjer

OK

[RESPONSE]
status=200

DocumentId=12345678
ElectronicId=3227383
ProcessStatus=SENT

3. SIMPLE Format

Flat format sa dot-notacijom. Aktivira se: RESPONSEFORMAT=SIMPLE ili ?response=SIMPLE

Primjer

OK
status=200
DocumentId=12345678
ElectronicId=3227383
ProcessStatus=SENT

ℹ️ URL Override: Dodajte ?response=INI, ?response=SIMPLE ili ?response=RAW na bilo koji endpoint za privremenu promjenu formata.

⚠️ Rukovanje Greškama

Plugin uvijek vraća HTTP 200, ali greške se prikazuju u response body-ju:

Proxy Greška

{
  "code": "PROXY_ERROR",
  "message": "Connection timeout after 30000ms"
}

MER API Greška

{
  "ErrorCode": "INVALID_DOCUMENT",
  "ErrorMessage": "Document validation failed",
  "Details": ["Missing required field: BuyerID"]
}

RETURNONLY Mod

U RETURNONLY modu plugin vraća formatirani request bez slanja:

METHOD:
POST

URL:
https://demo.moj-eracun.hr/apis/v2/send

HEADERS:
Content-Type: application/json; charset=utf-8

BODY:
{
  "File": "<?xml...>",
  "Username": "828455",
  "Password": "mojPAssword",
  "CompanyId": "22345729108"
}

📌 Dodatne Napomene

Automatska Autentifikacija: Svi parametri (Username, Password, itd.) se automatski dodaju u svaki request
POST Metoda: MER API zahtijeva POST za sve operacije (čak i za receive)
ElectronicId Tip: Mora biti string, ne integer
URL Encoding: XML dokumenti moraju biti URL enkodirani kod slanja preko /sendxmlinvoice
Timeout: Default 30 sekundi, konfigurabilan u postavkama
Response Format: Može se promijeniti per-request kroz URL parametar ?response=

✅ Best Practice: Koristite RETURNONLY mod za testiranje strukture zahtjeva prije slanja na pravi server.

📚 Kompletan API Reference

ℹ️ Svi originalni pozivi MER servera prihvaćaju POST vrijednosti kao u naputku MER apija V2.

Endpoint	Metoda	Opis
`/mer/getmode`	GET	Vraća trenutni mod (TESTNI/PRODUKCIJSKI/RETURNONLY)
`/mer/ping`	POST	Provjera dostupnosti servisa
`/mer/send`	POST	Slanje dokumenta (JSON wrapper)
`/mer/sendxmlinvoice`	POST	Slanje raw XML dokumenta
`/mer/receive`	POST	Primanje dokumenta po ElectronicId
`/mer/queryOutbox`	POST	Lista poslanih dokumenata
`/mer/queryInbox`	POST	Lista primljenih dokumenata
`/mer/statusOutbox`	POST	Status poslanih dokumenata
`/mer/statusInbox`	POST	Status primljenih dokumenata
`/mer/markPaid`	POST	Označi dokument kao plaćen
`/mer/reject`	POST	Odbij dokument
`/mer/eReporting`	POST	eIzvještavanje prema PU
`/mer/UpdateDokumentProcessStatus`	POST	Ažuriranje statusa dokumenta
`/mer/checkIdentifier`	POST	Provjera MPS identifikatora
`/mer/notifyimport/{DocumentId}`	POST	Notifikacija o import dokumentu

📧 HrFiskalizator - MER Plugin API Dokumentacija

📋 Pregled

Osnovne Značajke

🔧 Konfiguracija Plugin-a

Postavke u HrFiskalizatoru

Endpointi

🏥 1. Provjera Dostupnosti Servisa (Ping)

📤 2. Slanje eRačuna

Request Body

📤 3. Slanje Raw XML (Iz Editora)

📋 4. Popis Poslanih Dokumenata (Query Outbox)

Request Body

📨 5. Popis Primljenih Dokumenata (Query Inbox)

Request Body

📄 6. Primanje Dokumenta (Receive)

URL Parametri

🔍 7. Status Poslanog Dokumenta (Status Outbox)

Request Body

🔍 8. Status Primljenog Dokumenta (Status Inbox) ℹ️ Prihvaća i sve druge parametre iz MER apija.

Request Body

💰 9. Označi Kao Plaćeno (Mark Paid)

Request Body

❌ 10. Odbijanje Dokumenta (Reject)

Request Body

📊 Response Formati

1. RAW Format (Default)

2. INI Format

3. SIMPLE Format

⚠️ Rukovanje Greškama

Proxy Greška

MER API Greška

RETURNONLY Mod

📌 Dodatne Napomene

📚 Kompletan API Reference

🔍 8. Status Primljenog Dokumenta (Status Inbox)
ℹ️ Prihvaća i sve druge parametre iz MER apija.