The Messaging API helps you implement sending or receiving electronic business documents to your business partners. Using MAPI, for example, a supplier can send an invoice to their customer, while a customer can issue an order to their supplier or retrieve an invoice sent to them.

Our goal is to make exchanging electronic business documents as easy and straightforward as possible. The API is suited for all developers regardless of their level of expertise in the field of electronic invoicing and relevant business frameworks.

Start by learning more about Transactions and how to send an electronic business document generated from metadata. The requests are authenticated using HTTP Basic Authentication.

The quickest way to try out the Messaging API is through Postman, a flexible and comprehensive tool for developing and testing APIs.

Download a copy of our Postman collection by clicking the following button:

To learn more about how Postman can assist you in implementing MAPI, go to Implementing MAPI: C#, Java, Python, PHP, Ruby, Node.js, jQuery.

For further information, contact us at info [at] unimaze [dot] com.

If you are new to the domain of electronic invoicing and procurement and the exchange of standardized business documents, the following section offers an overview of few of the key concepts used in the Messaging API.

A message is an envelope that wraps the business documents that you want to transfer to your business partners. Each message has a unique identifier that is used for tracking and handling message and document data. For example, this identifier is used for attaching new documents to the message (POST /messages/:mid/documents) and retrieving the status of the message after the message has been handed over to the server (GET /messages/:mid).

The additional message information, such as the business transaction group, business profile, and document validation details, ensures that the receiving party can correctly process and import the data.

There are three ways to construct or parse messages. Choose the approach depending on what type of business document you want to send or receive and on how familiar you are with different document standards:

• Implement using metadata The recommended approach. This method uses JSON metadata to abstract different document syntax formats and performs automatic conversion. It is the easiest to implement and has the best standards compliance.
• Implement natively Using this method, you need to create or parse native data in XML format and make separate implementation for each document syntax format that you want to support.
• Implement as raw documents This lets you send any kind of document as the core document, such as PDF files, images, or even XML or EDIFACT documents.

Learn more about the following:

Generate business documents from metadata

• We recommend using this approach as it is not necessary to verify which documents your business partner is able to process and the correct document standard is selected automatically.
• This group of calls (Transactions) relies on metadata to generate a valid XML or EDIFACT document.
• To successfully create a business document through one of these calls, the metadata must be correctly formatted and include the minimum required elements.

Submit XML documents

• If you have knowledge and experience working with business document specifications, this approach lets you implement the chosen document specification in its native format.
• We are here to assist you—our system validates the documents when submitting them to ensure that they conform to the chosen business profile.
• This approach (POST /messages/create-business-transaction) requires an XML document that has been formatted according to the corresponding document specification, as defined by the relevant business profile.

Submit any document

• If the document that you want to send is not defined as a transaction or formatted according to the configured business specifications, use the POST /messages/create-message call.
• A greater flexibility allows you to send scanned business documents or any additional content that does not comply with one of the supported document specifications.
• Keep in mind that, because this type of exchange is not predefined by a business profile, the message envelope must specify how the documents should be handled. Since the exchange parameters are not standardized, the sender and the receiver need to agree on the conditions to prevent issues during message processing and delivery.

The API returns conventional HTTP status codes. Successful requests have status codes in the 2xx range. Failed requests return status codes in the 4xx range.

Some API calls also return a JSON response body containing a relevant message object or document payload.

HTTP Status codes

Here is a summary of the HTTP status codes that the Messaging API returns:

Status code	Description
200 OK	The request was successful.
201 Created	The resource has been successfully created or retrieved.
400 Bad Request	The request could not be processed due to incorrect or missing parameters or payload data.
401 Unauthorized	The authentication credentials provided are not valid.
403 Forbidden	The authenticated user does not have permission to view the requested resource.
404 Not Found	The resource required does not exist.
415 Unsupported Media Type	The content type provided is not supported by the server.
422 Unprocessable Entity	The request was well formed but could not be processed.

Generally, when response status codes 2xx are returned, the API call was successful. We recommend restricting access and using validations when implementing the Messaging API so that users do not encounter 4xx HTTP status codes. However, the user message in a 422 response can be displayed directly to the user.

User messages

If a user message needs to be shown to the user, the following JSON format is returned:

{
    "statusCode": "422",
    "statusText": "UnprocessableEntity",
    "message": "Could not find transaction group 'SubmitData'"
}

Error messages

For 400 Bad Request errors, the Messaging API returns error messages in JSON format that provide additional information regarding the error. The error message indicates which part of the request needs to be modified before repeating the request.

For example, if no document is provided when making a call that uploads document data and creates a message, you get the following error message:

{
    "Name": [
        "The Name field is required."
    ]
}

That is also the case for response status codes that signal incorrect use of the API, such as 405 Method Not Allowed.

The message identifier (mid) is always in the format of a globally unique identifier (GUID or UUID), for example, c34ed79d-e411-4001-b20c-5ef6eede4dfb.

Before creating a new message, the sender's back-end system must generate and store the message identifier. Most programming languages can generate a random GUID. For more information, see how to create a GUID in C#, Java, or Python. You can also find online generators, such as this Online GUID generator.

Participants are identified using an ISO identifier in the following format: {Type}:{Identifier}.

Identifiers are crucial for determining sending and receiving participants.

To check which identifier types are supported, see the ISO 6523 ICD list. The identifier type corresponds to the code of the identifier in the list.

There are three key steps in correctly sending and handling outbound messages:

1. Creating the message. Messages are created by uploading business document data and providing the information necessary for message processing and delivery. Depending on the format of the document and your needs, we offer three approaches, as described in Creating messages.
2. Adding more documents to the message. This step is optional. Users can add as many attachments as needed. The message processing does not start until all documents have been uploaded.
3. Monitoring the message processing status. After the message has been delivered to the sender's outbox, its status is set to received. The message status must then be updated accordingly until delivered.

The Messaging API supports three different ways of creating messages. Each group of calls takes a different type of data, both in terms of document format and content.

The following section should help guide you through successfully creating new messages.

Create using metadata

The calls using the Transactions resource create a business document from the metadata structure in the correct syntax format based on the information about the receiver's ability to handle different document specifications. These calls are the following:

• POST /transactions/submit-order
• POST /transactions/submit-invoice
• POST /transactions/correct-with-credit
• POST /transactions/submit-payment-notification
• POST /transactions/submit-billing-response
• POST /transactions/request-quotation
• POST /transactions/submit-quotation

You submit the metadata as the request body payload in JSON format.

If the receiver is not able to receive any of the formats that they support or any documents electronically at all, the document is delivered to the provided receiver's email address.

For more detailed instructions on how to prepare metadata correctly, see Metadata. Full metadata examples in JSON format can be found in the description for each call.

Metadata

The following section should help you provide all the necessary information in the metadata.

Message handling

We rely on the information from the messageHandling section to make sure that the business document is delivered to your business partner.

• receiverIdentifier: Must be set to the party identifier of the receiver. The format is {Type}:{Identifier}, where Type is the type of the party identifier, and Identifier is the identifier value. When you are sending an order, a remittance advice, or a quotation request, receiverIdentifier must match the identifier of the supplier. For invoices, credit notes, and quotations, this is the identifier of the customer. For billing responses, it corresponds to the identifier of the receiver, which is always the issuer of the invoice or the credit note (the seller).
• fallbackEmailAddress: Must be a valid email address.
• fallbackContactName: Optional but recommended.

Document references

For invoices and credit notes, the billingReferences section lets you specify the invoices and credit notes related to the document that you want to create. The order based on which the billing document was made can be referenced in orderReference.

In the BISENUBL syntax, invoices must include one of these two elements:

• orderReference: A reference to the relevant purchase order. Comprises the identifying number of the order and its issue date.
• buyerReference: An internal identifier of the buyer.

The documentReferences section is reserved for other types of associated documents, such as despatch advice, contract, and more. However, although supported in the BISENUBL document specification, keep in mind that this type of references might not be represented in other syntaxes.

