Guides

Working with MLRs, eMLRs and MLAs

Actions and responses provide evidence and tracking of message transactions.

MLR (Message Level Response) documents are responses, that are used to receive status updates related to the delivery of an electronic document. Expected values are:

  • Acknowledgement (AB) is sent back after an outbound document has been received and validated and is ready for processing on our servers. If for some reason an AP signal is received before this one, it should be ignored.
  • Accepted (AP) is sent back after an outbound document has been delivered. This can be considered a final state.
  • Rejected (RE) is sent back after an outbound document has failed a delivery. The reason for the failure are stated in the message. This can be considered a final state, unless the message is later manually retried from the UI.

MLA (Message Level Action) documents is an extended application response, described below. It is used as a trigger for actions, such as tax reporting and contains the action document (tax reporting document, for example).

eMLR (Extended Message Level Response) documents is an extended application response, described below. When used in tax reporting, only the AP and RE signals can be expected.


What is extended application response?

An extended application response is based on Peppol BIS3 ApplicationResponse documents, but with the added capability to use document references allowing for more flexibility and transparency in specifying different types of references.


Action and response messages

There are two customizations we have defined.

First one is used for extended Message Level Response (MLRs), which is defined with the following process parameters:

<cbc:CustomizationID>urn:unimaze.com:transaction:mlr:3</cbc:CustomizationID>
<cbc:ProfileID>urn:unimaze.com:profile:mlr:3</cbc:ProfileID>

The other one is used as an extended Message Level Action (MLAs), which is defined by the following process parameters:

<cbc:CustomizationID>urn:unimaze.com:transaction:message_level_action:3</cbc:CustomizationID>
<cbc:ProfileID>urn:unimaze.com:profile:message_level_action:3</cbc:ProfileID>

NOTE: An application response document is chosen, as it is commonly supported and since UBL 2.x does not define a generic enquiry document.

In the flow diagrams below, we can describe the usage in the following way:

  • An MLA is created inherently, as a consequence of sending or receiving an invoice that needs to be reported to the tax authority or when directly triggered by a web service call, such as reporting a payment or rejection of an invoice.
    • The core document describes the action.
    • An external XML attachment will be added to the message, which in this context is the signed declaration, to be submitted to the tax authority.
  • An eMLR will be created and returned back with information as an evidence of submitted declaration (referenced) as well the signed response from the tax authority.
    • An document reference with an external URI pointing to the XML attachment contained within the action message.
    • An embedded XML document containing the response from the tax authority.

Usage specifications (identifiers)

Based on the Peppol BIS3 MLR validations, there are a few important differences.

First of all, party names (legal identifiers) are required and not only EndpointID

<cac:SenderParty>
    <cbc:EndpointID schemeID="9934">1000000000</cbc:EndpointID>
    <cac:PartyLegalEntity>
        <cbc:RegistrationName>Supplier/Seller (tax payer) Party</cbc:RegistrationName>
    </cac:PartyLegalEntity>
</cac:SenderParty>
<cac:ReceiverParty>
    <cbc:EndpointID schemeID="ZZZ">HR-TaxAuthority</cbc:EndpointID>
    <cac:PartyLegalEntity>
        <cbc:RegistrationName>Poreza Uprava</cbc:RegistrationName>
    </cac:PartyLegalEntity>
</cac:ReceiverParty>

The response code for the MLAs is always AQ (response expected) which by definition indicates that a response is requested or expected to the original message.

The response codes for the eMLRs can be AP (approved) or RE (rejected) to indicate a success or failure of the action.

Secondly, the document reference node is extended to provide three kind of data.

  • Document identifiers e.g. parameter values, used similar to "invoiced object identifiers" in invoice documents.
  • External document attachment references (URIs).
  • Embedded attachments.

The first document identifier always points to the invoice or credit note in question, for both action messages and response messages:

<cac:DocumentReference>
    <cbc:ID>d27318f1-a43c-47b0-a604-3cccb27c4bae</cbc:ID>
</cac:DocumentReference>

For action documents, similar identifiers are set to describe the action. The particular values applied for each workflow are specified in the sections below. Here is an example for RegisterPayment action.

<cac:DocumentReference>
    <cbc:ID>Jurisdiction</cbc:ID>
    <cbc:DocumentDescription>Croatia</cbc:DocumentDescription>
