Skip to main content

Quick Start

This tutorial runs entirely in the HR sandbox. You will authenticate, create a sandbox Legal Entity, confirm its onboarding, send an invoice, and verify how an incoming invoice is received.

Sandbox API URL: https://hr-sandbox.api.acubeapi.com

No production credentials or real fiscal documents are used in this tutorial.

You will complete four steps:

  1. Get sandbox access and authenticate.
  2. Onboard a new Legal Entity.
  3. Simulate the reception of an incoming invoice.
  4. Send an invoice.

1. Get sandbox access and authenticate​

Create a free sandbox account. To receive an access token, please follow the authentication guide

If the received token does not grant access to the HR API, contact A-Cube support.

A Legal Entity represents the Croatian taxpayer that will send or receive documents.

In the production environment, onboarding has two parts:

  1. You create the Legal Entity in A-Cube, with the services it uses.
  2. A representative of the company confirms A-Cube in FiskAplikacija, the Tax Authority's application in the ePorezna portal, once for each enabled service:
    • Document exchange: A-Cube as its accredited service provider (ASP).
    • Fiscalisation: A-Cube as authorised to fiscalise for it.

A-Cube then checks the confirmations automatically and records them on the Legal Entity; to check at once, run the onboarding check. A service can be used once it is confirmed.

In the sandbox environment, there is no FiskAplikacija step, but you still run the onboarding check after creating the Legal Entity. The check doesn't contact the Tax Authority:

  • Document exchange is confirmed once the Legal Entity is registered in A-Cube's metadata service (SMP), which A-Cube does when the Legal Entity is created.
  • Fiscalisation is always confirmed.

Use POST /legal-entities to create a Legal Entity in A-Cube.

The {{jwt}} should be replaced with the token received from authentication step.

The taxId field refers to the OIB (Tax identifier) of the Legal Entity: replace {{supplier_taxId}} with a valid OIB (11 digits). documentExchangeEnabled and fiscalisationEnabled choose the services A-Cube provides for it: sending and receiving documents, and reporting them to the Tax Authority.

POST /legal-entities
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json

{
"taxId": "{{supplier_taxId}}",
"name": "Example Supplier d.o.o.",
"email": "example@company.com",
"phoneNumber": "+38514567890",
"country": "HR",
"address": "Ilica 1",
"city": "Zagreb",
"zipCode": "10000",
"documentExchangeEnabled": true,
"fiscalisationEnabled": true
}
{
"uuid": "018f4a2e-7b3c-7f1a-b2c3-4d5e6f789abc",
"taxId": "{{supplier_taxId}}",
"name": "Example Supplier d.o.o.",
"email": "example@company.com",
"phoneNumber": "+38514567890",
"country": "HR",
"address": "Ilica 1",
"city": "Zagreb",
"county": null,
"zipCode": "10000",
"createdAt": "2026-11-01T10:00:00+00:00",
"updatedAt": null,
"documentExchangeEnabled": true,
"fiscalisationEnabled": true,
"documentExchangeConfirmationStatus": "not_checked",
"documentExchangeConfirmationError": null,
"fiscalisationConfirmationStatus": "not_checked",
"fiscalisationConfirmationError": null
}

2.2. Check the onboarding​

Use POST /legal-entities/{uuid}/onboarding-check to check whether the Legal Entity has confirmed A-Cube for document exchange and for fiscalisation. Replace {{legalEntityUuid}} with the uuid of the Legal Entity created in the previous step.

In the sandbox, the check sets each enabled service to confirmed. Until document exchange is confirmed, sending a document is refused with legal_entity_not_onboarded; until fiscalisation is confirmed, filing a report or the Tax Data Document of an external document is refused with report.fiscalisation_not_confirmed or tax_data_document.fiscalisation_not_confirmed.

POST /legal-entities/{{legalEntityUuid}}/onboarding-check
Authorization: Bearer {{jwt}}
Accept: application/json
{
"documentExchangeConfirmationStatus": "confirmed",
"documentExchangeConfirmationError": null,
"fiscalisationConfirmationStatus": "confirmed",
"fiscalisationConfirmationError": null
}

3. Simulate an incoming invoice​

There is no public endpoint for directly injecting an incoming invoice. To test invoice reception, send an invoice from one sandbox Legal Entity to another.

Please repeat the steps of onboarding a new legal entity using a different OIB (taxId) to create a second Legal Entity. Save the newly generated Legal Entity OIB as {{customer_taxId}} and its uuid as {{customer_legalEntityUuid}}.

4. Send an invoice​

4.1 Send an HR CIUS 2025 Invoice​

Prepare a valid UBL 2.1 XML invoice following the Croatian specification for e-invoices, with extensions (HR CIUS 2025) and send it as a request body to POST /invoices

Before sending the request, remember to replace {{supplier_taxId}} & {{customer_taxId}} accordingly with the Legal Entity OIBs you created in the previous steps.

POST /invoices
Authorization: Bearer {{jwt}}
Content-Type: application/xml
Accept: application/json
<?xml version="1.0" encoding="UTF-8"?>
<Invoice
xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"
xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2"
xmlns:sig="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2">
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionContent>
<sig:UBLDocumentSignatures>
<sac:SignatureInformation/>
</sig:UBLDocumentSignatures>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:mfin.gov.hr:cius-2025:1.0#conformant#urn:mfin.gov.hr:ext-2025:1.0</cbc:CustomizationID>
<cbc:ProfileID>P1</cbc:ProfileID>
<cbc:ID>2026-Invoice-0001</cbc:ID>
<cbc:IssueDate>2026-11-01</cbc:IssueDate>
<cbc:IssueTime>10:00:00</cbc:IssueTime>
<cbc:DueDate>2026-11-30</cbc:DueDate>
<cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
<cac:AccountingSupplierParty>
<cac:Party>
<cbc:EndpointID schemeID="9934">{{supplier_taxId}}</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID>9934:{{supplier_taxId}}::HR99:12345</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cbc:StreetName>Ilica 1</cbc:StreetName>
<cbc:CityName>Zagreb</cbc:CityName>
<cbc:PostalZone>10000</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>HR</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>HR{{supplier_taxId}}</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Example Supplier d.o.o.</cbc:RegistrationName>
</cac:PartyLegalEntity>
<cac:Contact>
<cbc:Name>Example Contact</cbc:Name>
<cbc:ElectronicMail>example@company.com</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
<cac:SellerContact>
<cbc:ID>{{supplier_taxId}}</cbc:ID>
<cbc:Name>Operator</cbc:Name>
</cac:SellerContact>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="9934">{{customer_taxId}}</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID>9934:{{customer_taxId}}::HR99:98765</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cbc:StreetName>Savska cesta 1</cbc:StreetName>
<cbc:CityName>Zagreb</cbc:CityName>
<cbc:PostalZone>10000</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>HR</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>HR{{customer_taxId}}</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Example Buyer d.o.o.</cbc:RegistrationName>
</cac:PartyLegalEntity>
</cac:Party>
</cac:AccountingCustomerParty>
<cac:Delivery>
<cbc:ActualDeliveryDate>2026-11-01</cbc:ActualDeliveryDate>
<cac:DeliveryLocation>
<cac:Address>
<cac:Country>
<cbc:IdentificationCode>HR</cbc:IdentificationCode>
</cac:Country>
</cac:Address>
</cac:DeliveryLocation>
</cac:Delivery>
<cac:PaymentMeans>
<cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
<cac:PayeeFinancialAccount>
<cbc:ID>HR4424070001100630713</cbc:ID>
</cac:PayeeFinancialAccount>
</cac:PaymentMeans>
<cac:TaxTotal>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="EUR">1325.00</cbc:TaxableAmount>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.00</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
<cbc:LineExtensionAmount currencyID="EUR">1325.00</cbc:LineExtensionAmount>
<cbc:TaxExclusiveAmount currencyID="EUR">1325.00</cbc:TaxExclusiveAmount>
<cbc:TaxInclusiveAmount currencyID="EUR">1656.25</cbc:TaxInclusiveAmount>
<cbc:PayableAmount currencyID="EUR">1656.25</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
<cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:InvoicedQuantity unitCode="H87">1.000</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount currencyID="EUR">1325.00</cbc:LineExtensionAmount>
<cac:Item>
<cbc:Name>Example product</cbc:Name>
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="CG">62.90.90</cbc:ItemClassificationCode>
</cac:CommodityClassification>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Name>HR:PDV25</cbc:Name>
<cbc:Percent>25</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">1325.000000</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="H87">1.000</cbc:BaseQuantity>
</cac:Price>
</cac:InvoiceLine>
</Invoice>
{
"uuid": "0199e8a1-2b3c-7d4e-8f90-a1b2c3d4e5f6",
"legalEntityUuid": "018f4a2e-7b3c-7f1a-b2c3-4d5e6f789abc",
"invoiceNumber": "2026-Invoice-0001",
"invoiceDate": "2026-11-01",
"dueDate": "2026-11-30",
"currency": "EUR",
"totalAmount": "1656.25",
"netAmount": "1325.00",
"direction": "outgoing",
"typeCode": "380",
"businessProcess": "P1",
"sender": {
"name": "Example Supplier d.o.o.",
"taxId": "{{supplier_taxId}}"
},
"recipient": {
"name": "Example Buyer d.o.o.",
"taxId": "{{customer_taxId}}"
},
"status": "sent",
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-11-01T10:00:00+00:00",
"updatedAt": "2026-11-01T10:00:00+00:00"
}

4.2 Retrieve the received invoice​

Reception is asynchronous. Retrieve the filtered invoice list using:

GET /invoices?legalEntityUuid[]={{customer_legalEntityUuid}}&direction[]=incoming

GET /invoices?legalEntityUuid[]={{customer_legalEntityUuid}}&direction[]=incoming
Authorization: Bearer {{jwt}}
Accept: application/json
[
{
"uuid": "0199e8a1-9c4d-7e5f-8a6b-7c8d9e0f1a2b",
"legalEntityUuid": "{{customer_legalEntityUuid}}",
"invoiceNumber": "2026-Invoice-0001",
"invoiceDate": "2026-11-01",
"dueDate": "2026-11-30",
"currency": "EUR",
"totalAmount": "1656.25",
"netAmount": "1325.00",
"direction": "incoming",
"typeCode": "380",
"businessProcess": "P1",
"sender": {
"name": "Example Supplier d.o.o.",
"taxId": "{{supplier_taxId}}"
},
"recipient": {
"name": "Example Buyer d.o.o.",
"taxId": "{{customer_taxId}}"
},
"status": "received",
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-11-01T10:00:05+00:00",
"updatedAt": "2026-11-01T10:00:05+00:00"
}
]

Then, retrieve the document details and original XML using its UUID.

tip

You can now authenticate, onboard a sandbox entity, and exchange test documents.

Next steps: