Messaging Services v1.0 (v1)

Download OpenAPI specification:Download

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

Run in Postman

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.

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) and retrieving the status of the message after the message has been handed over to the server (GET /messages/:mid).

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

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

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

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

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.

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 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 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"
    }
]

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

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.

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

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

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

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

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

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

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:

    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.

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

Unit of measure

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

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

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

Authentication

Basic

The Messaging API uses HTTP Basic Authentication. To authenticate requests, you need a username and password.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Devices

POST /devices/upload

Uploads a document from an external device, such as a scanner, using a raw binary format (application/octet-stream).

You can also submit the data as a stream that is formatted as a base64-encoded ASCII text. In this case, the HTTP Content-Type header must be set to application/base64.

The user scans a business document, for example, using OCR software, creates a native business document, such as a UBL 2.1 document, and sends it to themselves. This lets users import paper documents into the application.

The signed-in user must be the message receiver, not the message sender. It is not possible to send documents to other users using this API call. The user also needs to be an agent, which is managed through the user settings.

Core documents submitted this way are validated in the same manner as when calling POST /messages/create-business-transaction.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

transactionGroupIdentifier
required
string

The identifier of the transaction group, for example, SubmitInvoice or SubmitOrder.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood, but could not be processed.

post /api/v1/devices/upload
/api/v1/devices/upload

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "d1abd08e-d4a4-45f5-bb52-118c74bba786",
  • "timeReceived": "2020-06-25T15:11:46.9999283Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

Uploads a document from the device using raw binary (deprecated). Deprecated

query Parameters
messageId
required
string <uuid>
transactionGroupIdentifier
required
string

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood, but could not be processed.

post /api/v1/external/devices/upload
/api/v1/external/devices/upload

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "c070ad45-9be1-43a9-95e4-fe053636a98a",
  • "timeReceived": "2020-06-25T15:11:47.0249338Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

Message

GET /messages/:mid

Returns information about a specific message using the unique message identifier (GUID).

The returned object contains details about the message and the documents that are wrapped in the message.

The binary payload of message attachments can be retrieved through the following calls:

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Success

get /api/v1/messages/{id}
/api/v1/messages/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "3c6a906a-f98c-491d-8b53-4aa9ea142a17",
  • "timeReceived": "2020-06-25T15:11:47.0289479Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

GET /messages/:mid/documents/:idx

Retrieves the binary payload of a document stored in a specific message using the index number of the document. The document index is a zero-based index whose first element is always the core document of the message.

To find the document index number, use the GET /messages/:mid call. The call returns a JSON object that represents the message envelope. The index number is found in the index property of each document in the documents array.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

idx
required
integer <int32>

The number of the attachment. Attachments form a zero-based index. The first index (0) is the core processing document.

Responses

200

Document payload

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages/{id}/documents/{idx}
/api/v1/messages/{id}/documents/{idx}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

GET /messages/:mid/documents/:name

Returns the binary payload of a document stored in a specific message using the name of the document. Each message attachment has a unique name in the context of the message.

The document name can be found through the GET /messages/:mid call. The name corresponds to the name property of each document in the documents array of the returned message object.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

name
required
string Nullable

The unique name of the attachment contained in the message.

Responses

200

Document payload

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages/{id}/documents/{name}
/api/v1/messages/{id}/documents/{name}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

GET /messages/:mid/documents/core

Returns the binary payload of the core processing document stored in a specific message.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Document payload

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages/{id}/documents/core
/api/v1/messages/{id}/documents/core

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

GET /messages/:mid/documents/original

Returns the binary payload of the original document stored in a specific message.

An original document is a document that has been transformed from one business document syntax specification to another in the inbound message. This way, the document is delivered to the receiver in one of the document specifications that the receiver can process and import.

After transformation, the document that has been transformed becomes the original document in the inbound message, while the new document is called the transformed document. In the inbound message, the transformed document also becomes the core document.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Document payload

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages/{id}/documents/original
/api/v1/messages/{id}/documents/original

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

GET /messages/:mid/documents/transformed

Returns the binary payload of the transformed document stored in a specific message.

Documents are transformed from one business document specification to another one so that the receiver can receive the document in one of the document specifications that they support.

After transformation, the new document is called the transformed document in the inbound message, while the document that was originally sent becomes the original document. In the inbound message, the transformed document becomes the core document.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Document payload

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages/{id}/documents/transformed
/api/v1/messages/{id}/documents/transformed

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

GET /messages

Retrieves messages using filters. If no filters are set, the call returns the 50 newest messages that the user has permission to view. The messages are sorted by date, in descending order.

Users with basic access rights see the messages that were sent or received by their own party. Manager users can view the messages owned by the parties that they manage, while administrator users can view the messages from all the parties in the system.

The returned results can be paged. The maximum number of messages per page is 100.

Multiple filters can be used at the same time. If there are no matching messages, the call returns an empty array.

query Parameters
Status
string (MessageStatuses)
Enum: "NotSet" "Received" "Delivered" "Processed" "Failed" "PendingDelivery" "PendingProcessing" "Parked" "Logged" "LoggedFailed" "Retrying" "NotProcessing" "LoggedRelayed" "PendingReview"

The requested message status.

For more details, see Message flow.

Transfer
string Nullable

The transfer status of the requested messages. Valid values are: inbound, outbound, internal, routed, incoming, outgoing.

The incoming status includes both inbound and internal messages, and the outgoing status covers both outbound and internal messages. Internal messages are exchanged within the same party, for example, between different departments of one company.

TransactionGroup
string Nullable

The name of the transaction group indicating the action that should be performed on the data, for example, SubmitInvoice, CorrectWithCredit, or SubmitOrder.

For more details, see Business transaction groups.

TimeReceivedFrom
string <date-time> Nullable

Defines the date starting from which the messages were received. The date provided is included in the time range.

The date must be in the following format {yyyy-mm-dd}. When specifying both date and time, the format is {yyyy-mm-dd}T{hh:mm:ss.s}.

TimeReceivedTo
string <date-time> Nullable

Defines the date up to which the messages were received. The date provided is not included in the time range.

The date must be in the following format {yyyy-mm-dd}. When specifying both date and time, the format is {yyyy-mm-dd}T{hh:mm:ss.s}.

SourcePartyIdentifier
string Nullable

The sender of the wanted messages. The party is specified using the {identifierType}:{identifier} format, for example, KT:xxxxxxyyyy.

SinkPartyIdentifier
string Nullable

The receiver of the requested messages. Uses the business participant identifier in the {identifierType}:{identifier} format, for example, KT:xxxxxxyyyy.

OwnerPartyIdentifier
string Nullable

The owner of the selected messages. The message owner is either the sender or the receiver of the message. Takes the business participant identifier provided in the {identifierType}:{identifier} format, for example, KT:xxxxxxyyyy.

FromTextFilter
string Nullable

The sender of the wanted messages. Uses the name of the business participant.

ToTextFilter
string Nullable

The receiver of the requested messages. Requires the name of the business participant.

MessageReference
string Nullable

The reference number of the document contained in the message or the unique message identifier (GUID).

For example, if this parameter is used for a document reference number, it might be the invoice number.

ValidationStatus
string (ValidationHeaderStatus)
Enum: "Valid" "Invalid" "Ignored" "Unknown" "MissingData"

The validation status of the document contained in the message.

Offset
integer <int32> [ 0 .. 2147483647 ] Nullable

The number of items that are skipped before the results are returned.

The value must be a multiple of the value of the limit parameter.

Limit
integer <int32> [ 1 .. 10000 ] Nullable

The number of messages returned. The maximum value is 100, the minimum value is 1.

If not set, the default value is 50.

Responses

200

List of messages.

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/messages
/api/v1/messages

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    }
]

POST /messages/create-message

Uploads a generic document and creates a message.

The call sends the primary document of the message to the server using a raw binary format (application/octet-stream). You can also submit the data as a stream that is formatted as a base64-encoded ASCII text. In this case, the HTTP Content-Type header must be set to application/base64.

The document must be sent as the request body.

The message data is not validated at this stage, which means that the message validation status is always set to unknown. The call also informs the server of whether more data is expected or not and then updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset.

This upload is meant for generic documents (for example, images) and non-standard documents (for example, documents that cannot be validated). For standard business documents, use the POST /messages/create-business-transaction method.

The sender and the receiver must agree on the message envelope parameters, such as ServiceType, Service, and Action.

query Parameters
MessageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

DestinationPartyInfo
required
string

The ISO identifier of the receiving party, preceded by the identifier type. The format is {identifierType}:{identifier}, for example, KT:xxxxxxyyyy.

Service
required
string

A descriptor of the service. Can refer to the business profile of the document.

In that case, it has the format of the Unique Resource Name (URN) of the profile, typically together with the corresponding business transaction group, for example, urn:www.cenbii.eu:profile:bii04:ver1.0##CENBII-1.0.

The parameter is used along with the action parameter to control document processing.

ServiceType
string Nullable

The type of service. Used by ebXML Messaging Service (ebMS) specification.

Action
required
string

The name of the transaction group indicating the action that should be performed on the data, for example, SubmitInvoice or CorrectWithCredit.

ConversationIdentifier
string Nullable

The identifier of the conversation. Used as a correlation identifier between different documents in the same business context, for example, between a credit note that was issued based on an invoice and that invoice.

If not provided, it is generated automatically. In that case, it includes the date when the message was sent, a random token, and the ISO identifier of the sender.

DocumentNo
string Nullable

The value should correspond to the document number or contain another suitable reference to the message, for example, the invoice number.

ReferenceInformation
string Nullable

Used for specifying information relevant to the document. Can be set to any value, for example, the invoice amount or a special reference value.

Name
required
string

The name of the document. The value must be unique in the context of the message.

ContentType
required
string

The media type (MIME type) of the document. For XML documents, the media type is text/xml. This is used for display and processing control.

More
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

Encoding
string Nullable

The encoding used for displaying text documents. For XML documents, examples include utf-8 and iso-8859-1.

Namespace
string Nullable

The namespace of the document. The parameter is informative and might be used for XML documents, where it corresponds to the namespace of the XML document.

EmbedDocument
boolean

Whether the document should be embedded into the xml.

services
Array of strings Nullable

A list of services that the user specifies for additional message processing.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/messages/create-message
/api/v1/messages/create-message

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "08c54dcb-e73f-478e-a30d-139293d41c4b",
  • "timeReceived": "2020-06-25T15:11:47.1859214Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

POST /messages/create-business-transaction

Uploads a document and creates a business transaction that needs to be validated.

The call creates a business transaction by uploading a raw binary format (application/octet-stream) and then validates that transaction. You can also submit the data as a stream that is formatted as a base64-encoded ASCII text. In this case, the HTTP Content-Type header must be set to application/base64.

The document must be sent as the request body.

The validation step ensures that the document fulfills the corresponding business and semantic requirements.

The call also informs the server of whether more data is expected or not and then updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset.

Additional documents are added through the POST /messages/:mid/documents call. This is possible if the value of the more parameter was set to true when the message was created.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

transactionGroupIdentifier
required
string

The identifier of the transaction group indicating the action that should be performed on the data, for example, SubmitInvoice, CorrectWithCredit, or SubmitOrder. See Business transaction groups.

conversationIdentifier
string Nullable

The identifier of the conversation. Used as a correlation identifier between different documents in the same business context, for example, between a credit note that was issued based on an invoice and that invoice.

If not provided, it is generated automatically. In that case, it includes the date when the message was sent, a random token, and the ISO identifier of the sender.

more
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

processingMode
string (TransactionProcessingMode)
Enum: "Default" "Routed" "Device"

The way the transaction is processed.

services
Array of strings Nullable

A list of services that the user specifies for additional message processing.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/messages/create-business-transaction
/api/v1/messages/create-business-transaction

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "f0b708d3-67c1-44b3-8b40-990322e44fc1",
  • "timeReceived": "2020-06-25T15:11:47.2009205Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

POST /messages/:mid/documents

Attaches a document to an existing message.

The call submits the document data to the server and adds it to the selected message by using a raw binary format (application/octet-stream). You can also submit the data as a stream that is formatted as a base64-encoded ASCII text. In this case, the HTTP Content-Type header must be set to application/base64.

The document must be sent as the request body.

When the data is uploaded, the call then informs the server of whether more data is expected or not and updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset.

The call throws an exception if the message does not exist or if it has already been closed, which means that its message status is received.

path Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

query Parameters
Name
required
string

The name of the document. The value must be unique in the context of the message.

ContentType
required
string

The media type (MIME type) of the document. For XML documents, the media type is text/xml. This is used for display and processing control.

More
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

Encoding
string Nullable

The encoding used for displaying text documents. For XML documents, examples include utf-8 and iso-8859-1.

Namespace
string Nullable

The namespace of the document. The parameter is informative and might be used for XML documents, where it corresponds to the namespace of the XML document.