</cac:DocumentReference>
<cac:DocumentReference>
    <cbc:ID>RequestAction</cbc:ID>
    <cbc:DocumentDescription>RegisterPayment</cbc:DocumentDescription>
</cac:DocumentReference>
<cac:DocumentReference>
    <cbc:ID>PaidAmount</cbc:ID>
    <cbc:DocumentDescription>200.23</cbc:DocumentDescription>
</cac:DocumentReference>

For response documents, these document identifiers are set to describe return values, as the following example shows (in this case, how we could migrate SEF to allow more transparency and easier extraction of parameters):

  <cac:Response>
      <cbc:ResponseCode>AB</cbc:ResponseCode>
      <!-- <cbc:Description>{"NetworkInformation":{"InvoiceId":"354994557","SalesInvoiceId":"358843883"}}</cbc:Description> -->
  </cac:Response>

  <!-- Example SEF response -->
  <cac:DocumentReference>
      <cbc:ID>NetworkInvoiceId</cbc:ID>
      <cbc:DocumentDescription>354994557</cbc:DocumentDescription>
  </cac:DocumentReference>
  <cac:DocumentReference>
      <cbc:ID>NetworkSalesInvoiceId</cbc:ID>
      <cbc:DocumentDescription>358843883</cbc:DocumentDescription>
  </cac:DocumentReference>

Usage specifications (payloads)

In action messages in this context, there is never an embedded attachment, since the attachment is added after the core document is created.

It is created in the same context as the message, but separate from the core document.

The message simply describes the action (see below sections for more details) and the attachment is stored there for reference.

In response messages, in addition to potential return parameters, an external reference to the attachment is defined, this can be used to fetch the created evidence or request sent to the tax authority.

<cac:DocumentReference>
    <cbc:ID>TaxAuthorityRequest</cbc:ID>
    <cac:Attachment>
        <cac:ExternalReference>
            <cbc:URI>https://mapi.unimaze.com/messages/f4e4d960-7711-4abd-b8b7-8509f4b640dc/display?id=bcdef&amp;ct=raw</cbc:URI>
            <cbc:MimeCode>application/xml</cbc:MimeCode>
        </cac:ExternalReference>
    </cac:Attachment>
</cac:DocumentReference>

The response message will also include the returned response from the tax authority:

<cac:DocumentReference>
    <cbc:ID>TaxAuthorityResponse</cbc:ID>
    <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="application/xml"></cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
</cac:DocumentReference>

Flow overview, interactions with Tax Administration

The following diagram depicts which interactions are made with the tax authority from the supplier and customer.

📘

NOTE: Fiscal actions such as "register rejection" and "register payment" differ from one country to the other . This is an example of fiscal actions in use in Croatia.

---
title: Interactions with Tax Administration
---
sequenceDiagram
    participant S as Supplier
    participant C as Customer
    participant T as Tax Admin

    S->>T: Register fiscal document (issued e-invoice)
    S->>T: Register taxable deliveries (issued NON e-invoice)
    S->>T: Register paid e-invoice
    C->>T: Register fiscal document (received e-invoice)
    C->>T: Register rejected e-invoice

Fiscalization of outbound invoice/credit note

The service internally creates an extended Application Response (MLA) with document identifier variables:

  • Jurisdiction: Croatia
  • Role: Supplier
  • RequestAction: RegisterFiscalEvidence

The Application Response (MLR) is returned with document identifier variables (example):

  • ErrorCode: S0008
  • ErrorDescription: Već postoji zabilježen eRačun s istim identifikatorom.
---
title: Fiscalization of outbound invoice/credit note (supplier side)
---
sequenceDiagram
    participant E as ERP / SaaS partner
    participant M as Unimaze / MAPI
    participant MPS
    participant C as Customer
    participant TA as Tax Admin

    E->>M: POST SubmitInvoice
    M->>MPS: Query registry
    MPS->>M: Is registered = YES
    M-->>M: adds service
    M->>C: Deliver invoice
    M->>E: Get MLR (invoice delivery)
    M->>M: Creates request RegisterFiscalEvidence document
    M->>M: Sign document
    M->>M: Add attachment 'EvidentirajERacunZahtjev'
    M->>TA: Make SOAP request
    M->>E: GET Extended MLR (incl. signed request+result)

Fiscalization of inbound invoice/credit note