In billing responses, documentReference refers to the relevant invoice or credit note in response to which the billing response has been sent.

In quotations, the quotationRequestReference section is used to indicate the relevant quotation request.

Supplier and customer details

The customer and supplier sections include information about the company name, its ISO identifier, postal address, and contact details. The required elements depend on the document type.

• identifier: The ISO identifier of the party. Always follows the same format: {Type}:{Identifier}, where Type is the type of the identifier and the identifier value is provided in Identifier.
• vatNumber: The VAT number of the supplier is required in invoices and credit notes.
• countryCode: Must comply with the ISO 3166 standard.
• contact: Contact details are optional.

Address information

You can specify the address of the sender or the receiver in one of the two ways:

1. Using structured data.

   In this case, each address element is provided using a specific property: StreetNameAndAddress, City, PostalZone, CountryCode.

   If needed, any additional information is supplied using AddressLine2 and AddressLine3 properties, as shown in the example.

   "address": {
       "streetNameAndNumber": "42nd Street 1",
       "city": "New York",
       "addressLine2": "PO Box 45",
       "postalZone": "10036",
       "countryCode": "US"
   }

2. Using unstructured data.

   You can also set address information using StreetNameAndAddress, AddressLine2, AddressLine3, and CountryCode. In this case, AddressLine2 and AddressLine3 contain freely-structured text, as shown in the following example.

   "address": {
       "streetNameAndNumber": "42nd Street 1",
       "addressLine2": "PO Box 45, 10036 New York",
       "countryCode": "US"
   }

Line information

• itemNo and name: These properties are used for identifying items. In orderLines, only one of the two properties is required, but you can also set both of these values. In invoiceLines and creditNoteLines both the item number (itemNo) and the name of the item (name) are required. In quotationLines, if you are not using commodityClassification, you need to supply both properties.
• taxCategoryType, taxableAmount, taxAmount, taxPercentage: In invoices and credit notes, all tax information is required. In orders, tax information can be omitted. However, if you provide one of these elements, you need to provide all four.
• taxCategoryType: Must use one of these values: StandardRated, ReducedRated, ZeroRated, Exempt, NotSubjectToVat.
• quantity: Integer.
• unitOfMeasure: In unitOfMeasure, the unit property must use one these values: One, Piece, Kilogram, Rec20, Rec21, Month, Package, Year, Day, Hour, Kilometre, Metre, Litre, SquareMetre, CubicMetre, Tonne, KiloWattHour. If unit is set to Rec20 or Rec21, you need to set the code property too. For more information about accepted values, see Unit of measure.
• unitPriceAmount: Integer.
• taxableAmount: Integer.
• taxPercentage: Integer. Do not add a percent sign.
• discountValue: Requires a number provided as a string. To set a percentage discount, the numeric value must include a percent sign. To set a fixed discount amount, provide only a numeric value.
• prepaidAmount: Integer, optional.
• payableAmount: Integer, optional. If provided, the value must be correctly stated, otherwise an error is returned that indicates the expected amount. If the value is not provided, it is calculated based on the line information.
• currencyCode: Must adhere to the ISO 4217 standard. If that is not the case, a document validation error occurs.

In billing responses, the following properties need to use specific values:

• status: Refers to the processing status of the business document. These are the possible values: MessageAcknowledgement, Accepted, Rejected, InProcess, UnderQuery, ConditionallyAccepted, Paid. To learn more, see Billing response elements.
• reason: Supplies additional information about the document status by defining the issue reported. Use one of the following values: NoIssue, ReferencesIncorrect, LegalInformationIncorrect, ReceiverUnknown, ItemQualityInsufficient, DeliveryIssues, PricesIncorrect, QuantityIncorrect, ItemsIncorrect, PaymentTermsIncorrect, NotRecognized, FinanceIncorrect, Other. To find out more, see Billing response elements.
• actions: Indicates what the receiver needs to do to correct the issue reported. In actions, type must have one of these values: NoActionRequired, ProvideInformation, IssueNewInvoice, CreditFully, CreditPartially, CreditTheAmount, Other. For more information, go to Billing response elements.

In quotation requests, different parameters can be mandatory depending on whether the customer creates a quotation request based on the supplier's catalog or not. To learn more, go to Quotation request: Use cases.

When a quotation is created based on a quotation request that was delivered through the application, the quotation needs to reference that quotation request. For more information, see Quotation: Use cases.

Create as a transaction

The POST /messages/create-business-transaction call takes a business document in raw format and requires that you check the receiving capabilities of your business partner before making the request. The document must be formatted according to a business document specification and must be an XML (text/xml) document.

To check which document syntax the receiver understands, use the GET /parties/:pid/transactions call. This retrieves a list of all business transactions that a participant supports for a specific business transaction type (for example, SubmitInvoice), such as this one:

[
    {
        "uniqueId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
        "profileId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
        "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
        "transactionKeyName": "BISENUBL-3.0 SubmitInvoice",
        "profileKeyName": "BISENUBL-3.0",
        "documentIdentifier": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "willBeTransformed": false
    },
    {
        "uniqueId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
        "profileId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
        "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
        "transactionKeyName": "BISENCII-3.0 SubmitInvoice",
        "profileKeyName": "BISENCII-3.0",
        "documentIdentifier": "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100::CrossIndustryInvoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::D16B",
        "willBeTransformed": false
    },
    {
        "uniqueId": "urn:www.cenbii.eu:profile:bii05:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0",
        "profileId": "urn:www.cenbii.eu:profile:bii05:ver1.0",
        "customizationId": "urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0",
        "transactionKeyName": "BII05-1.0 SubmitInvoice",
        "profileKeyName": "BII05-1.0",
        "documentIdentifier": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0::2.0",
        "willBeTransformed": true
    }
]

To successfully execute the POST /messages/create-business-transaction call, you need a valid XML document that fulfills the syntactic and semantic requirements of the corresponding business profile. In other words, the document must be correctly formatted and contain all the required elements, and the information provided must comply with the predefined norms.

Create as a generic message

If you need to send a different kind of document, such as an EDIFACT (text/plain) document, use the POST /messages/create-message call.

The documents sent this way do not undergo validation. This lets you send images or business documents that do not follow a strict document structure.

However, the sender and the receiver must agree on the message envelope parameters to be able to exchange the document.

These parameters, such as service and action, contain information about how the document needs to be processed.

Messages contain at least one document, which is called core processing document. Submitting additional documents is possible after the message core document has been added. This is done using the POST /messages/:mid/documents call.

Controlling whether additional documents can be added or not is achieved through the more parameter. The parameter is used in the initial call when creating the message and in subsequent calls when adding documents to the same message.

If the value of the parameter is set to true, you can add more attachments to the message. After the value of the parameter is set to false, no new documents can be added.

This also affects message processing because the processing does not start until the value of the parameter has been set to false.

Messages that have been submitted to the server are processed asynchronously. After a message is created on the server, its message status is one of the following:

• notset: The message is waiting for more documents to be added.
• received: The message is ready for processing.
• retrying: The message might have failed processing or validation but is pending a retry.

When the processing has been completed, the message status is set to one of these two statuses:

• delivered: The message has been successfully processed and delivered.
• failed: The message processing or delivery failed.

The outcome of the processing can be tracked using the GET /messages/:mid call.

The call returns a JSON object that contains information about the message and the business documents included in the message. The message status information is stored as the status property.

{
    "uniqueId": "99bf2d71-01c4-4fa2-9f36-87df8d6405b0",
    "timeReceived": "2019-05-29T13:07:58.127",
    "timeDelivered": "2019-05-29T13:24:54.777",
    "documentNo": "INV123",
    "status": "delivered",
    "transfer": "outbound",
    "validationStatus": "approved",
    "service": "urn:www.cenbii.eu:profile:bii05:ver1.0##CENBII-1.0",
    "action": "SubmitInvoice",
    "conversation": "190529:603727:KT:1111119999",
    "referenceInformation": "",
    "originParty": {
        "identifier": "KT:1111119999",
        "name": "Test Party One"
    },
    "destinationParty": {
        "identifier": "KT:2222229999",
        "name": "Test Party Two"
    },
    "documents": [
      {
        "index": 0,
        "name": "Invoice",
        "contentType": "text/xml",
        "encoding": "utf-8",
        "referenceId": "99bf2d7101c44fa29f3687df8d6405b0:KT:1111119999:0:6ndhnotgb5",
        "namespace": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
        "attachmentType": "Core",
        "isTransformed": false
      }
    ]
}

For more details regarding the message delivery and services processing, use the GET /messages/:mid/traces call. The call returns an array of JSON objects that each includes information about the events that occurred during the message processing.

[
    {
        "timestamp": "2019-05-29T13:07:58.19",
        "sourcePartyName": "Test Party One",
        "typeName": "CreateClosed",
        "message": "Message created (Invoice, text/xml) - ready for processing"
    },
    {
        "timestamp": "2019-05-29T13:24:54.59",
        "sourcePartyName": null,
        "typeName": "MovedToReceiverInbox",
        "message": "Message transferred to inbox of receiving party"
    }
]

When inbound messages are received and validated, they are made ready for importing into the receiver's back-end system. After the receiver's back-end system has handled the message, it notifies the messaging server of the outcome of the delivery.

The messages that are waiting to be imported have the pendingdelivery message status. Checking for pending messages is done through the GET /messages?status=pendingdelivery&transfer=inbound call. By default, the request retrieves a list of the 50 most recent messages whose message status is pendingdelivery.

You can paginate the results using the offset and limit parameters. The maximum value of the limit parameter is 100.

For parsing and processing, business documents are retrieved in their raw format, either in XML or in JSON.

When it comes to core documents, we recommend that you retrieve them using one of these calls:

• GET /transactions/submit-order?mid={mid}
• GET /transactions/submit-invoice?mid={mid}
• GET /transactions/correct-with-credit?mid={mid}
• GET /transactions/submit-payment-notification?mid={mid}

These calls retrieve the document metadata in JSON format along with the information about the message. This helps you work with different document specifications that your business partners might support without having to prepare each document separately. The correct document specification is then chosen for you when creating a message based on the information about what the receiver can process.

Documents can also be retrieved based on their type, name, or index number. To fetch the core document of a message, use the GET /messages/:mid/documents/core call. If the core document had to be transformed to another business document specification so that the receiver can process it, the transformed document in the inbound message is retrieved through the GET /messages/:mid/documents/transformed call. To get the original document that was transformed, use the GET /messages/:mid/documents/original.

For the calls that take the document index or the document name, you first need to retrieve the message using the message identifier (uniqueId). Message details are given in JSON format, such as this one:

{
    "uniqueId": "6cfa5c24-25c5-4eb4-bed5-3ed6cc6c25c5",
    "timeReceived": "2019-05-29T13:24:54.31",
    "timeDelivered": null,
    "documentNo": "",
    "status": "pendingdelivery",
    "transfer": "inbound",
    "validationStatus": "unknown",
    "service": "urn:www:nesubl.eu:profiles:profile4:ver2.0##NESUBL-2.0",
    "action": "SubmitInvoice",
    "conversation": "190529:203504:KT:1111119999",
    "referenceInformation": "",
    "originParty": {
        "identifier": "KT:1111119999",
        "name": "Test Party One"
    },
    "destinationParty": {
        "identifier": "KT:2222229999",
        "name": "Test Party Two"
    },
    "documents": [
      {
        "index": 0,
        "name": "Invoice",
        "contentType": "application/xml",
        "encoding": "",
        "referenceId": "6cfa5c2425c54eb4bed53ed6cc6c25c5:KT:1111119999:0:hvbwdczr6i",
        "namespace": "",
        "attachmentType": "Core",
        "isTransformed": false
      }
    ]
}

The GET /messages/:mid/documents/:name call requires the name of the document, which matches the value of the name property of the corresponding element in the documents array in the same JSON object. Each business document has a unique name in the context of the message in which it is contained.

The other call for importing business documents, GET /messages/:mid/documents/:idx, relies on the index number of the document. The core business document always has an index of 0, while the attachments in the same message have a higher index. The index number is stored as the index property of each document in the documents array in the message object.

To remove messages from the list of messages with the pendingdelivery status, the receiver's back-end system must change their status depending on the outcome of importing and processing.

To indicate a successful delivery, you need to change the message status from pendingdelivery to delivered. This is achieved using the POST /messages/:mid/mark-as-delivered call. If there is an issue when importing the message, the message status is set instead to failed through the POST /messages/:mid/mark-as-failed call.

Messages marked as failed can be parked or retried manually through the Messaging Server UI.

Retrying triggers a new attempt to import the message. This is useful in case that the technical or other issues that prevented the first delivery attempt have been successfully fixed.

Parking a message typically indicates that the issue encountered has been resolved in some other way. For example, it might mean that the business document has been sent in another message, transmitted through email, or printed and delivered through the post. You need to provide a reason for parking the message, which facilitates document tracking.

Parking failed messages is especially useful if you do not intend to import them because it lets you detect and manage these messages more easily.

After you have imported your received messages and made sure that the business documents are correctly processed, you can view the documents in their original raw form or formatted using a style sheet. Anonymous access is possible. You can view outbound documents in the same manner.

The same call (GET /messages/display/:id) is used to view both formatted and raw documents. No authorization is needed to make this request. The call requires a unique document reference identifier that is fetched together with the message information by using the GET /messages/:mid call. The document reference identifier is stored as the referenceId property.

By default, XML documents retrieved this way are converted to HTML when a style sheet is available. To view raw documents, the value of the optional ct parameter in the GET /messages/display/:id call must be set to raw.

The call also lets users convert the document to another format. This is done by setting the ct parameter to one of these options: pdf, png, jpg, gif, or tif.

The identifier used for fetching the document has the following format: {messageIdentifier(GUID)}:{partyIdentifierType}:{partyIdentifier}:{documentIndexNumber}:{passcode}. The passcode is an automatically generated token that is used for granting anonymous access to the document.

For example, if the document reference identifier has this value 5f272652dc144b1289c8a8d66dd9e0bb:KT:1111118899:2:e2rpq8r7lb, this means that the document is contained in the message whose GUID is 5f272652-dc14-4b12-89c8-a8d66dd9e0bb. The message is owned by a party whose identifier is KT:1111118899, while the document is the second attachment that the message contains besides the core processing document. Documents are indexed using a zero-based index, and the first element is always the core processing document. The final element of the identifier is the passcode.

Clicking Run in Postman imports the collection of requests into your Postman application where you can run them directly. The API Reference will help guide you through the requirements for each call.

For more information about importing the collection, see Using the Run in Postman button. For all other questions related to Postman, go to Postman Learning Center.

If you want to implement MAPI in C#, Java, Python, PHP, Ruby, Node.js, or jQuery, you can rely on Postman to generate the code for API calls. Open the call that you want to make and go to Code, then select the language that you want to use.

Copy the example request into your code and modify it as needed.

A message goes through several states during message processing and delivery and the message status changes accordingly. Some states occur as a result of internal message processing and others as a result of an API call. In certain cases, such as when a message is parked or retried, users need to make the changes manually through the UI.

The same message can have different statuses in the sender's outbox and the receiver's inbox. In both cases, the message status is tracked until it is updated to delivered, failed, or parked. These states are considered final because typically no further state changes will occur.

Outbound messages

The following diagram shows the states that the message undergoes from the sender's perspective.

After the message is pushed to the messaging server, the sender's back-end system monitors the message status until it reaches one of these states: delivered, failed, or parked.

