# Introduction 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](#tag/Transaction) and how to send an electronic business document generated from metadata. The requests are authenticated using [HTTP Basic Authentication](#section/Authentication). The quickest way to try out the Messaging API is through [Postman](https://www.getpostman.com/), a flexible and comprehensive tool for developing and testing APIs. Download a copy of our Postman collection by clicking the following button: [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/4253a45b1d581284c065) To learn more about how Postman can assist you in implementing MAPI, go to [Implementing MAPI: C#, Java, Python, PHP, Ruby, Node.js, jQuery](#section/Implementing-MAPI:-C-Java-Python-PHP-Ruby-Node.js-jQuery). For further information, contact us at info [at] unimaze [dot] com. # Before you begin 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`](#operation/AddDocuments)) and retrieving the status of the message after the message has been handed over to the server ([`GET /messages/:mid`](#operation/MessageGetById)). Message envelope

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. ## Quickstart 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`](#tag/Transaction)) 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`](#operation/CreateBusinessTransaction)) 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`](#operation/CreateMessage) 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. ## Response codes 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`. ## Message identifier The message identifier (`mid`) is always in the format of a [globally unique identifier](https://tools.ietf.org/html/rfc4122) (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#](https://docs.microsoft.com/en-us/dotnet/api/system.guid.newguid?view=netframework-4.8), [Java](https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/util/UUID.html), or [Python](https://docs.python.org/3/library/uuid.html). You can also find online generators, such as this [Online GUID generator](https://www.guidgenerator.com/online-guid-generator.aspx). ## Business participant identifiers 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](http://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/). The identifier type corresponds to the code of the identifier in the list. # Sending outbound messages 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](#section/Sending-outbound-messages/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](#Outbound-messages) until delivered. ## Creating messages 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`](#tag/Transaction) 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`](#operation/CreateSubmitOrder) * [`POST /transactions/submit-order-change`](#operation/CreateSubmitOrderChange) * [`POST /transactions/submit-order-cancellation`](#operation/CreateSubmitOrderCancellation) * [`POST /transactions/submit-invoice`](#operation/CreateSubmitInvoice) * [`POST /transactions/correct-with-credit`](#operation/CreateCorrectWithCredit) * [`POST /transactions/submit-payment-notification`](#operation/CreateSubmitPaymentNotification) * [`POST /transactions/submit-billing-response`](#operation/CreateSubmitBillingResponse) * [`POST /transactions/request-quotation`](#operation/CreateRequestQuotation) * [`POST /transactions/submit-quotation`](#operation/CreateSubmitQuotation) 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](#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](https://www.iso.org/obp/ui/#search). * `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`, `OutsideTaxScope`. * `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](#section/Additional-information/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](https://www.iso.org/iso-4217-currency-codes.html). 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](#Billing-response-status). * `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](#Billing-response-reason). * `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](#Billing-response-action). 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](#section/Additional-information/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](#section/Additional-information/Quotation:-Use-cases).

Create as a transaction

The [`POST /messages/create-business-transaction`](#operation/CreateBusinessTransaction) 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`](#operation/GetPartyReceivingTransactions) 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`](#operation/CreateBusinessTransaction) 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`](#operation/CreateMessage) 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. ## Adding documents 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`](#operation/AddDocuments) 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`. ## Monitoring outbound message status 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`](#operation/MessageGetById) 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/status`](#operation/GetMessageStatusWithTraces) call. The call returns information on when the message was received onto the server, when it was delivered(if it has been delivered), different possible statuses of the message and an array of JSON objects that each includes information about the events that occurred during the message processing. ``` { "receivedTimestamp": "2020-06-12T11:50:47.277Z", "deliveredTimestamp": null, "messageStatus": "InProcess", "internalMessageStatus": "PendingDelivery", "validationStatus": "Valid", "traces": [ { "timestamp": "2020-06-12T11:50:46.617Z", "sourceIp": "mapi.dsp-test.unimaze.com", "sourceUser": "profile1", "sourcePartyName": "TEST party", "traceTypeKeyName": "CreateClosed", "traceMessage": "Message created (RemittanceAdvice, text/xml) - ready for processing", "traceDescription": "" }, { "timestamp": "2020-06-12T11:50:47.323Z", "sourceIp": "", "sourceUser": "", "sourcePartyName": null, "traceTypeKeyName": "MovedToReceiverInbox", "traceMessage": "Message transferred to inbox of receiving party", "traceDescription": "Document moved to receiver's inbox" } ] } ``` # Receiving inbound messages 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. ## Getting a list of pending messages 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`](#operation/GetMessages) 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. ## Fetching documents 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}`](#operation/GetSubmitOrder) * [`GET /transactions/submit-order-change?mid={mid}`](#operation/GetSubmitOrderChange) * [`GET /transactions/submit-order-cancellation?mid={mid}`](#operation/GetSubmitOrderCancellation) * [`GET /transactions/submit-invoice?mid={mid}`](#operation/GetSubmitInvoice) * [`GET /transactions/correct-with-credit?mid={mid}`](#operation/GetCorrectWithCredit) * [`GET /transactions/submit-payment-notification?mid={mid}`](#operation/GetSubmitPaymentNotification) 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`](#operation/GetCoreMessageDocument) 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`](#operation/GetTransformedMessageDocument) call. To get the original document that was transformed, use the [`GET /messages/:mid/documents/original`](#operation/GetOriginalMessageDocument). 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`](#operation/GetMessageDocumentByName) 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`](#operation/GetMessageDocumentByIndex), 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. ## Setting message status 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`](#operation/MarkMessageAsDelivered) 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`](#operation/MarkMessageAsFailed) 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. # Viewing documents 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`](#operation/DisplayDocuments)) 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`](#operation/MessageGetById) 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`](#operation/DisplayDocuments) 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. # Implementing MAPI: C#, Java, Python, PHP, Ruby, Node.js, jQuery Clicking **Run in Postman** imports the collection of requests into your Postman application where you can run them directly. The [API Reference](#section/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](https://learning.getpostman.com/docs/postman_for_publishers/run_button/using_run_button/). For all other questions related to Postman, go to [Postman Learning Center](https://learning.getpostman.com/). 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](https://learning.getpostman.com/docs/postman/sending_api_requests/generate_code_snippets/) 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. # Additional information ## Message flow 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`. Message flow - Outbound messages

1. A message is created through the [`POST /messages/create-business-transaction`](#operation/CreateBusinessTransaction) or any of the `POST` requests using the [Transaction](#tag/Transaction) resource (see [Creating messages](#section/Sending-outbound-messages/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](#operation/AddDocuments). 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`](#operation/AddDocuments) 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`](#operation/AddDocuments) 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. Message flow - Inbound messages

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`](#operation/GetMessages) 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`](#operation/MarkMessageAsFailed) 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`](#operation/MarkMessageAsDelivered) 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](#Outbound-messages).

When a receiver's back-end system monitors the `pendingprocessing` state, it does so through the [`GET /messages?status=pendingprocessing&transfer=inbound`](#operation/GetMessages) call. After it has successfullyWhen a receiver's back-end system monitors processed the message, the message status can be updated using the [`POST /messages/:mid/mark-as-processed`](#operation/MarkMessageAsProcessed) 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`](#operation/MarkMessageAsDelivered) call.

Messages in the `pendingprocessing` or `pendingdelivery` state can be parked through the UI. ## Business transaction groups 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). ## Billing profiles 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) ## Billing response elements 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)](https://docs.peppol.eu/poacc/upgrade-3/codelist/UNCL4343-T111/) 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)](https://docs.peppol.eu/poacc/upgrade-3/codelist/OPStatusReason/) 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)](https://docs.peppol.eu/poacc/upgrade-3/codelist/OPStatusAction/) 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.

## Billing response: Use cases 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" ``` ## Quotation request: Use cases 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:

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

1. 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. ## Quotation: Use cases 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](#section/Additional-information/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." }, } } ``` ## Services 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
Sending a claim to bank	`urn:services:banking:claim`	Local (Iceland)
Sending document to bank	`urn:services:banking:document`	Local (Iceland)
Printing at Oddi Printing Center	`urn:services:oddi:print`	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`. Additional parameters can be specified, supported is `lang` and `attachpdf`. Example: `urn:services:dispatcher:mail.pdf?email=netfang@netfang.is#$#lang=en#$#attachpdf=true`

Sending a claim to bank

The sender has the possibility of sending a claim to the receiver’s online bank. The document is sent on behalf of the sender using credentials and a machine certificate, encrypted centrally. Currently, these banks are supported: * Íslandsbanki, Arion banki, Landsbanki * Kvika, Sparisjóðirnir, Seðlabankinn, InKasso

Parameter	`urn:services:banking:claim`
General server settings	The application is configured to connect with a centralized banking hub integration. It allows users to send claims with the invoices directly to the banks.
Party settings	Required party setting for sending claims are the client credentials that are encrypted using AES and a secret encryption key. This are set up on the messaging server by Unimaze. Namespace: `urn:services:banking:claim` Name: `ClientCredentials`
Arguments	The sender provides the following: accountNo [example: 012366004321] dueDate [example: 2023-05-27] graceDate [example: 2023-05-29] cancellationDate [example: 2023-06-15] The arguments can be specified in any order. Arguments are delimited using #$#. The following example shows how the parameter with arguments are set up: `urn:services:banking:claim?accountNo=013066000001#$#dueDate=2023-04- 24#$#graceDate=2023-04-25#$#cancellationDate=2023-05-24.` accountNo and dueDate can either both be specified, or they can be specified inside the invoice document. If they are not both specified as parameters, they are taken from the invoice. In the invoice the accountNo is taken from the payment means using payment means code 49 in older standards (TS-136, BII/NES) and code 9 in newer standards (Peppol BIS3/European Norm and later). graceDate is optional. graceDate must be set to a later than due date. If graceDate is not specified, it is found on the Invoice. If it is not specified on the invoice either, it’s set as the same date as the dueDate. cancellationDate is optional. If cancellationDate is not specified, it is set as one year after the dueDate. cancellationDate must be set at least 30 days later than due date. Both the sender and receiver legal entities identifiers must be specified in the invoice. Example of payment means for older standard used for accountNo and dueDate: ``` 49 2018-12-07 IS:BANK 123456 IS:66 123 ``` Example of where graceDate is taken from in older standard: ``` 2018-12-22 ``` Example of where dueDate is taken from newer standards: ``` 2018-12-07 ``` Example of payment means for newer standards used for accountNo: ``` 9 012366123456 ``` Example of where graceDate is taken from newer standards: ``` 2018-12-22 EINDAGI

Sending document to bank

The sender has the possibility of sending a document to the receiver’s online bank. The document is sent on behalf of the sender using credentials and a machine certificate, encrypted centrally. Currently, these banks are supported: * Íslandsbanki

Parameter	`urn:services:banking:document`
General server settings	The application is configured to connect with a centralized banking hub integration. It allows users to send document with the invoices directly to the banks.
Party settings	Required party setting for sending documents are the client credentials that are encrypted using AES and a secret encryption key. This are set up on the messaging server by Unimaze. `urn:services:banking:document:credentials` stores the encrypted username and password `urn:services:dispatcher:company.logo.base64` and `urn:services:dispatcher:company.logo.content.type` stored the optional company URL in the format required (size, proportions), stored as BASE64 media type encoded
Arguments	The sender provides the following:

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.

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`.

## Unit of measure In business documents that are [created from JSON metadata](#Create-using-metadata), the unit of measure (`unitOfMeasure`) in the document needs to be specified according to the standards [UN/ECE Recommendation 20](http://tfig.unece.org/contents/recommendation-20.htm) and [UN/ECE Recommendation 21](http://www.unece.org/fileadmin/DAM/cefact/recommendations/bkup_htm/rec21en.htm). 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
KMT	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](http://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/) and [UN/ECE Recommendation 21](http://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec21/). ## Billing identifiers 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. Multiple billing identifiers can be used on header level while only one can be used in each line. The first billing identifier on header level will be an invoiced Object Identifier. 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 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

# API Reference The Messaging API works with four core resources: [`Transactions`](#tag/Transaction), [`Messages`](#tag/Message), [`Parties`](#tag/Party). 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](#Metadata) to generate business documents ([`Transactions`](#tag/Transaction)). For more information about how requests are authorized, refer to [Authentication](#section/Authentication). To see what responses MAPI returns, go to [Response codes](#section/Before-you-begin/Response-codes). We recommend you start by exploring the [`Transactions`](#tag/Transaction) 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`](#tag/Message) resource and the [`POST /messages/create-business-transaction`](#operation/CreateBusinessTransaction) call. This approach lets you implement business documents in their native format, for example, as a UBL 2.1 XML document.