Getting started

Invoice, UBL - Integrators Manual

Goals

Your main goals are to enable users following operations via your ERP system:

  • Send documents, properly formatted and wrapped in XML with enabled attachments
  • Receive documents (importing data from XML document)
  • Monitor statuses of sent invoices
  • Enable resend and cancel actions with outgoing and reject action on incoming invoices

Registration

Moj-eRačun functionalities presume that user is registered, so if he hasn't passed the registration process, it is necessary for an application to redirect him to our page https://www.moj-eracun.rs/home/registracija where he can go through the process using web browser and familiarize himself with details and further steps. After he successfully passes the registration process, he should be able to input his credentials into your application. User identity is defined through 4 fields:

Api V1

Id - User credential username
Pass - User credential password
Oib - Sender CompanyID
PJ – Sender Company Business Unit

Api V2

Username - Login number
Password - Login password
CompanyId - Sender Business Number, aka PIB or VatId
CompanyBu – Sender Business Unit

All of these four data are interpreted as textual data. User may run multiple companies under the same account and vice-versa so "many-to-many" relationship should be considered. Business unit field should remain empty if user doesn't require one or he doesn't know what that is. Business unit can be described as a store, or dislocated area which one company owns or where it conducts some business activities.

Invoice

Invoice is XML representation of invoice data.

Invoice xsd schemes and namespaces

Invoice implements UBL-2.1 schemes and namespaces.

Invoice parsed nodes

Parsed nodes are mandatory nodes, that moj-eracun.hr service will extract from posted document and use to properly address document

Invoice ID: Invoice/ID
Supplier CompanyID (PIB, VatId or similar): Invoice/AccountingSupplierParty/Party/PartyLegalEntity/CompanyID
Supplier Company BusinessUnit: Invoice/AccountingSupplierParty/Party/PartyIdentification/ID
Customer CompanyID (PIB, VatId or similar): Invoice/AccountingCustomerParty/Party/PartyLegalEntity/CompanyID
Customer Company BusinessUnit: Invoice/AccountingCustomerParty/Party/PartyIdentification/ID
Customer Business Contact Email: Invoice/AccountingCustomerParty/AccountingContact/ElectronicMail
Attached document: AttachedDocument/Attachment/EmbeddedDocumentBinaryObject

Invoice parsed nodes example


<outgoinginvoicesdata>
        <outgoinginvoice>
        <invoiceenvelope>
        <invoice>
        <!-- Invoice Id -->
        <cbc:id>15-01-91</cbc:id>
        <cac:accountingsupplierparty>
        <cac:party>
        <cac:partylegalentity>
                <!-- Sender PIB -->
        <cbc:companyid>69715301002</cbc:companyid>
            </cac:partylegalentity>
            <!-- Optional Sender Business Unit -->
        <cac:partyidentification>
        <cbc:id>Business unit 1</cbc:id>
            </cac:partyidentification>
            </cac:party>
        </cac:accountingsupplierparty>
        <cac:accountingcustomerparty>
        <cac:party>
        <cac:partylegalentity>
                <!-- Recipient PIB -->
        <cbc:companyid>01234554321</cbc:companyid>
            </cac:partylegalentity>
            <!-- Optional Recipient Business Unit -->
        <cac:partyidentification>
        <cbc:id>podružnica Ilok</cbc:id>
            </cac:partyidentification>
            </cac:party>
        <cac:accountingcontact>
            <!-- Recipient contact mail -->
        <cbc:electronicmail>test@gmail.com;test2@gmail.com;test3@gmail.com</cbc:electronicmail>
            </cac:accountingcontact>
        </cac:accountingcustomerparty>
        </invoice>
    </invoiceenvelope>
        <attacheddocumentenvelope>
        <attacheddocument>
        <cbc:parentdocumentid>15-01-91</cbc:parentdocumentid>
        <cac:attachment>
            <!-- Base64 encoded Pdf file to string -->
        <cbc:embeddeddocumentbinaryobject mimecode="application/pdf" filename="Invoice-15-01-91.pdf">
            JVBER...==
            </cbc:embeddeddocumentbinaryobject>
        </cac:attachment>
        </attacheddocument>
    </attacheddocumentenvelope>
  
    </outgoinginvoice>
</outgoinginvoicesdata>
        

Guidelines for implementation

These guidelines contain some of the most common questions which could appear during the integration proccess.

  • Make sure to fill as many data as possible in the XML document
  • Make sure that you validate your XML document before testing
  • Make sure that you enable sending eDocuments to multiple e-mail addresses (see XML node strucutre lower)
  • Make sure that you enable sending multiple attachments

Multiple e-mails - XML node structure

Multiple e-mail addressess should be put in the customers Accounting Contact data:


        <cac:AccountingContact>
        <cbc:Name>Accounting Contact Name</cbc:Name>
        <cbc:ElectronicMail>mail1@mail.com;mail2@mail.com</cbc:ElectronicMail>
           </cac:AccountingContact>
            
            

European Norm (EN) compliance

In March 2017, CEN issued the EU norm for electronic invoices which are exchanged with public entities. This norm implemented some differences in comparison to the current data model used by Moj-eRačun and other service providers in Croatia.
Therefore we have begun to implement these changes to our system to enable our users to exchange eInvoices with public entities. Our service will be fully compliant with the EU norm, and the Croatian legislation in time.
To implement these differences, we had to do some modifications to our system. These modifications are described in the following guidelines:

These Guidelines contain XSD schemes for EN compliant eInovices, an XML example and PDF file with textual guidelines. In order to ensure that all of our partners will be able to exchange EN compliant eInvoices, we have decided to develop a converter which will convert the current standard which our user use to the EN compliant format. Therefore, the proccess of exchange of eInvoices will look like this:

We hope that this picture, together with the Guidelines will give you all the necessary information on implementation of EN compliant eInvoices. If you have any questions, feel free to contact us.

UBL Validation

You can validate Your XML document on the this: link

Demo environment

Moj-eRačun service provides a demo environment to its partners for testing purposes. Demo environment can be accessed via this: link.

If a partner wants to use our demo environment, he should be registered so make sure you have your username and password before you begin testing.

Contact us

If you have any questions, feel free to contact us: