Fiskalizacija2 Node.js Library

Node.js library za fiskalizaciju 2.0 omogućava jednostavno slanje zahtjeva za evidenciju eRačuna i eIzvještavanje.

B2C fiskalizacija, odnosno fiskalizacija u krajnjoj potrošnji, trenutno nije podržana

Instalacija

npm i fiskalizacija2

Korištenje

Library pruža klasu FiskalizacijaClient koja prima objekt konfiguracije:

{
    service: string, // URL servisa za fiskalizaciju
    privateKey: string | Buffer, // Privatni ključ za potpis poruke u PEM formatu
    publicCert: string | Buffer, // Javni certifikat u PEM formatu
    ca?: string | Buffer, // Opcionalni PEM CA bundle za validaciju SSL/TLS veze
                          // default: FINA ROOT CA, RDC 2020, RDC 2025
                          // Eksplicitno postaviti na undefined za korištenje sistemskog truststore-a
    timeout?: number, // Opcionalni timeout u milisekundama (default: 30000)
}

Metode za slanje zahtjeva su:

• evidentirajERacun(IEvidentirajERacunZahtjev)
• evidentirajNaplatu(IEvidentirajNaplatu)
• evidentirajOdbijanje(IEvidentirajOdbijanje)
• evidentirajIsporukuZaKojuNijeIzdanERacun(IEvidentirajIsporukuZaKojuNijeIzdanERacun)

Sve metode vraćaju FiskalizacijaResult objekt koji sadrži:

interface FiskalizacijaResult<Z, O> {
    success: boolean;                   // Uspjeh operacije
    error?: IErrorWithMessage;          // Greška ako postoji
    httpStatusCode?: number;            // HTTP status kod
    soapReqRaw?: string;                // Sirovi SOAP zahtjev
    reqObject?: Z;                      // Objekt zahtjeva
    soapResRaw?: string;                // Sirovi SOAP odgovor
    soapResSignatureValid?: boolean;    // Valjanost potpisa odgovora
    resObject?: O;                      // Objekt odgovora, npr. IEvidentirajERacunOdgovor
    resErrors?: IErrorWithMessage[];    // Greške u validaciji odgovora regexom (ne prekidaju obradu i ne utječu na success)
}

Kreiranje zahtjeva

Sučelja za zahtjeve su:

• IEvidentirajERacunZahtjev
• IEvidentirajIsporukuZaKojuNijeIzdanERacunZahtjev
• IEvidentirajNaplatuZahtjev
• IEvidentirajOdbijanjeZahtjev

Moguće generiranje zahtjeva koristeći pomoćne metode:

• getEvidentirajERacunZahtjev(vrsta: "I" | "U", eracun: IERacun | IERacun[])
• getEvidentirajIsporukuZaKojuNijeIzdanERacunZahtjev(racun: IRacun | IRacun[])
• getEvidentirajNaplatuZahtjev(naplata: INaplata | INaplata[])
• getEvidentirajOdbijanjeZahtjev(odbijanje: IOdbijanje | IOdbijanje[])

Objekti koji zadovoljavaju sučelja IERacun odnosno IRacun mogu se generirati iz UBL dokumenata Invoice ili CreditNote:

• getERacunFromUbl(doc: string | Buffer | XmlDocument | XmlElement): IERacun
• getRacunFromUbl(doc: string | Buffer | XmlDocument | XmlElement): IRacun

Funkcije prihvaćaju XML kao string, Buffer, ili već parsirane XmlDocument/XmlElement objekte iz libxml2-wasm biblioteke. Automatski prepoznaju i obrađuju StandardBusinessDocument (SBD) omot oko UBL dokumenta.

Primjeri

FiskalizacijaClient

const client = new FiskalizacijaClient({
    service: FiskalizacijaServiceURL.test, // ili FiskalizacijaServiceURL.prod
    privateKey: fs.readFileSync('path/to/privateKey.pem'),
    publicCert: fs.readFileSync('path/to/publicCert.pem'),
})

EvidentirajERacun