1. A message is created through the POST /messages/create-business-transaction or any of the POST requests using the Transaction resource (see Creating messages). The message processing and delivery follow the same steps regardless of the call that was used to create the message. Whether any attachments can be submitted to the message is managed through the more parameter. This is a required query parameter used when creating messages and when adding documents. If the more parameter is set to true, the message is open and other documents can be added. Setting the value to false closes the message and prevents you from adding attachments.
2. If an additional document needs to be attached to the message, the message status is set to notset. The sender can add new documents to the message if the more parameter has been set to true in the call that was used to create the message. An attachment is uploaded using the POST /messages/:mid/documents call. The message status remains notset until all documents are added.
3. If all the documents have been added, this means that the more parameter in the last POST /messages/:mid/documents request made has been set to false. The message status is set to received and the message is ready for processing. If there were no additional documents, the message status is set directly to received.
4. If the processing and the delivery have been successful, the message status is set to delivered.
5. If the message processing and delivery have been unsuccessful, the message status is changed to retrying. This typically occurs due to external failures, such as network issues. Messages are retried until one of the retrying attempts is successful or until the maximum number of attempts is reached. If the processing and the delivery have been successful, the message status is set to delivered.
6. If the retrying attempts have been exhausted without success, the message status is set to failed. These messages can be retried or parked manually.
7. If the message's delivery is unsuccessful the status might be changed to 'pending review'. Messages with the 'pending review' status will be looked over and manually fixed if the input data is consistent.
8. Parking a message indicates that the message is not going to be delivered through the messaging server. A message can be parked from the UI if its status is failed. Parking a message might also mean that it has been delivered in another way. The user provides a reason for parking the message, which facilitates message tracking. Parked messages can also be retried.
9. Retrying a message is done from the UI when the message delivery has been unsuccessful. This changes the message status to received and triggers the delivery process again. The sender can retry a message if its message status is failed, parked, or delivered.

Inbound messages

See how messages are handled after they reach the receiver's inbox in the following diagram. The message status is used for tracking the message progress until it is set to delivered, failed, or parked, which are considered final states.

When a message reaches the receiver's back-end system, the message status is set to one of these two statuses depending on the party setup:

• pendingdelivery: This is the default configuration where an accounting system imports documents directly.
• pendingprocessing: This is used in special cases when another back-end system monitors and controls the flow of documents, for example, an invoice acceptance system, before giving control to a second system, which is typically an accounting system.

When a receiver's back-end system monitors the pendingdelivery state, it does so through the GET /messages?status=pendingdelivery&transfer=inbound call.

1. If the receiver's back-end system could not import the message, the message status must be set to failed, which is achieved through the POST /messages/:mid/mark-as-failed call. Failed messages can be parked or retried. For example, this might happen when the import implementation does not support a payment means and must be updated.
2. If the message has been imported successfully, the message status changes to delivered using the POST /messages/:mid/mark-as-delivered call. Delivered messages can be retried.
3. When there are issues during message processing or delivery, the message can be parked. Messages can be parked if their status is pendingdelivery, pendingprocessing, delivered, or failed. This can be done only from the UI. If a message has been parked, this indicates that the document has been delivered in another message or in some other way or that the issues encountered have been solved.
4. The message delivery can be triggered again if the message status is delivered, failed, or parked. To retry a message, you need to use the UI. When the delivery is retried, the message status is set again to received. For more information about the message flow from the sender's point of view, see Outbound messages.

When a receiver's back-end system monitors the pendingprocessing state, it does so through the GET /messages?status=pendingprocessing&transfer=inbound call. After it has successfully processed the message, the message status can be updated using the POST /messages/:mid/mark-as-processed call. The message status is then changed to pendingdelivery and the message will then be waiting for the second system to handle it.

Alternatively, the system can prevent the second system from processing it by setting it to delivered using the POST /messages/:mid/mark-as-delivered call.

Messages in the pendingprocessing or pendingdelivery state can be parked through the UI.

Business transaction groups are the types of business transactions. A business transaction group points to the action that should be performed on the core business document, while a business transaction refers to an implementation of a particular document syntax. For example, SubmitInvoice can refer to transactions NESP4-2.0 SubmitInvoice or BISENUBL-3.0 SubmitInvoice.

These are the three most commonly used business transactions groups:

Transaction group	Description
SubmitInvoice	The supplier issues an invoice to the customer to request payment for services or products provided. An invoice is used to specify the financial aspect following a business transaction.
SubmitOrder	The buyer places an order with a seller. The order specifies which goods or services the seller should deliver and might specify delivery conditions, discounts, and other pricing details.
CorrectWithCredit	The supplier issues a correction credit note to the customer. For example, this happens when the products delivered do not satisfy quality standards or when there is an error in the despatch advice or the invoice.

Here is a list of all the business transaction groups that are configured on the messaging server:

Transaction group	Description
AcknowledgeCatalogue	The buyer confirms that they have accepted the seller's catalogue.
AcknowledgeOrder	The seller accepts or rejects an order that they have received from the buyer.
CorrectWithCredit	The supplier issues a correction credit note to the customer. For example, this happens when the products delivered do not satisfy quality standards or when there is an error in the despatch advice or the invoice.
CorrectWithDebit	The customer issues a correction invoice to the supplier, for example, in case when the despatch advice does not correspond to the products received or when the products do not satisfy quality standards.
PunchOutCatalogue	The buyer sends to the seller a list of products or services that was created through the seller's procurement system or online catalogue.
RequestQuotation	The customer requests a quotation from the supplier.
SubmitCatalogue	The seller submits a catalogue to the buyer or a potential buyer.
SubmitDocument	The sender transmits an additional document to the receiver.
SubmitInvoice	The supplier issues an invoice to the customer to request payment for services or products provided.
SubmitBillingResponse	The buyer sends to the seller an informative message regarding the status of the invoice or the credit note that the buyer's system is processing.
SubmitMessageResponse	The receiver sends a message level response (MLR) in case the sender has requested feedback about the validation status of the message that they issued. The message level response contains details regarding the validation.
SubmitOrder	The buyer places an order with a seller.
SubmitOrderResponse	The seller accepts or rejects an order that they have received from the buyer.
SubmitPackingNote	The seller sends a packing note or a despatch advice to the buyer. The document defines the delivery conditions and confirms that the items have been despatched.
SubmitPaymentNotification	The customer sends a remittance advice to the supplier to notify them that their invoice or credit note has been paid.
SubmitPaymentReminder	The seller submits a reminder to the customer that their payment is due.
SubmitQuotation	The supplier sends a quotation to the customer for the items or services requested.
SubmitUtilityStatement	The supplier issues a utility statement to the customer. The document accompanies an invoice or a credit note and provides details regarding utility services expenditure (electricity, gas, water, telephone).

Business profiles are contracts for business collaboration. Each profile comprises of one or more business documents used in the collaboration, generally using the same syntax. For example the NESP4-2.0 business profile defines the transaction NESP4-2.0 SubmitInvoice (an invoice), but the BISENUBL-3.0 business profiles defines two transactions, BISENUBL-3.0 SubmitInvoice (an invoice) and BISENUBL-3.0 CorrectWithCredit (a credit note).

When a participant supports handling of a particular business profile (either sending or receiving), it should support handling all transactions (documents) within the business profile.

SubmitInvoice