EmbedDocument
boolean

Whether the document should be embedded into the xml.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/messages/{messageId}/documents
/api/v1/messages/{messageId}/documents

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "838039a7-fdc0-493e-ab4a-737532a01a24",
  • "timeReceived": "2020-06-25T15:11:47.2149204Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

POST /messages/:mid/mark-as-processed

Indicates that the message has been successfully processed. The message is then ready for delivery.

To execute the call successfully, the message must be in the pendingprocessing state. After the message has been marked as processed, its status changes to pendingdelivery.

For more information about message statuses, see Message flow.

path Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Status successfully set.

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/messages/{messageId}/mark-as-processed
/api/v1/messages/{messageId}/mark-as-processed

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "statusCode": "422",
  • "statusText": "UnprocessableEntity",
  • "message": "Message could not be processed. Missing lines."
}

POST /messages/:mid/mark-as-delivered

Sets the message status to delivered to the back-end system. This indicates that the message has been successfully received.

An incoming message can be marked as delivered if its current status is pendingdelivery.

For more information about message statuses, see Message flow.

path Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Status successfully set.

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/messages/{messageId}/mark-as-delivered
/api/v1/messages/{messageId}/mark-as-delivered

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "statusCode": "422",
  • "statusText": "UnprocessableEntity",
  • "message": "Message could not be processed. Missing lines."
}

POST /messages/:mid/mark-as-failed

Sets the message status to failed and sends an error message for logging purposes.

A message should be marked as failed if the receiver's back-end system could not import it.

For more information about message statuses, see Message flow.

path Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

query Parameters
errorMessage
required
string

A meaningful message detailing why the message failed. The message is stored in log and trace messages.

Responses

200

Status successfully set.

400

Invalid input parameters.

422

The request was understood, but could not be processed.

post /api/v1/messages/{messageId}/mark-as-failed
/api/v1/messages/{messageId}/mark-as-failed

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "statusCode": "422",
  • "statusText": "UnprocessableEntity",
  • "message": "Message could not be processed. Missing lines."
}

GET /messages/:mid/traces

Returns all traces of a specific message.

These messages track message processing and record the relevant events. A trace message includes information about the party that set off the event, the date and time when it happened, the type of event, and a textual description of the event.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Message traces

404

Message not found.

get /api/v1/messages/{id}/traces
/api/v1/messages/{id}/traces

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

GET /messages/:mid/validations

Returns all validation entries for a specific message.

Validation entries indicate the validation outcome for the core processing document of the message. Each entry specifies an instance of an error or a warning that are related to the document structure or business rule validation.

path Parameters
id
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Message validation entries

404

Message not found.

get /api/v1/messages/{id}/validations
/api/v1/messages/{id}/validations

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

GET /messages/display/:id

Displays an XML business document in HTML format.

This API call is unique in that it returns the document in the original format in which it was submitted, for example, in PDF, JPG, and others.

The business document is fetched using the document reference identifier, which is retrieved through GET /messages/:mid. In the JSON response body that is returned, the identifier is stored as the referenceId property.

The call does not require authentication—anonymous access is allowed. However, the reference identifier includes a passcode that should only be shared by secure means.

The document can be converted to formats other than HTML (PDF, JPG, PNG, GIF, or TIF) or displayed raw. You can also view embedded documents.

If additional languages are supported for this document type, you can choose the language in which the document is displayed.

path Parameters
id
required
string Nullable

The unique document reference identifier. The identifier is in the following format {messageIdentifier}:{partyIdentifierType}:{partyIdentifier}:{documentIndexNumber}:{passcode}.

The party identifier matches the sender of the message. The passcode is a token generated when the document is added to the message.

query Parameters
ct
string Nullable
Default: ""

The format to which the XML document should be converted. If the parameter is not specified, no conversion is made and the document is displayed in HTML provided that a corresponding style sheet is available.

Possible values are: pdf, png, jpg, gif, tif, raw. Setting the parameter to raw displays the original XML file. Only documents in XML format can be converted.

lang
string Nullable
Default: "en"

The language in which the document should be displayed.

The parameter uses the 2-letter language codes, as defined in the ISO 639-1 standard.

You can also set fallback options, for example, is,en. The document is displayed in the first available language. If the language requested is not supported, the parameter is ignored.

adri
integer <int32> Nullable

The index number of the embedded document.

