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:

`text
{
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:

`typescript
interface FiskalizacijaResult {
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, options?: ExtractionOptions): IERacun
- getRacunFromUbl(doc: string | Buffer | XmlDocument | XmlElement, options?: ExtractionOptions): 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.

$3

Ako UBL dokument nije u potpunosti ispravan (npr. nedostaju obvezna polja ili polja ne zadovoljavaju regex), metode će baciti ValidationError. Prosljeđivanjem lenient: true opcije moguće je izvući djelomične podatke:

`typescript
const options = {
lenient: true,
errors: [] // Opcionalno: polje u koje će se prikupiti sve validacijske greške
};
const eRacun = getERacunFromUbl(ublDocument, options);

// IERacun objekt će sadržavati sve podatke koji postoje, neovisno o tome da li zadovoljavaju regex.
// Polja koja nedostaju će biti prazni stringovi/nizovi
`

Primjeri

$3

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

$3

`typescript
const ublDocument = '....'; // 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);
}
`

$3

`typescript
const ublDocument = '....'; // 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);
}
`

$3

`typescript
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);
}
`

$3

`typescript
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