The service internally creates an extended Application Response (MLA) with document identifier variables:

  • Jurisdiction: Croatia
  • Role: Customer
  • RequestAction: RegisterFiscalEvidence

The MLR is as described above, with no specific return document identifier variables.

---
title: Fiscalization of inbound invoice/credit note (customer side)
---
sequenceDiagram
    participant S as Supplier
    participant M as Unimaze / MAPI
    participant E as ERP / SaaS partner
    participant TA as Tax Admin

    S->>M: Receive invoice
    M-->>M: adds service
    M->>E: Get MLR (invoice delivery)
    M->>E: GET SubmitInvoice
    M->>M: Create new request document RegisterFiscalEvidence
    M->>M: Sign document
    M->>M: Add attachment 'EvidentirajERacunZahtjev'
    M->>TA: Make SOAP request
    M->>E: GET Extended MLR (incl. signed request+result)

Register paid invoice/credit note (Croatia)

This action is triggered with web service call POST /messages/:mid/compliance/hr/register-payment where :mid is the GUID of the previously issued invoice. This will automatically create a message with reference number (for tracking and tracing) <invoice number>-RegisterPayment.

The payload will be:

{
  "billingDate": "2025-10-20",   -- double check translation ...
  "chargedAmount": "323.10",
  "paymentMethod": "Other"       -- taken from enum: TransactionAccount, SettlementPayment, Other
}

The content is extended Application Response with document reference variables:

  • Jurisdiction: Croatia
  • Role: Supplier
  • RequestAction: RegisterPayment

---
title: Register paid invoice/credit note (supplier side)
---
sequenceDiagram
    participant E as ERP / SaaS partner
    participant M as Unimaze / MAPI
    participant TA as Tax Admin

    E->>M: POST ReportFiscalPayment
    M->>M: Create new request document RegisterFiscalAction
    M->>M: Sign document
    M->>M: Add attachment 'EvidentirajNaplatuZahtjev'
    M->>TA: Make SOAP request
    M->>E: GET Extended MLR (incl. signed request+result)

Register rejected invoice/credit note (Croatia)

This action is triggered with web service call POST /messages/:mid/compliance/hr/register-rejection where :mid is the GUID of the previously received invoice. This will automatically create a message with reference number (for tracking and tracing) <invoice number>-RegisterRejections.

The payload will be:

{
  "rejectionType": "Other",   -- enum MismatchNotAffectingTax, MismatchAffectingTax, Other
  "rejectionReason": "We rejected due to ..."
}

The content is extended Application Response (MLA) with document reference variables:

  • Jurisdiction: Croatia
  • Role: Customer
  • RequestAction: RegisterRejection
  • RejectionType: <one of enum values>
  • RejectionReason: <description of rejection>
---
title: Register rejected invoice/credit note (customer side)
---
sequenceDiagram
    participant E as ERP / SaaS partner
    participant M as Unimaze / MAPI
    participant TA as Tax Admin

    E->>M: POST ReportFiscalRejection
    M->>M: New document RegisterFiscalAction (extended application response)
    M->>M: Sign document
    M->>M: Add attachment 'EvidentirajOdbijanjeZahtjev'
    M->>TA: Make SOAP request
    M->>E: GET Extended MLR (incl. signed request + result)

Report taxable deliveries from invoice/credit note(Croatia)

The service internally creates an extended Application Response (MLA) with document identifier variables:

  • Jurisdiction: Croatia
  • Role: Supplier
  • RequestAction: RegisterTaxableDelivery

The MLR is as described above, with no specific return document identifier variables.

---
title: Report taxable deliveries from invoice/credit note (supplier side)
---
sequenceDiagram
    participant E as ERP / SaaS partner
    participant M as Unimaze / MAPI
    participant MPS
    participant TA as Tax Admin

    E->>M: POST SubmitInvoice
    M->>MPS: Query registry
    MPS->>M: Is registered = NO
    M->>E: Get MLR (invoice delivery)
    M-->>M: adds service, creates TaxClearance document
    M-->>M: POST Add request document RegisterTaxableDelivery
    M->>M: Sign document
    M->>M: Add attachment 'EvidentirajIsporukuZaKojuNijeIzdanERacunZahtjev'
    M->>TA: Make SOAP request
    M->>E: GET Extended MLR (incl. signed request+result)

Updated 2 days ago