Setting this parameter displays the document embedded in the core processing document of the message. Embedded documents are indexed using a zero-based index.

Responses

200

Success

get /api/v1/messages/display/{id}
/api/v1/messages/display/{id}

Party

GET /parties/:pid

Returns information about a particular party, specifically the company name. Users need to supply the party's identifier.

path Parameters
id
required
string Nullable

The ISO identifier of the business participant in the {identifierType}:{identifier} format, for example, KT:xxxxxxyyyy.

Responses

200

Success

get /api/v1/parties/{id}
/api/v1/parties/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "identifier": "KT:2222228899",
  • "name": "Supplier Company"
}

GET /parties/:pid/transactions

Retrieves receiving transactions that a particular party is capable of handling.

Receiving transactions are associated with a particular receiving role that determines which documents the party can receive in the scope of one business profile. In other words, by registering different business transactions, business participants define which document specification they accept.

If a business participant has no transactions registered in the given business transaction group, the request returns a 200 OK response code and an empty array.

If the identifier type in the identifier of the business participant is not valid, the call returns a 422 Unprocessable Entity response code.

path Parameters
id
required
string Nullable

The ISO identifier of the business participant in the {identifierType}:{identifier} format, for example KT:xxxxxxyyyy.

query Parameters
action
required
string

The name of the transaction group indicating the action that should be performed on the data, for example, SubmitInvoice, CorrectWithCredit, or SubmitOrder.

includeAll
boolean
Default: true

Lets you select whether you want to see all the transactions or only those that have been registered for this party. All transactions include the registered transactions and the transactions that can be supported after the documents are transformed to one of the registered document specifications.

The default value of the parameter is true, which means that all transactions are shown. To see only the transactions that have been registered for the party, set the value to false.

Responses

200

Success

get /api/v1/parties/{id}/transactions
/api/v1/parties/{id}/transactions

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

POST /parties/transactions/batch-query

Makes a batch query to retrieve receiving transactions of a number of parties for a specific business transaction group.

The limit is 120 entries per request.

The results returned have one of the following statuses: Ready, NoRecordFound, or PendingLookup. The PendingLookup status means that the results are not final and that a subsequent query may result in either Ready or NoRecordsFound.

query Parameters
action
required
string

The name of the transaction group indicating the action that should be performed on the data, for example, SubmitInvoice, CorrectWithCredit, or SubmitOrder.

idType
required
string

The type of the party identifier used in the query, for example, KT or 0196.

Request Body schema:
Array
string

Responses

200

Success

400

Bad or missing payload.

post /api/v1/parties/transactions/batch-query
/api/v1/parties/transactions/batch-query

Request samples

Content type
Copy
Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

Transaction

POST /transactions/submit-order

Creates a SubmitOrder business transaction from a metadata structure.

The more parameter of the call informs the server whether additional document attachments are expected or not and then updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset.

The following example contains the minimum JSON body required to create a valid order. These elements are mandatory.

{
    "messageHandling": {
        "receiverIdentifier": "KT:2222228899",
        "fallbackEmailAddress": "seller-example@unimaze.com"
    },
    "order": {
        "orderNo": "ORD1234",
        "issueDate": "2019-05-26T10:15:42.774Z",
        "currencyCode": "USD",
        "customer": {
            "name": "Test Party One",
            "identifier": "KT:1111118899",
            "address": {
                "streetNameAndNumber": "42nd Street 1",
                "city": "New York",
                "postalZone": "10036",
                "countryCode": "US"
            }
        },
        "supplier": {
            "name": "Test Party Two",
            "identifier": "KT:2222228899",
            "address": {
                "streetNameAndNumber": "14th Street 52",
                "city": "New York",
                "postalZone": "10011",
                "countryCode": "US"
            }
        },
        "orderLines": [
          {
            "name": "Product A",
            "quantity": 1,
            "unitOfMeasure": {
                "unit": "Rec20",
                "code": "KHZ"
            },
            "unitPriceAmount": 1000
          }
        ]
    }
}

The request body schema includes all mandatory and optional elements.

For more information about allowed values for metadata elements, see Metadata.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

conversationIdentifier
string Nullable

The identifier of the conversation. Used as a correlation identifier between different documents in the same business context, for example, between a credit note that was issued based on an invoice and that invoice.

If not provided, it is generated automatically. In that case, it includes the date when the message was sent, a random token, and the ISO identifier of the sender.

