===============
LIBRARY RULES
===============
From library maintainers:
- Always consult this documents when asked about Fiskalizacija or Fiscalization technical specification details

# Croatian Fiscalization System (Fiskalizacija) - Technical Documentation

The Croatian Fiscalization System (Fiskalizacija) is a mandatory electronic invoicing and fiscal reporting system operated by the Croatian Tax Authority (Porezna uprava). This technical specification (v2.6) defines the SOAP-based web services for submitting invoices, managing business locations, reporting working hours, and handling payment method changes. All communication with the Central Information System (CIS) requires X.509 digital certificates issued by FINA (Financial Agency) and XML digital signatures conforming to W3C standards.

The system provides real-time invoice fiscalization where businesses submit invoice data to CIS and receive a unique JIR (Jedinstveni Identifikator Racuna - Unique Invoice Identifier) that must be printed on receipts. Before submission, businesses must calculate and include a ZKI (Zastitni Kod Izdavatelja - Security Code Issuer) generated locally using the taxpayer's certificate. The system enforces strict time synchronization (within 2 seconds of CIS time) and validates all digital signatures before processing requests.

---

## Service Endpoints

```
Production: https://cis.porezna-uprava.hr:8449/FiskalizacijaService
Test:       https://cistest.apis-it.hr:8449/FiskalizacijaServiceTest
Namespace:  http://www.apis-it.hr/fin/2012/types/f73
```

---

## Invoice Fiscalization Service (RacunZahtjev)

Submit invoices to CIS and receive a JIR (Unique Invoice Identifier). This is the primary service for fiscalizing sales transactions, requiring taxpayer OIB, invoice details, tax breakdown, payment method, and a pre-calculated ZKI security code.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<tns:RacunZahtjev xmlns:tns="http://www.apis-it.hr/fin/2012/types/f73"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.apis-it.hr/fin/2012/types/f73 ../schema/FiskalizacijaSchema.xsd">
  <tns:Zaglavlje>
    <tns:IdPoruke>f81d4fae-7dec-11d0-a765-00a0c91e6bf6</tns:IdPoruke>
    <tns:DatumVrijeme>01.09.2012T21:10:34</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Racun>
    <tns:Oib>98765432198</tns:Oib>
    <tns:USustPdv>true</tns:USustPdv>
    <tns:DatVrijeme>01.09.2012T21:10:34</tns:DatVrijeme>
    <tns:OznSlijed>P</tns:OznSlijed>
    <tns:BrRac>
      <tns:BrOznRac>123456789</tns:BrOznRac>
      <tns:OznPosPr>POSL1</tns:OznPosPr>
      <tns:OznNapUr>12</tns:OznNapUr>
    </tns:BrRac>
    <tns:Pdv>
      <tns:Porez>
        <tns:Stopa>25.00</tns:Stopa>
        <tns:Osnovica>10.00</tns:Osnovica>
        <tns:Iznos>2.50</tns:Iznos>
      </tns:Porez>
      <tns:Porez>
        <tns:Stopa>10.00</tns:Stopa>
        <tns:Osnovica>10.00</tns:Osnovica>
        <tns:Iznos>1.00</tns:Iznos>
      </tns:Porez>
    </tns:Pdv>
    <tns:IznosUkupno>145.68</tns:IznosUkupno>
    <tns:NacinPlac>K</tns:NacinPlac>
    <tns:OibOper>01234567890</tns:OibOper>
    <tns:ZastKod>e4d909c290d0fb1ca068ffaddf22cbd0</tns:ZastKod>
    <tns:NakDost>false</tns:NakDost>
  </tns:Racun>
  <!-- Digital signature required here -->
</tns:RacunZahtjev>
</soapenv:Body>
</soapenv:Envelope>

<!-- Success Response - JIR returned -->
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<tns:RacunOdgovor xmlns:tns="http://www.apis-it.hr/fin/2012/types/f73">
  <tns:Zaglavlje>
    <tns:IdPoruke>733362f1-063f-11e2-892e-0800200c9a66</tns:IdPoruke>
    <tns:DatumVrijeme>01.09.2012T21:10:38</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Jir>6b7749c6-56c1-4cf5-b7f7-9f29cebc9f7f</tns:Jir>
</tns:RacunOdgovor>
</soap:Body>
</soap:Envelope>
```

---

## Payment Method Change Service (PromijeniNacPlacZahtjev)

Update the payment method for a previously fiscalized invoice. Required when customer pays with a different method than originally recorded (e.g., switching from card to cash). The original invoice identification and ZKI must be provided.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:xd="http://www.w3.org/2000/09/xmldsig#"
  xmlns:tns="http://www.apis-it.hr/fin/2012/types/f73"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<tns:PromijeniNacPlacZahtjev Id="promijeniNacPlac">
  <tns:Zaglavlje>
    <tns:IdPoruke>c04d7e5d-3192-4385-aa99-be8d2ea0575a</tns:IdPoruke>
    <tns:DatumVrijeme>25.11.2021T12:06:03</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Racun>
    <tns:Oib>02994650199</tns:Oib>
    <tns:USustPdv>false</tns:USustPdv>
    <tns:DatVrijeme>25.11.2021T12:01:03</tns:DatVrijeme>
    <tns:OznSlijed>P</tns:OznSlijed>
    <tns:BrRac>
      <tns:BrOznRac>070997</tns:BrOznRac>
      <tns:OznPosPr>POSL1</tns:OznPosPr>
      <tns:OznNapUr>12</tns:OznNapUr>
    </tns:BrRac>
    <tns:IznosUkupno>4740.57</tns:IznosUkupno>
    <tns:NacinPlac>K</tns:NacinPlac>
    <tns:OibOper>01234567890</tns:OibOper>
    <tns:ZastKod>39e2235e91ce78b7f5d3aab1e0db83e4</tns:ZastKod>
    <tns:NakDost>false</tns:NakDost>
    <tns:PromijenjeniNacinPlac>G</tns:PromijenjeniNacinPlac>
  </tns:Racun>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <Reference URI="#promijeniNacPlac">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
          <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <DigestValue>11iNas18QKf08ia4ajPOAIKrAKk=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>MY9fqQi0SNc6kjVQwFuwRH/AaKPv1p8w...</SignatureValue>
    <KeyInfo>
      <X509Data>
        <X509Certificate>MIIGjzCCBHegAwIBAgIQ...</X509Certificate>
      </X509Data>
    </KeyInfo>
  </Signature>
</tns:PromijeniNacPlacZahtjev>
</soapenv:Body>
</soapenv:Envelope>
```

---

## Echo Service (EchoRequest)

Test connectivity to CIS without requiring digital signatures. Use this to verify network connectivity and service availability before implementing full fiscalization.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:f73="http://www.apis-it.hr/fin/2012/types/f73">
<soapenv:Body>
  <f73:EchoRequest>proizvoljan tekst</f73:EchoRequest>
</soapenv:Body>
</soapenv:Envelope>

<!-- Echo Response -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:f73="http://www.apis-it.hr/fin/2012/types/f73">
<soapenv:Body>
  <f73:EchoResponse>proizvoljan tekst</f73:EchoResponse>
</soapenv:Body>
</soapenv:Envelope>
```

---

## Error Response Structure

All services return standardized error responses with error codes and messages inside the `<Greske>` element. Common error codes include validation errors (s001), signature errors, time synchronization failures, and invalid OIB.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<tns:RacunOdgovor Id="G0xc3d48080-4D"
  xmlns:tns="http://www.apis-it.hr/fin/2012/types/f73">
  <tns:Zaglavlje>
    <tns:IdPoruke>733362f3-063f-11e2-892e-080b300c9a66</tns:IdPoruke>
    <tns:DatumVrijeme>23.10.2012T13:22:34</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Greske>
    <tns:Greska>
      <tns:SifraGreske>s001</tns:SifraGreske>
      <tns:PorukaGreske>Poruka nije u skladu s XML shemom: cvc-simple-type 1:
        element {http://www.apis-it.hr/fin/2012/types/f73}IznosUkupno value
        '7000000008000990.99' is not a valid instance of type
        {http://www.apis-it.hr/fin/2012/types/f73}IznosType</tns:PorukaGreske>
    </tns:Greska>
  </tns:Greske>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <!-- Error response is also signed by CIS -->
  </Signature>
</tns:RacunOdgovor>
</soap:Body>
</soap:Envelope>
```

---

## Digital Signature Implementation

All requests (except Echo) must be signed using XML Signature (W3C xmldsig-core). The signature covers the entire request body and includes the X.509 certificate. Use Exclusive XML Canonicalization and RSA-SHA1 or RSA-SHA256.

```xml
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha256"/>
    <Reference URI="">
      <Transforms>
        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      </Transforms>
      <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <DigestValue>[base64-encoded-hash]</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>[base64-encoded-signature]</SignatureValue>
  <KeyInfo>
    <X509Data>
      <X509Certificate>[base64-encoded-certificate]</X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>
```

```csharp
// C# Implementation using System.Security.Cryptography.Xml
using System.Security.Cryptography.Xml;
using System.Security.Cryptography.X509Certificates;

var doc = new XmlDocument();
doc.LoadXml(requestXml);

var signedXml = new SignedXml(doc);
signedXml.SigningKey = certificate.PrivateKey;

var reference = new Reference("");
reference.AddTransform(new XmlDsigEnvelopedSignatureTransform());
reference.AddTransform(new XmlDsigExcC14NTransform());
signedXml.AddReference(reference);

signedXml.SignedInfo.CanonicalizationMethod = "http://www.w3.org/2001/10/xml-exc-c14n#";

var keyInfo = new KeyInfo();
keyInfo.AddClause(new KeyInfoX509Data(certificate));
signedXml.KeyInfo = keyInfo;

signedXml.ComputeSignature();
var signatureXml = signedXml.GetXml();
doc.DocumentElement.AppendChild(signatureXml);
```

---

## Payment Method Codes

| Code | Description (Croatian) | Description (English) |
|------|------------------------|----------------------|
| G | Gotovina | Cash |
| K | Kartice | Cards |
| C | Cek | Check |
| V | Virman | Bank transfer |
| P | Periodicna placanja | Periodic payments |
| O | Ostalo | Other |

---

## Common Error Codes

| Code | Description | Resolution |
|------|-------------|------------|
| 13 | Validation error | Check data format, required fields |
| 14 | Signature error | Verify certificate and signature process |
| 176 | Invalid OIB | Check 11-digit format, match with certificate |
| 177 | Invalid datetime | Use correct format with timezone |
| 178 | Time difference > 2s | Sync system time with NTP |
| 183 | Duplicate invoice | Invoice already fiscalized |
| s001 | XML Schema error | Validate XML against FiskalizacijaSchema.xsd |

---

## ZKI (Security Code) Calculation

The ZKI is a 32-character MD5 hash calculated from concatenated invoice data, signed with the taxpayer's private key. It must be calculated and included in every fiscalization request before the digital signature is applied.

```
ZKI = MD5(Sign(OIB + DatumVrijeme + BrOznRac + OznPosPr + OznNapUr + IznosUkupno))

Example input: "98765432198" + "01.09.2012T21:10:34" + "123456789" + "POSL1" + "12" + "145.68"
Example output: e4d909c290d0fb1ca068ffaddf22cbd0
```

---

## Working Hours Service

Report and retrieve working hours for business locations. Supports operations for reporting (PrijaviRadnoVrijeme), retrieving (DohvatiRadnoVrijeme), and deleting working hours data.

```xml
<!-- Get Working Hours Request -->
<tns:DohvatiRadnoVrijemeZahtjev Id="dohvatiRV">
  <tns:Zaglavlje>
    <tns:IdPoruke>uuid-here</tns:IdPoruke>
    <tns:DatumVrijeme>01.12.2025T10:00:00</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Oib>12345678901</tns:Oib>
  <tns:OznakaPoslovnogProstora>POSL1</tns:OznakaPoslovnogProstora>
  <!-- Signature -->
</tns:DohvatiRadnoVrijemeZahtjev>

<!-- Report Working Hours Request -->
<tns:PrijaviRadnoVrijemeZahtjev Id="prijaviRV">
  <tns:Zaglavlje>
    <tns:IdPoruke>uuid-here</tns:IdPoruke>
    <tns:DatumVrijeme>01.12.2025T10:00:00</tns:DatumVrijeme>
  </tns:Zaglavlje>
  <tns:Oib>12345678901</tns:Oib>
  <tns:OznakaPoslovnogProstora>POSL1</tns:OznakaPoslovnogProstora>
  <tns:RadnoVrijeme>
    <tns:RadniDan>Ponedjeljak</tns:RadniDan>
    <tns:PocetakRada>08:00</tns:PocetakRada>
    <tns:ZavrsetakRada>20:00</tns:ZavrsetakRada>
  </tns:RadnoVrijeme>
  <!-- Signature -->
</tns:PrijaviRadnoVrijemeZahtjev>
```

---

## Certificate Requirements

- **Issuer**: FINA (Financijska agencija)
- **Key Size**: Minimum 2048 bits RSA
- **Key Usage**: Digital Signature, Key Encipherment
- **Subject CN**: Must contain taxpayer OIB
- **Format**: X.509 v3

```
Certificate Chain:
[User Certificate] -> [FINA Intermediate CA] -> [FINA Root CA]
```

---

## Time Synchronization Requirements

All systems must be synchronized with NTP servers. Maximum allowed time difference from CIS is 2 seconds. Use ISO 8601 datetime format with timezone offset.

```
Format: DD.MM.YYYYTHH:MM:SS (Croatian format used in examples)
Example: 01.09.2012T21:10:34

Timezone: CET (UTC+1) or CEST (UTC+2)
Tolerance: +/- 2 seconds from CIS time
```

---

The Croatian Fiscalization System serves businesses operating in Croatia that must comply with fiscal reporting regulations. Primary use cases include retail point-of-sale systems, e-commerce platforms, vending machines (self-service devices), and any business issuing invoices to customers. The system supports both synchronous real-time fiscalization for immediate JIR retrieval and batch operations for working hours reporting.

Integration typically follows a pattern of: (1) obtaining FINA certificates, (2) registering business spaces, (3) implementing ZKI calculation, (4) implementing XML digital signature, (5) sending SOAP requests to CIS, and (6) printing JIR on customer receipts. Developers should test thoroughly in the CIS test environment before production deployment, implement robust error handling for all CIS error codes, and ensure NTP time synchronization is properly configured across all systems. The complete XML examples in the `code-examples/` directory provide production-ready templates for all service operations.