Profile key name	Internal transaction identifier	Document syntax
BISENUBL-3.0 (FUT TS-236)	...	UBL 2.1 Invoice
BISENCII-3.0	...	CrossIndustryInvoice
BIS4A-2.0	...	UBL 2.1 Invoice
BIS5A-2.0	...	UBL 2.1 Invoice
BIEHF4A-2.0	...	UBL 2.1 Invoice
BIEHF5A-2.0	...	UBL 2.1 Invoice
BISXY-2.0	...	UBL 2.1 Invoice
BII04-1.0 (FUT TS-136)	urn:www.cenbii.eu:profile:bii04:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0	UBL 2.0 Invoice
BII05-1.0 (FUT TS-137)	urn:www.cenbii.eu:profile:bii05:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0	UBL 2.0 Invoice
BII06-1.0	urn:www.cenbii.eu:profile:bii06:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm010:ver1.0	UBL 2.0 Invoice
BIS4A-2.0	urn:www.cenbii.eu:profile:bii04:ver2.0##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0	UBL 2.0 Invoice
NESP4-2.0 (FUT TS-135)	urn:www.nesubl.eu:profiles:profile4:ver2.0##NESUBL-2.0	UBL 2.0 Invoice
NESP5-2.0	urn:www.nesubl.eu:profiles:profile5:ver2.0##NESUBL-2.0	UBL 2.0 Invoice
NESP8-2.0	urn:www.nesubl.eu:profiles:profile8:ver2.0##NESUBL-2.0	UBL 2.0 Invoice
OIO-NESP5-2.02	urn:www.nesubl.eu:profiles:profile5:ver2.0##OIOUBL-2.02	UBL 2.0 Invoice
OIO-BS-1.0-2.02	Procurement-BilSim-1.0##OIOUBL-2.02	UBL 2.0 Invoice
OIO-BSR-1.0-2.02	Procurement-BilSimR-1.0##OIOUBL-2.02	UBL 2.0 Invoice
OIO-OABS-1.0-2.02	Procurement-OrdAdv-BilSim-1.0##OIOUBL-2.02	UBL 2.0 Invoice
OIO-OSRBS-1.0-2.02	Procurement-OrdSimR-BilSim-1.0##OIOUBL-2.02	UBL 2.0 Invoice
OIOXML	OIOXML.*##OIOXML	OIOXML Invoice

CorrectWithCredit

Profile key name	Internal transaction identifier	Document syntax
BISENUBL-3.0 (FUT TS-236)	...	UBL 2.1 CreditNote
BISENCII-3.0	...	CrossIndustryInvoice
BIS5A-2.0	...	UBL 2.1 CreditNote
BIEHF5A-2.0	...	UBL 2.1 CreditNote
BISXY-2.0	...	UBL 2.1 CreditNote
BISXY-2.0	...	UBL 2.1 CreditNote
BII05-1.0 (FUT TS-137)	urn:www.cenbii.eu:profile:bii05:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm014:ver1.0	UBL 2.0 CreditNote
BII06-1.0	urn:www.cenbii.eu:profile:bii06:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm014:ver1.0	UBL 2.0 CreditNote
NESP5-2.0	urn:www.nesubl.eu:profiles:profile5:ver2.0##NESUBL-2.0	UBL 2.0 CreditNote
NESP8-2.0	urn:www.nesubl.eu:profiles:profile8:ver2.0##NESUBL-2.0	UBL 2.0 CreditNote
OIO-NESP5-2.02	urn:www.nesubl.eu:profiles:profile5:ver2.0##OIOUBL-2.02	UBL 2.0 CreditNote
OIO-BS-1.0-2.02	Procurement-BilSim-1.0##OIOUBL-2.01	UBL 2.0 CreditNote
OIOXML	OIOXML.*##OIOXML	OIOXML CreditNote

CorrectWithDebit

Profile key name	Internal transaction identifier	Document syntax
BII05-1.0 (FUT TS-137)	urn:www.cenbii.eu:profile:bii05:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm015:ver1.0	UBL 2.0 Invoice
BII06-1.0	urn:www.cenbii.eu:profile:bii06:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm015:ver1.0	UBL 2.0 Invoice
NESP5-2.0	urn:www.nesubl.eu:profiles:profile5:ver2.0##NESUBL-2.0	UBL 2.0 Invoice
NESP8-2.0	urn:www.nesubl.eu:profiles:profile8:ver2.0##NESUBL-2.0	UBL 2.0 Invoice
OIO-NESP5-2.02	urn:www.nesubl.eu:profiles:profile5:ver2.0##OIOUBL-2.02	UBL 2.0 Invoice

DisputeInvoice

Profile key name	Internal transaction identifier	Document syntax
NESP8-2.0	urn:www.nesubl.eu:profiles:profile8:ver2.0##NESUBL-2.0	UBL 2.0 ApplicationResponse

SubmitStatement

Profile key name	Internal transaction identifier	Document syntax
FUT-TS140	urn:X-www.stadlar.is:profile:ts140:ver2013##urn:www.cenbii.eu:transaction:BiiCoreTrdm026:ver2.0	UBL 2.1 Statement

SubmitCatalogue

Profile key name	Internal transaction identifier	Document syntax
FUT-TS139	urn:X-www.stadlar.is:profile:ts139:ver2013##urn:X-www.cenbii.eu:transaction:BiiCoreTrdm019:ver2.0	UBL 2.1 Catalogue
NESP1-2.0	urn:www.nesubl.eu:profiles:profile1:ver2.0##NESUBL-2.0	UBL 2.0 Catalogue

SubmitOrder

Profile key name	Internal transaction identifier	Document syntax
BIS3A-2.0	...	UBL 2.1 Order
BII03-1.0 (FUT TS-138)	urn:www.cenbii.eu:profile:bii03:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm001:ver1.0	UBL 2.0 Order
BII06-1.0	urn:www.cenbii.eu:profile:bii06:ver1.0##urn:www.cenbii.eu:transaction:biicoretrdm001:ver1.0	UBL 2.0 Order
NESP3-2.0	urn:www.nesubl.eu:profiles:profile3:ver2.0##NESUBL-2.0	UBL 2.0 Order

SubmitUtilityStatement

Profile key name	Internal transaction identifier	Document syntax
OIO-RU-1.0-2.02	Reference-Utility-1.0##OIOUBL-2.02	OIOUBL 2.0 UtilityStatement-2

SubmitDocument

Profile key name	Internal transaction identifier	Document syntax
EDI	EDIFACT	(text)

In billing responses there are three key elements that need to be specified in accordance with the corresponding code lists. Here you can find more information about the values accepted for each element.

Status

The status element is validated against the Invoice status code (UNCL4343 Subset) list.

You need to use one of the following values:

Value	Description
MessageAcknowledgement	The buyer confirms that they have received an invoice or a credit note that they can further process.
Accepted	The buyer has accepted the offer and the seller can expect payment from the buyer.
Rejected	The buyer has rejected the offer because they cannot process the invoice further. Rejecting an invoice does not necessarily mean that the transaction is rejected as well, even though that might be the case.
InProcess	The buyer's system is processing the invoice.
UnderQuery	The invoice processing has been suspended until the buyer receives additional information from the seller. This typically means that the document contains incorrect information or is missing key details.
ConditionallyAccepted	The buyer accepts the invoice provided that the conditions stated in the billing response are met. The buyer indicates these conditions in the reasonDescription property. If the seller does not dispute the terms, the invoice can be paid.
Paid	The buyer has paid the invoice.

Reason

The reason element accepts the values defined in the Status Clarification Reason (OpenPEPPOL) list.

The values are as follows:

Value	Description
NoIssue	The document can be processed correctly and there are no issues encountered.
ReferencesIncorrect	The document is missing the references that the buyer requested for successful document handling.
LegalInformationIncorrect	The information contained in the document does not meet the necessary legal requirements.
ReceiverUnknown	The receiving party could not be found.
ItemQualityInsufficient	The quality of the items does not fulfill the expected standards.
DeliveryIssues	The receiver does not agree with the delivery conditions or takes issue with the delivery that has already been carried out.
PricesIncorrect	The prices stated in the document differ from the prices previously agreed.
QuantityIncorrect	The quantity does not correspond to the prior agreement.
ItemsIncorrect	The items are missing or incorrectly specified.
PaymentTermsIncorrect	The payment terms do not conform to the agreed transaction terms.
NotRecognized	The transaction is not recognized as valid.
FinanceIncorrect	The finance terms are not stated correctly according to the agreement made between the seller and the buyer.
Other	Any other reason that does not fit the given categories.

Action

To specify which actions the buyer expects from the seller in order to resolve the reported issues, use the actions array.