more
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

processingMode
string (TransactionProcessingMode)
Enum: "Default" "Routed" "Device"

The way the transaction is processed.

services
Array of strings Nullable

A list of services that the user specifies for additional message processing.

Request Body schema: application/json
messageHandling
required
object (MessageHandlingMetadata)

Message delivery information.

order
required
object (OrderMetadata)

The metadata structure of an order.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/transactions/submit-order
/api/v1/transactions/submit-order

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageHandling":
    {
    },
  • "order":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "c99a321d-18dc-4ac2-92a0-90a2d9196a3e",
  • "timeReceived": "2020-06-25T15:11:47.7789241Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

GET /transactions/submit-order

Retrieves the metadata structure from an order together with the message information.

The call parses an XML business document whose document type is Order and the associated business transaction group SubmitOrder. The document is located using the unique message identifier (GUID).

The call returns a JSON that includes details about the message and the order metadata. The metadata returned matches the metadata structure used in the POST /transactions/submit-order call.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Order metadata

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/transactions/submit-order
/api/v1/transactions/submit-order

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageInfo":
    {
    },
  • "order":
    {
    }
}

POST /transactions/submit-invoice

Creates a SubmitInvoice business transaction from a metadata structure.

The more parameter of the call informs the server whether additional document attachments are expected or not and then updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset. A message with the status pending review will be reviewed and fixed if the data input is consistent. The following example contains the minimum JSON body required to create a valid invoice. These elements are mandatory.

{
    "messageHandling": {
        "receiverIdentifier": "KT:2222228899",
        "fallbackEmailAddress": "buyer-example@unimaze.com"
    },
    "invoice": {
        "invoiceNo": "INV1234",
        "issueDate": "2019-05-26T10:15:42.774Z",
        "currencyCode": "ISK",
        "orderReference": {
            "documentNo": "ORD4512",
            "issueDate": "2019-05-14T15:11:45.344Z"
        },
        "supplier": {
            "vatNumber": "99123",
            "name": "Test Party One",
            "identifier": "KT:1111118899",
            "address": {
                "streetNameAndNumber": "42nd Street 1",
                "city": "New York",
                "postalZone": "10036",
                "countryCode": "US"
            }
        },
        "customer": {
            "name": "Test Party Two",
            "identifier": "KT:2222228899",
            "address": {
                "streetNameAndNumber": "14th Street 52",
                "city": "New York",
                "postalZone": "10011",
                "countryCode": "US"
            }
        },
        "invoiceLines": [
          {
            "itemNo": "A301",
            "name": "Product A",
            "quantity": 1,
            "unitOfMeasure": {
                "unit": "Kilogram"
            },
            "unitPriceAmount": 1000,
            "taxCategoryType": "StandardRated",
            "taxableAmount": 1000,
            "taxAmount": 240,
            "taxPercentage": 24
          }
        ]
    }
}

The request body schema includes all mandatory and optional elements.

For more information about allowed values for metadata elements, see Metadata.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

conversationIdentifier
string Nullable

The identifier of the conversation. Used as a correlation identifier between different documents in the same business context, for example, between a credit note that was issued based on an invoice and that invoice.

If not provided, it is generated automatically. In that case, it includes the date when the message was sent, a random token, and the ISO identifier of the sender.

more
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

processingMode
string (TransactionProcessingMode)
Enum: "Default" "Routed" "Device"

The way the transaction is processed.

services
Array of strings Nullable

A list of services that the user specifies for additional message processing.

Request Body schema: application/json
messageHandling
required
object (MessageHandlingMetadata)

Message delivery information.

invoice
required
object (InvoiceMetadata)

The metadata structure of an invoice.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood but could not be processed.

post /api/v1/transactions/submit-invoice
/api/v1/transactions/submit-invoice

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageHandling":
    {
    },
  • "invoice":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "0c3cf88d-3d73-4aeb-b2e6-3936954f51f3",
  • "timeReceived": "2020-06-25T15:11:48.0789414Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

GET /transactions/submit-invoice

Retrieves the metadata structure from an invoice together with the message information.

The call parses an XML business document whose document type is Invoice and the associated business transaction group SubmitInvoice. The document is located using the unique message identifier (GUID).

The call returns a JSON that includes details about the message and the invoice metadata. The metadata returned matches the metadata structure used in the POST /transactions/submit-invoice call.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Invoice metadata

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/transactions/submit-invoice
/api/v1/transactions/submit-invoice

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageInfo":
    {
    },
  • "invoice":
    {
    }
}