const ublDocument = '<Invoice xmlns="...">....</Invoice>'; // UBL XML string ili Buffer
const eRacun = getERacunFromUbl(ublDocument);
const zahtjev = getEvidentirajERacunZahtjev('I', eRacun);
const result = await client.evidentirajERacun(zahtjev);
if (result.success) {
    console.log("eRačun uspješno evidentiran:", result.resObject);
} else {
    console.error("Greška pri evidentiranju eRačuna:", result.error);
}

EvidentirajIsporukuZaKojuNijeIzdanERacun

const ublDocument = '<Invoice xmlns="...">....</Invoice>'; // UBL XML string ili Buffer
const racun = getRacunFromUbl(ublDocument);
const zahtjev = getEvidentirajIsporukuZaKojuNijeIzdanERacunZahtjev(racun);
const result = await client.evidentirajIsporukuZaKojuNijeIzdanERacun(zahtjev);
if (result.success) {
    console.log("Isporuka uspješno evidentirana:", result.resObject);
} else {
    console.error("Greška pri evidentiranju isporuke:", result.error);
}

EvidentirajNaplatu

const naplata: INaplata = {
    // Broj dokumenta eRačuna, dio identifikatora eRačuna (BT-1 iz UBL 2.1)
    brojDokumenta: "RAC-2025-0001",
    // Datum izdavanja eRačuna, dio identifikatora eRačuna (BT-2 iz UBL 2.1)
    datumIzdavanja: "2025-01-01",
    // OIB ili porezni broj izdavatelja, dio identifikatora eRačuna (BT-31 iz UBL 2.1)
    oibPorezniBrojIzdavatelja: "00000000001",
    // OIB ili porezni broj primatelja
    oibPorezniBrojPrimatelja: "11111111119",
    // Datum naplate eRačuna
    datumNaplate: "2025-01-15",
    // Iznos koji je naplaćen
    naplaceniIznos: 100.00,
    /**
     * Šifra načina plaćanja
     * T - transakcijski račun
     * O - obračunsko plaćanje
     * Z - ostalo
     */
    nacinPlacanja: "T"
};
const zahtjev = getEvidentirajNaplatuZahtjev(naplata);
const result = await client.evidentirajNaplatu(zahtjev);
if (result.success) {
    console.log("Naplata uspješno evidentirana:", result.resObject);
} else {
    console.error("Greška pri evidentiranju naplate:", result.error);
}

EvidentirajOdbijanje

const odbijanje: IOdbijanje = {
    // Broj dokumenta eRačuna, dio identifikatora eRačuna (BT-1 iz UBL 2.1)
    brojDokumenta: "RAC-2025-0001",
    // Datum izdavanja eRačuna, dio identifikatora eRačuna (BT-2 iz UBL 2.1)
    datumIzdavanja: "2025-01-01",
    // OIB ili porezni broj izdavatelja, dio identifikatora eRačuna (BT-31 iz UBL 2.1)
    oibPorezniBrojIzdavatelja: "00000000001",
    // OIB ili porezni broj primatelja
    oibPorezniBrojPrimatelja: "11111111119",
    // Datum odbijanja eRačuna
    datumOdbijanja: "2025-01-20",
    /**
     * Šifra vrste razloga odbijanja eRačuna
     * N - Neusklađenost podataka koji ne utječu na obračun poreza
     * U - Neusklađenost podataka koji utječu na obračun poreza
     * O - Ostalo
     */
    vrstaRazlogaOdbijanja: "N",
    // Razlog odbijanja eRačuna
    razlogOdbijanja: "Podaci o kupcu nisu točni",
}
const zahtjev = getEvidentirajOdbijanjeZahtjev(odbijanje);
const result = await client.evidentirajOdbijanje(zahtjev);
if (result.success) {
    console.log("Odbijanje uspješno evidentirano:", result.resObject);
} else {
    console.error("Greška pri evidentiranju odbijanja:", result.error);
}

Povezani projekti

• fiskalizacija2 - materijali vezani uz Projekt Fiskalizacija 2.0 - fiskalizaciju eRačuna i eIzvještavanje