The actions element comprises two properties, type and description. The type property must be provided according to the Status Clarification Action (OpenPEPPOL) list, as described in the following table:

Value	Description
NoActionRequired	No further action is necessary.
ProvideInformation	The buyer requests the seller to provide the missing or erroneous information.
IssueNewInvoice	The buyer requests the seller to issue a new invoice after correcting the issues.
CreditFully	The invoice needs to be cancelled using a credit note.
CreditPartially	The seller needs to issue a credit note covering one portion of the total costs that the buyer paid.
CreditTheAmount	The total amount on the invoice needs to be refunded without issuing a credit note.
Other	Any other action that is not determined by the given action categories.

The purpose of sending a billing response is to inform the seller about the progress of the invoice processing in the buyer's system. A billing response is supposed to be issued within three working days after receiving an invoice. In return, depending on the use case, the seller is supposed to issue a new business document, supply additional information, or take no further action. How the seller handles the action is out of scope and must be managed externally.

The following section outlines the most common use cases in which a billing response is issued. The examples provided for each use case demonstrate how to specify the necessary information in the JSON metadata when sending a billing response.

1. Invoice is being processed.

   The buyer has received the invoice but is unable to provide a definite response before the maximum response time expires. The maximum response time is three working days following the receipt of the invoice. However, the seller should not contact the buyer until another three working days have passed.

   In this case, the buyer issues a billing response with the InProcess status within three days of receiving the invoice. The buyer then needs to issue another billing response when the invoice has finished processing.

   This does not cover the billing responses with the Other status.

   "status": "InProcess"

2. Invoice is being processed with additional reference data.

   The buyer has received the invoice and wants to provide additional information to the seller without prompting any other action from the seller. For example, this can be the invoice receipt date or the invoice reference in the buyer's system. The billing response status is InProcess.

   When providing additional information in the billing response metadata, the date when the invoice was received is specified as effectiveDate. For information such as the internal invoice reference identifier, use the details element. In details, the type property stores a description of the information shared while the value property contains the information itself.

   The expected course of action on the seller's side is defined in the actions array, where type is the action (NoActionRequired) and description might include additional details about the action.

   "issueDate": "2019-11-07",
   "status": "InProcess",
   "effectiveDate": "2019-11-06",
   ...
   "details": [
     {
       "type": "Buyer process reference",
       "value": "INV-191186"
     }
   ],
   "actions": [
     {
       "type": "NoActionRequired"
     }
   ]

3. Invoice is being processed but is put on hold.

   The buyer has received the invoice but could not complete the processing because of an issue with the invoice or the business process. This can occur in cases when the buyer was unable to validate the invoice reference number or when the goods have not yet been delivered.

   The buyer then lets the seller know that the processing will be continued after updating the invoice details or after the shipment arrives. In the billing response metadata, the date when the invoice processing will resume is specified as effectiveDate. The billing response status is InProcess and the additional information regarding the status is given in reasonDescription.

   "issueDate": "2019-11-11",
   "status": "InProcess",
   "effectiveDate": "2019-11-25",
   ...
   "reasonDescription": "We are awaiting the delivery of the items."

4. Invoice is accepted.

   The buyer has accepted the invoice and the seller can expect that the invoice will be paid on time. No additional information needs to be provided and the billing response status is Accepted.

   "issueDate": "2019-11-04",
   "status": "Accepted"

5. Invoice is rejected.

   The buyer has rejected the invoice and provided only a textual description of the issue, for example, PO reference is missing. This means that the buyer has not requested any action from the seller. In the billing response metadata, a description is specified in the reasonDescription property.

   To get any further information or resolve the issue, the seller can communicate with the buyer outside of the application. The billing response has the Rejected status.

   "issueDate": "2019-11-07",
   "status": "Rejected",
   ...
   "reason": "ReferencesIncorrect",
   "reasonDescription": "The purchase order reference is missing."

6. Invoice is rejected and a reissue is requested.

   The buyer has rejected the invoice and requires that the matter is resolved by issuing the invoice again after corrections are made.

   For example, an invoice can be rejected because it does not state the relevant purchase order. The buyer might not need a credit note if the incorrect invoice has not been booked. In that case, the buyer indicates that the billing response status is Rejected.

   In the billing response metadata, the reason for the status is supplied in the reason property (ReferencesIncorrect). The required action is specified in the type property in the actions array (IssueNewInvoice). Optionally, the buyer can describe the problem in more details using the description property in actions.

   "issueDate": "2019-11-07",
   "status": "Rejected",
   ...
   "reason": "ReferencesIncorrect",
   ...
   "action": [
     {
       "type": "IssueNewInvoice"
     }
   ]

7. Invoice is rejected and a replacement is requested.

   The buyer has rejected the invoice that has already been booked in the buyer's system. The buyer then requests a credit note for the incorrect invoice and a new invoice.

   The billing response status is then set to Rejected with the explanation specified in the reason property in the billing response metadata. For example, if the invoice is rejected because a reference to the purchase order is missing, reason has the value of ReferencesIncorrect.

   The actions expected from the seller are defined in the actions array. When requesting a credit note, the first type property in actions is assigned the value of CreditFully. The second type property in the array is set to IssueNewInvoice. Any further clarifications (description) are optional.

   "issueDate": "2019-11-07",
   "status": "Rejected",
   ...
   "reason": "ReferencesIncorrect",
   ...
   "action": [
     {
       "type": "CreditFully"
     },
     {
       "type": "IssueNewInvoice"
     }
   ]

8. Invoice is conditionally accepted.

   The buyer can conditionally accept the invoice while proposing new terms. For example, this can happen if the invoice due date is different from the one previously negotiated between the buyer and the seller.

   In the invoice metadata, the status property needs to be set to ConditionallyAccepted and the reason property to PaymentTermsIncorrect. The buyer can also add more details in reasonDescription.

   The updated payment terms are suggested using the details property. In the array, type refers to the element, for example BT-9 or Invoice due date, while value contains the new value of the element. In the example, value would be set to the new payment date.

   In case of disagreement with the new payment terms, the seller needs to reach the buyer outside of the application. Otherwise, no action is necessary.

   "issueDate": "2019-10-29",
   "status": "ConditionallyAccepted",
   ...
   "reason": "PaymentTermsIncorrect",
   "details": [
     {
       "type": "BT-9 (Due date)",
       "value": "2019-12-13"
     }
   ]

9. Invoice is under query due to missing or incorrect information.

   The buyer requests additional information from the seller to be able to continue processing the invoice. The billing response status is UnderQuery and the buyer provides the date on which the invoice processing was put on hold (effectiveDate in the billing response metadata). This facilitates handling any delays in payment that might occur due to longer processing.

   For example, if the invoice is missing a purchase order reference, the reason property in the metadata needs to be set to ReferencesIncorrect. The clarification for this is given in the details array. The buyer indicates the missing element in the type property, for example, BT-13 or Purchase order reference, and suggests the correct value as the value property, for example, PO1911548.

   Given that the seller needs to communicate the missing information to the buyer, the type property in the actions array must have the value of ProvideMissingInformation. The buyer can add any other information in the description property in actions.

   "issueDate": "2019-11-24",
   "status": "UnderQuery",
   "effectiveDate": "2019-11-23",
   ...
   "reason": "ReferencesIncorrect",
   "details": [
     {
       "type": "BT-13 (Purchase order reference)",
       "value": "PO1911548"
     }
   ],
   "actions": [
     {
       "type": "ProvideInformation"
     }
   ]