POST /transactions/correct-with-credit

Creates a CorrectWithCredit business transaction from a metadata structure.

The more parameter of the call informs the server whether additional document attachments are expected or not and then updates the message status. If no more documents will be added, the call sets the status of the message to received. Otherwise, the message remains open and the message status is notset.

The following example contains the minimum JSON body required to create a valid credit note. These elements are mandatory.

{
    "messageHandling": {
        "receiverIdentifier": "KT:2222228899",
        "fallbackEmailAddress": "buyer-example@unimaze.com"
    },
    "creditNote": {
        "creditNoteNo": "CN1234",
        "issueDate": "2019-05-26T10:15:42.774Z",
        "currencyCode": "ISK",
        "supplier": {
            "vatNumber": "99123",
            "name": "Test Party One",
            "identifier": "KT:1111118899",
            "address": {
                "streetNameAndNumber": "42nd Street 1",
                "city": "New York",
                "postalZone": "10036",
                "countryCode": "US"
            }
        },
        "customer": {
            "name": "Test Party Two",
            "identifier": "KT:2222228899",
            "address": {
                "streetNameAndNumber": "14th Street 52",
                "city": "New York",
                "postalZone": "10011",
                "countryCode": "US"
            }
        },
        "creditNoteLines": [
          {
            "itemNo": "A301",
            "name": "Product A",
            "quantity": 1,
            "unitOfMeasure": {
                "unit": "Rec21",
                "code": "BX"
            },
            "unitPriceAmount": 1000,
            "taxCategoryType": "StandardRated",
            "taxableAmount": 1000,
            "taxAmount": 240,
            "taxPercentage": 24
          }
        ]
    }
}

The request body schema includes all mandatory and optional elements.

For more information about allowed values for metadata elements, see Metadata.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

conversationIdentifier
string Nullable

The identifier of the conversation. Used as a correlation identifier between different documents in the same business context, for example, between a credit note that was issued based on an invoice and that invoice.

If not provided, it is generated automatically. In that case, it includes the date when the message was sent, a random token, and the ISO identifier of the sender.

more
required
boolean

Signals if the current document is the last document that the message is supposed to contain. If that is true, the processing starts immediately.

processingMode
string (TransactionProcessingMode)
Enum: "Default" "Routed" "Device"

The way the transaction is processed.

services
Array of strings Nullable

A list of services that the user specifies for additional message processing.

Request Body schema: application/json
messageHandling
required
object (MessageHandlingMetadata)

Message delivery information.

creditNote
required
object (CreditNoteMetadata)

The metadata structure of a credit note.

Responses

201

Message information

400

Invalid input parameters.

422

The request was understood, but could not be processed.

post /api/v1/transactions/correct-with-credit
/api/v1/transactions/correct-with-credit

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageHandling":
    {
    },
  • "creditNote":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "uniqueId": "7a0e216a-088d-47ff-a014-e9de359cd0b2",
  • "timeReceived": "2020-06-25T15:11:48.1959512Z",
  • "documentNo": "INV19093078",
  • "status": "delivered",
  • "transfer": "outbound",
  • "validationStatus": "approved",
  • "service": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0##PEPPOL-3.0-ENUBL",
  • "action": "SubmitInvoice",
  • "conversation": "200625:749235:KT:1111118899",
  • "referenceInformation": "72980 ISK",
  • "originParty":
    {
    },
  • "destinationParty":
    {
    },
  • "documents":
    [
    ]
}

GET /transactions/correct-with-credit

Retrieves the metadata structure from a credit note together with the message information.

The call parses an XML business document whose document type is CreditNote and the associated business transaction group CorrectWithCredit. The document is located using the unique message identifier (GUID).

The call returns a JSON that includes details about the message and the credit note metadata. The metadata returned matches the metadata structure used in the POST /transactions/correct-with-credit call.

query Parameters
messageId
required
string <uuid>

The identifier of the message in the format of a valid Universally unique identifier (GUID).

Responses

200

Credit note metadata

400

Invalid input parameters.

422

The request was understood but could not be processed.

get /api/v1/transactions/correct-with-credit
/api/v1/transactions/correct-with-credit

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "messageInfo":
    {
    },
  • "creditNote":
    {
    }
}