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 tell you about the delivery of a document you sent. They are sent only if your participant is set up for them. Expected values are:

  • Acknowledgement (AB) is sent when an outbound document has been validated and is in the queue for sending (the same moment as the outbound deliveryNotified webhook event), if your participant is set up for both acknowledgements and acceptances. If an AP arrives before it, ignore the AB.
  • Accepted (AP) is sent when an outbound document has been handed over to the receiver's provider. Where the network confirms receipt later, as in Slovakia, the AP comes before that confirmation. Consider it a final state.
  • Rejected (RE) is sent when delivery of an outbound document has finally failed. The message states the reason. Consider it a final state, unless the message is later retried manually.

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 are extended application responses, described below. When used in tax reporting, only Accepted (AP) or Rejected (RE) is sent, when the tax authority answers.

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 (eMLRs), 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 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>

An application response document is used because it is widely supported, and UBL 2.x has no 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.

What response messages to expect

For outbound delivery of an invoice or a credit note (your original message), you should expect:

  • MLRs (with a reference to the original message), only if your participant is set up for them: an Acknowledgement when the message is validated and ready for sending, and an Accept when it is handed over to the receiver's provider.
  • If tax reporting is enabled, an outbound MLA message for the tax report.
  • An eMLR (with a reference to the MLA message): an Accept or Reject when the tax authority has answered. In Croatia this usually happens within a minute. For Slovakia, see Tax reporting in Slovakia.

For inbound delivery of an invoice or credit note, you should expect:

  • An MLA to be created when the invoice is received.
  • An eMLR (with a reference to the MLA message), as for outbound: an Accept or Reject.

When something fails:

  • A validation failure is reported on the submit call, or as a status change of the message to failed.
  • A delivery failure produces a Reject MLR when delivery has finally failed, only if your participant is set up for MLRs.
  • A tax report that can't be sent produces a Reject eMLR. In rare cases manual handling delays it.
  • If the tax authority never answers, no eMLR arrives.

Accept and Reject are final. Rejected messages must be corrected.

If you use webhooks, the status change on the original message is also sent as a status event. Its properties carry the main values from the MLA and the eMLR, such as jurisdiction and errorCode, and actionMessageId is the message identifier of the MLA. You don't have to parse the eMLR to learn the outcome.

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>Porezna 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

General

When submitting an invoice with POST /messages/create-business-transaction or with JSON metadata, full transparency is gained through proper error handling and processing:

  • When a participant is not registered
    • The default behaviour is to return an error message "party not found" and a message is not found.
    • By specifying an "allow no dispatch" service, the message is created anyway.
    • By specifying a fallback e-mail address, an e-mail can be delivered instead.

Interactions with Tax Administration

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

📘

Croatia

Fiscal actions such as "register rejection" and "register payment" differ from one country to the other . The example below is for fiscal actions in use in Croatia.

📘

Slovakia

For Slovakia, only Register fiscal document is applicable, other actions are not supported.

---
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 (Croatia)

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 for Croatia, other error codes may be applicable for Slovakia, France, etc.):

  • 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 (Croatia)

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)

Tax reporting in Slovakia

In Slovakia, only the seller's provider reports. Unimaze reports each valid invoice and credit note where you are the seller: the ones you send, and the self-billed ones you receive (to be confirmed). Only domestic invoices that carry the seller's VAT identifier (IČ DPH) are reported. This is specific to Slovakia: in Croatia both sides report. The report is a Tax Data Document, sent over the network to the tax authority, which answers with a message level status.

The service creates an extended Application Response (MLA) in your account, with these document identifier variables:

  • Jurisdiction: Slovakia
  • Role: Supplier
  • RequestAction: RegisterFiscalEvidence

The Tax Data Document is embedded in the MLA. The MLA's document number is <invoice number>-RegisterFiscalEvidence, and its status follows the submission to the tax authority.

When the tax authority answers, you receive an Accepted or Rejected eMLR, which refers to both the MLA and the invoice. It links to the request and embeds the tax authority's response. On acceptance, the invoice's taxReportingStatus changes from none to electronic.

The eMLR's document number ends in :Accepted or :Rejected. It is an inbound message: fetch it and mark it as delivered like any other inbound message.

---
title: Tax reporting in Slovakia
---
sequenceDiagram
    participant E as ERP / SaaS partner
    participant M as Unimaze / MAPI
    participant TA as Tax authority

    M->>M: Create MLA (RegisterFiscalEvidence, Tax Data Document)
    M->>TA: Send Tax Data Document over the network
    TA->>M: Message level status
    M->>E: eMLR Accepted or Rejected (incl. tax authority response)

For the steps in your integration, see the Slovakia guide.

Register paid invoice/credit note (Croatia)

This action is triggered with POST /api/v1/messages/{messageId}/compliance/hr/register-payment, where messageId is the invoice you issued. It creates a message with the reference number <invoice number>-RegisterPayment, for tracking. For the request body, see Supplier must register a payment.

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 register-payment
    M->>M: Create request document RegisterPayment
    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 POST /api/v1/messages/{messageId}/compliance/hr/register-rejection, where messageId is the invoice you received. It creates a message with the reference number <invoice number>-RegisterRejection, for tracking. For the request body and the rejection business message, see Customer may register a rejection.

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 register-rejection
    M->>M: Create request document RegisterRejection (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 1 day ago

Did this page help you?