10. Invoice is under query due to incorrect details and a partial credit note is requested.

    The buyer has put the invoice processing on hold until the information in the invoice is corrected and a partial refund is issued. For example, this can occur if the quantity stated on the invoice and the quantity delivered do not match. The buyer resumes the processing after receiving a partial credit note.

    In the billing response metadata, the status property is set to UnderQuery. The clarification of the status is specified in reason as DeliveryIssues and a more detailed description of the status is given in reasonDescription.

    Finally, the buyer defines the action that the seller needs to take in the actions array. Here, the seller is supposed to issue a credit note that covers a part of the total costs. The type property in actions is then set to CreditPartially. The buyer also has the option of providing more details, such as contact information, in the description property of the same array.

    "issueDate": "2019-11-24",
    "status": "UnderQuery",
    "reason": "DeliveryIssues",
    "reasonDescription": "For item with the item number VH5Y11LA7P (line no. 3 in the invoice) the ordered and invoiced quantity was 6 units. We have received only 5 units. Please issue a credit note for the missing item.",
    "actions": [
      {
        "type": "CreditPartially"
      }
    ]

11. Invoice payment is initiated.

    The buyer notifies the seller that the invoice has been paid. The billing response status is Paid.

    The buyer can also indicate the date on which the payment was made using the effectiveDate property in the billing response metadata.

    "issueDate": "2019-11-20",
    "status": "Paid",
    "effectiveDate": "2019-11-19"

Depending on the circumstances in which a quotation request is made, different parameters must be provided to create a valid document. There are two possible scenarios:

1. The customer does not have access to the supplier's catalog item information and makes an open request. The customer provides the item information in one of the two following ways:

   1. Using description and notes.

      The customer can use the elements on the header and line levels to describe the items or services that they are interested in ordering or provide additional relevant information. These elements are as follows:

      • On the quotation request header level: description, notes.
      • On the quotation request line level: notes.

   2. Using commodityClassification.

      The element consists of two properties, type and code. The customer provides a category (code) of the item or the service according to the chosen classification system (type).

      It is also possible to enter any other information using description and notes on the header level and notes on the line level of the document to further describe the items or services requested.

2. The customer has access to the supplier's catalog item information and makes a specific request. When the customer has access to the supplier's catalog, the items need to be specified in accordance with the catalog information. In this case, the following elements are required:

   • On the quotation request line level: itemNo, name.

     Any other information can be supplied in the notes and commodityClassification elements on the line level, as well as in the description and notes elements on the header level.

The quotation that the customer receives from the supplier in response is expected to contain at least one item for each quotation request line.

Based on whether the quotation was made in response to a quotation request or not, the document is expected to contain different parameters. There are two possible situations:

1. A quotation request was made externally.

   In case when the customer made a quotation request outside the scope, for example, by making a telephone call or by sending an email, the elements referring to the quotation request are omitted. This includes the quotation request number (the documentNo property in the quotationRequestReference element) and the line identifiers (the lineIdentifierReference property in quotationLines).

2. A quotation request was made electronically.

   If the supplier issues a quotation in reply to a quotation request that the customer sent through the application, the document must indicate the quotation request number (the documentNo property in the quotationRequestReference element).

   For each item, the quotation needs to reference the corresponding line from the quotation request. In quotation requests, line identifiers are stored as the lineIdentifier property in quotationLines. This information is then reused in the lineIdentifierReference property in the quotationLines array in the quotation.

   If you are providing multiple alternative products or service items for a single quotation request line, you can indicate this by repeating the same line identifier as needed.

   The following examples show the relevant elements from the JSON metadata for a quotation request and a quotation issued following that request.

   Quotation request

   As mentioned in Quotation request: Use cases, there are several ways for the customer to indicate which items they need.

   In the following example, the quotation request contains two items that are specified using the description and notes properties.

   {
       ...
       "quotationRequest": {
           "quotationRequestNo": "QTR-1912774",
           ...
           "quotationLines": [
             {
               "lineIdentifier": "1",
               "description": "A windproof foldable umbrella.",
               "quantity": 6.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "notes": "We would like the umbrellas to match the colors of our company's logo."
             },
             {
               "lineIdentifier": "2",
               "description": "A white or copper umbrella holder.",
               "quantity": 2.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "notes": "We are looking for a sturdy umbrella holder with a metal finish or made of metal. Please send us your best offer."
             }
           ]
       }
   }

   The items can also be specified using the commodityClassification element, as shown here.

   {
       ...
       "quotationRequest": {
           "quotationRequestNo": "QTR-1912774",
           ...
           "quotationLines": [
             {
               "lineIdentifier": "1",
               "quantity": 6.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "commodityClassification": {
                   "type": "Unspsc",
                   "code": "53102505"
               }
             },
             {
               "lineIdentifier": "2",
               "quantity": 2.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "commodityClassification": {
                   "type": "Unspsc",
                   "code": "56101523"
               }
             }
           ]
       }
   }

   Quotation

   The quotation request shown in the preceding examples is referenced in the quotation as the quotationRequestReference element.

   The quotation suggests two options for the first item from the quotation request. As both these items refer to the first line of the quotation request, the lineIdentifierReference property has the same value on both quotation lines (1). For the second item from the quotation request, there is only item suggested and the lineIdentifierReference property is assigned the number of that line (2).

   The line identifiers in the quotation request should use numeric values corresponding to the number of the line in the document. However, because the customer can use differently formatted identifiers instead, it is important to check the actual values used before referencing them in the quotation.

   {
       ...
       "quotation": {
           "quotationNo": "QT-1912851",
           "quotationRequestReference": {
               "documentNo": "QTR-1912774"
           },
           ...
           "quotationLines": [
             {
               "lineIdentifierReference": "1",
               "itemNo": "VI9623NJ85",
               "name": "Umbrella",
               "description": "Windproof travel umbrella with flexible fiberglass ribs and double canopy.",
               "quantity": 6.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "unitPriceAmount": 2750.27,
               "notes": "We offer the product in 15 colors. Please specify the color when ordering."
             },
             {
               "lineIdentifierReference": "1",
               "itemNo": "J8724HYQV3",
               "name": "Travel umbrella",
               "description": "Lightweight, compact, with automatic opening and closing function. Instant dry technology, canopy with teflon coating and 9 fiberglass ribs. Ergonomic design with a rubberized handle.",
               "quantity": 6.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "unitPriceAmount": 3068.75,
               "notes": "The item is available only in black."
             },
             {
               "lineIdentifierReference": "2",
               "itemNo": "PL8C6K0NTG",
               "name": "Umbrella holder",
               "description": "Umbrella stand rack with removable tray and 8 hooks.",
               "quantity": 2.0,
               "unitOfMeasure": {
                   "unit": "One"
               },
               "unitPriceAmount": 5751.94,
               "notes": "Please note that we only have bronze and white in stock. Copper and black have longer delivery time."
             },
       }
   }

When creating messages on the messaging server, the sender has the option to trigger additional document processing. This is managed through services.

Depending on the service type, services are configured in one the following ways:

1. For the server (General server settings).
2. For the sending party (Party settings).
3. On the message level (Arguments).

When services are set for an individual message, the user supplies a list of service parameters in the API call.

Each service is identified with a unique service identifier. For more information about how to configure and use a particular service, refer to the service description.

To view the service status, sign in on your account in the eefacta Server UI. Select the message for which you want to see the services, then go to the Services tab. The service status shows you whether the service has been successfully performed or not.

The following services are available:

Service	Identifier	Availability
Skip dispatching	urn:services:generic:allow.no.dispatch	Global
Send through email	urn:services:dispatcher:mail.pdf	Global
Printing at Oddi Printing Center	urn:services:oddi:print	Local (Iceland)
Sending documents to Mappan at Iceland Post	urn:services:dispatcher:mappan.pdf	Local (Iceland)
Printing at NoInk	urn:services:noink:print.mail.pdf	Local (Sweden)

Skip dispatching

When you specify this service parameter, you can create a message on the server without requiring delivery (dispatching) of the message to the receiving party. Therefore, you can use this parameter when you want to use another service, such as Send through email, and avoid getting a "Participant not found" error if the user is not registered on the server or found in any external networks.

The receiving party does not need to be registered on eefacta Server.

Parameter	urn:services:generic:allow.no.dispatch
General server settings	None
Party settings	None
Arguments	None

Send through email

When the business document is pushed to the server, it can be forwarded through email in PDF format.

Parameter	urn:services:dispatcher:mail.pdf
General server settings	None
Party settings	None
Arguments	The sender must specify the email address to which the business document will be sent, for example, email=address@domain.is. The argument is then supplied at the end of the parameter, as shown in the following example: urn:services:mail:pdf?email=netfang@netfang.is.

Printing at Oddi Printing Center

During dispatching, business documents can also be delivered to Oddi's Printing Center. Oddi prints and handles the document according to the contract signed with the sender.

Parameter	urn:services:oddi:print
General server settings	The messaging server is integrated with Oddi's Printing Center. Oddi sets up a folder for the sending party, as well as a username and password. When documents are distributed to Oddi, default credentials are used. In case of dealing with large numbers of documents, the sender typically signs a direct contract with Oddi.
Party settings	If the sender has an agreement concluded with Oddi, Oddi provides a username and password that are then registered in the sender's account on the messaging server. The settings are as follows: urn:services:oddi:print:username urn:services:oddi:print:password If you do not have a contract signed with Oddi, you need to enter one of the following: urn:services:oddi:print:use.default.credentials=true urn:services:oddi:print:use.default.credentials=1
Arguments	You need to specify the username and password obtained when signing up with Oddi: User=username#&#Password={auth:pwd}. These credentials are then replaced in the sender's account on the messaging server.

Sending documents to Mappan at Iceland Post

The business document can also be sent through Mappan, a service provided by the Iceland Post. Users register with the Iceland Post and are assigned a folder to which their mail is delivered electronically.

With this service, business documents are forwarded in PDF format to the receiver's folder on their Iceland Post account.

Parameter	urn:services:dispatcher:mappan.pdf
General server settings	The application is connected to the Mappan service.
Party settings	None
Arguments	You need to supply the following: The identifier of the receiving party in this format: KT=identifier. The credentials that you obtained when you registered at the Iceland Post: User=username#$#Password={auth:pwd}. The subject of the message: Subject=Heading. The language. This is optional. We currently support English and Icelandic, and the default language is Icelandic: lang=is. Arguments are delimited with #$#. The arguments can be provided in any order. The following is a full example of the service parameter with the arguments specified: urn:services:dispatcher:mappan.pdf?KT=01234567899#$#User=notandi#$#Password=lykilord#$#subject=Sending frá Miðlun Sendils#$#lang=is

Printing at NoInk

The sender has the possibility of having their business documents printed and further distributed, for example by postal mail, by NoInk in Sweden.

In this case, the document is forwarded to NoInk when it is dispatched to the messaging server. NoInk prints the document and dispatches it in accordance with the contract concluded with the sender.

Parameter	urn:services:noink:print.mail.pdf
General server settings	The application is configured to connect with NoInk communication server. The sender is assigned a folder and user credentials. Business documents are transferred to NoInk using default credentials. Otherwise, typically in cases where the sender needs to print large quantities of documents, the sender signs a direct contract with NoInk.
Party settings	If the sender has a contract signed with NoInk, the username and password provided by NoInk need to be registered on the sender's account on the messaging server. The settings are the following: urn:services:noink:print:username urn:services:noink:print:password
Arguments	The sender provides the following: The username and password that the sender received when signing up with NoInk: User=username#$#Password={auth:pwd}. The credentials are then also replaced on the sender’s account on the messaging server. The language. Selecting a language is optional and you can choose between English and Icelandic, for example, lang=en. If the language is not supplied, Icelandic is used by default. The arguments can be specified in any order. Arguments are delimited using #$#. The following example shows how to set up all arguments correctly: User=notandi#$#Password=password#$#lang=is.

In business documents that are created from JSON metadata, the unit of measure (unitOfMeasure) in the document needs to be specified according to the standards UN/ECE Recommendation 20 and UN/ECE Recommendation 21.

The unitOfMeasure property in the metadata consists of two fields, unit and code.

The unit property can be used on its own with one of the following values:

• One
• Piece
• Package
• Kilogram
• Metre
• Litre
• SquareMetre
• CubicMetre
• Kilometre
• Tonne
• KiloWattHour
• Hour
• Day
• Month
• Year
• Rec20
• Rec21

The values Rec20 and Rec21 refer to UN/ECE standardized code lists. To expand the list of supported values, set the unit property to Rec20 or Rec21 and the code property to one of the allowed codes. Some examples are provided in the following tables:

Recommendation 20 codes

Rec20 code	Name
C62	One
H87	Piece
KGM	Kilogram
MTR	Metre
LTR	Litre
MTK	Square metre
MTQ	Cubic metre
KTM	Kilometre
TNE	Tonne
KWH	Kilowatt hour
DAY	Day
HUR	Hour
MIN	Minute

Recommendation 21 codes

Rec21 code	Name
BG	Bag
BA	Barrel
BX	Box
CT	Carton
CY	Cylinder
PK	Package
PX	Pallet
RL	Reel
SA	Sack
ST	Sheet

For a full list of unit of measure codes, see UN/ECE Recommendation 20 and UN/ECE Recommendation 21.

Billing identifiers use codes to describe what the fields contain. This also specifies how certain invoices or certain invoice lines should be accounted for (bókað?) This information needs to be provided by the buyer, whether that be with the order document or otherwise. Please note that billing references can only be used with the EN/CII standard

Usage example: An insurance company gets an invoice from an auto repair shop, the invoice header contains a "reference identifier" that references the car that was being repaired. This is done using the code ABZ which stands for vehicle licence number. This allows the insurance company to match the invoice with the correct incident report and the specific car that was damaged.

The following is a table of frequently used reference types and codes:

Billing identifiers

Reference type and code	Description
Vehicle licence number (ABZ)	Number of the licence issued for a vehicle by an agency of government.
Department number (AMV)	Number assigned to a department within an organization.
Work order (AOV)	Reference number for an order to do work.
Company / place registration number (XA)	Company registration and place as legally required.
Metering point (AVE)	Reference to a metering point.
Meter unit number (MG)	Number identifying a unique meter unit.
Charge card account number (AIU)	Number to identify charge card account.
Phone number (AMV)	A sequence of digits used to call from one telephone line to another in a public telephone network.
Returns notice number (ALQ)	A reference number to a returns notice.
Waybill number (AAM)	Reference number assigned to a waybill.
Firm booking reference number (AXE)	A reference number identifying a previous firm booking.
Shipping unit identification (ACC)	Identifying marks on the outermost unit that is used to transport merchandise.

Payment means describes the way a buyer should pay the invoice and which details they need to provide.

For a particular payment means, the corresponding details must be provided. For example, when the type is set to SepaCreditTransfer then the corresponding sepaCreditTransfer node needs to be filled in with the payee account number, payer account number and the payment mandate identifier.

Elements

Name	Description
Sepa credit transfer	Credit transfer inside the Single Euro Payment Area (SEPA) system.
International transfer	Payment by debit movement of funds from one account to another via IBAN accounts.
Domestic claim	Payment by means of a claim in the bank. Used specifically in Iceland
Domestic transfer	Payment by means of a bank account. Used specifically in Iceland

The Messaging API works with four core resources: Transactions, Messages, Parties, Devices. Here you will find descriptions of these resources and instructions on how to access and handle them.

For API calls that use a specific request body, the examples are provided in the endpoint description and as request samples in the rightmost column. This is the case with the calls relying on metadata to generate business documents (Transactions).

For more information about how requests are authorized, refer to Authentication. To see what responses MAPI returns, go to Response codes.

We recommend you start by exploring the Transactions resource. Using this resource, you can send and retrieve business documents that are created from the metadata. The correct document standard is chosen for you, and if the message delivery is unsuccessful, the document will reach your business partner through email.

If you have a deep knowledge of document standards and are willing to learn about new document standards as they emerge, take a look at the Messages resource and the POST /messages/create-business-transaction call. This approach lets you implement business documents in their native format, for example, as a UBL 2.1 XML document.