REST API

Introduction

To send and receive business documents like orders and invoices thru the PEPPOL network, Unit4 provides a HTTP based client API as described in this document.

Picture of submit form

Establish access with the access point

There are two separate access points available, one for testing and one for production.

Environment URL Description
TEST https://ap-test.unit4.com/ Send and receive using PEPPOL-SMK test network
PROD https://ap.unit4.com/ Send and receive using PEPPOL-SML production network

NOTE! These URLs might change in the future so keep them configurable in your integration code.

If you want a test account, send an e-mail to support with your company name, organisation number, postal address and a technical contact person (including e-mail and phone). Or you can self regiser a test account online.

To obtain a production account contact sales by email to get correct pricing and system-code. Then simply fill out the registration form by clicking register link at the the front page. You will instantly be able to exchange messages with all other PEPPOL receivers in production and should verify your integration by sending a single test invoice to our test recipient-id: 9908:810017902.

Handling invoices for multiple companies

It is possible to handle invoices for more than one company using a single account, the conditions for doing so are:

  • You may send invoices on behalf of any company by specifying its PEPPOL ParticipantID as sender.
  • You can receive invoices to a company associated with your own account.
  • A company can only be associated with one account for incoming messages.
  • The receiving company must be registered in an PEPPOL SMP (we handle his for you)
  • In order to associate a company with you account contact us by email

In addition to handling the invoices of several companies from a single account it is possible to create multiple accounts paid for by the same company. This allows customers of the access point to create separate accounts for their own customers. To create additional accounts you must contact us by email.

PEPPOL Participant Identifiers

Senders and receivers needs to be identified using their PEPPOL ParticipantID's.

All receivers must be registered in an PEPPOL SMP (catalogue service) with a list of document types they support and which accesspoint they should be delivered to.

The senders do not need any registration, but you must to use a proper ParticipantID of the form CODE:IDENTIFIER, like 9908:810017902.

Identifier Description Example value
RecipientID PEPPOL ParticipantID of the receiver 9908:976098897
SenderID PEPPOL ParticipantID of the sender 0088:1234567890123

PEPPOL ParticipantID is built up with a scheme code (a 4 digit ISO6523 code) followed by a ':' and the actual identififier. In Norway 9-digits organization numbers are used as identififiers and the scheme code for NO:VAT is 9908. A full ParticipantID could then be 9908:976098897.

PEPPOL Document Identifiers

In order to transfer messages you must specify a legal DocumentID and ProcessID (aka ProfileID) combination.

  • Perform a SMP lookup to get a list of DocumentID's the receiver suports (can be many)
  • If you can produce documents matching any of these variants, check that you also know the ProfileID
  • Then you must produce the message with the selcted DocumentID and ProfileID standard
  • You should then validate the message against the rules for this DocumentID and ProfileID combination
  • When all is well - you can send the message using Unit4 Access Point API

The following table are examples of real values. You should always fetch real values by performing SMP lookup (described here).

Identifier Example (Norwegian EHF v2 invoice only)
DocumentID urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.difi.no:ehf:faktura:ver2.0::2.1
ProcessID urn:www.cenbii.eu:profile:bii04:ver2.0

General transfer mechanisms

We have chosen a REST type HTTP transport between the access point and the clients. Transport is secured by HTTPS so make sure your client support TLSv1.2+ and modern chipers.

We use Basic Authentication according to RFC2617. Since communication will be performed using HTTPS, authentication credentials are secured. Make sure you enable Preemptive Basic Authentication in your HTTP client library.

We use XML as data-format for request and response, so make sure your HTTP client adds Accept: application/xml headers.

About the Message Store

All messages will be assigned an unique msg_no (long integer). This will be the key to do operations on the message later.

When you list each of the message stores below you'll get meta-data about the messages. This meta-data includes an URL where you can download the actual message content.

Message Store Description
OUTBOX When you send messages they will be visible here until they are delivered.
INBOX When you receive messages they will be visible here until you have fetched them and marked them as read.
MESSAGES All messages will be available here and simple search and pagination is available.

If the message is received from another access point it is deemed to be inbound and direction is set to "IN".

Messages transferred by us (Unit4 Access Point) to another access point are deemed to have a direction of outbound, hence direction is set to "OUT".

About received, delivered and uuid

The timestamps "received" and "delivered" have slightly different meaning when sending and receiving.

Message direction Received timestamp Delivered timestamp UUID
OUT When uploaded to U4AP by API-user When delivered to receivers AccessPoint Unique transfer ID between AP's
IN When reveived by U4AP from other AccessPoint When downloaded and marked as READ by API-user Unique transfer ID between AP's

API functionality

The table below shows the methods available thru the public api..

Resource name (URL) HTTP methods Description
/outbox POST Places documents into the outbound queue for transmission through the PEPPOL network.
GET Retrieves the status for a message previously placed into the outbound queue.
/inbox GET List of all received messages, which have not been marked as read.
POST Marks a message as read, thus removing it from the /inbox view.
/messages GET List of all messages sent and received. Use query parameters to filter the result set
/directory GET Retrieves information about recipients capable of receiving electronic documents.

Basically you may view the resources /outbox, /inbox and /messages as "views" into the message repository of the access point. I.e. once a message has been sent, it is moved from the "outbox" into the archive of "messages".

A link referencing a message in the /outbox will still be valid once the message has been "moved" to /messages, however; the contents returned will have changed. A message which has been sent will have it's delivered timestamp and transport uuid set.

NOTE! The URL's included in the responses might change and are for illustrative purposes only. Do not hardcode them into your application. You should follow the hyperlinks returned.

API examples

Send outbound messages to PEPPOL recipients

POST /outbox

For each message:

  1. Check what processes and document types the receiver accepts.
  2. Generate an PEPPOL document that conforms to the CustomizationID and ProfileID the receiver accepts.
  3. Validate the contents according to the CEN BII and local/national rules
  4. Send file using the "outbox" resource with correct sender, receiver, process, document and channel identification.
  5. Inspect the status of the transmission. The status is returned immediately as part of the response from the server
  6. Optional : Re-read status later (after an hour or so) to get the DELIVERED timestamp and UUID of the transport

You must use "multipart/form-data", which means that all parameters should be sendt as form-data and not as http-headers.

The following is an example illustrating how you may send the file named "invoice42.xml" using cURL.

curl -i -u %lt;username>:%lt;password>
    -H 'Accept: application/xml' 
    -F 'file=@invoice42.xml'
    -F 'SenderID=9908:976098897'
    -F 'RecipientID=9908:987601787'
    -F 'ChannelID=PEPPOL'
    -F 'ProcessID=urn:www.cenbii.eu:profile:bii04:ver2.0'
    -F 'DocumentID=urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.difi.no:ehf:faktura:ver2.0::2.1'
    https://ap-test.unit4.com/outbox

Form field name Value Example
SenderID The PEPPOL participant identity of the sender 9908:976098897
RecipientID The PEPPOL participant identity of the receiver 9908:986252932
ChannelID User specified classification of document (works much like a tag or category) PEPPOL
DocumentID Full PEPPOL document type identifier that identifies the document format and its customization
ProcessID Full business process/profile in which this document shall be used
file File actual XML payload containing the business document. ... xml-data ...

Uploads the supplied file using the given attributes. The message is placed into the outbound queue for transmission.

Response on success:

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://ap-test.unit4.com/outbox/19

Response on error:

HTTP/1.1 400 Bad Request
Content-Type: text/plain;charset=UTF-8

Wrong documentId value: urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0

List of messages in the outbox

GET /outbox

Retrieves a list of messages which have not yet been transferred into the PEPPOL network.

HTTP/1.1 200 OK
Content-Type: application/xml

Retrieve list of inbound invoices

GET /inbox
  1. Retrieve list of XML documents from the "inbox" resource
  2. For each document in the returned list:
    • Download document using the URL which is provided in the returned list
    • Mark message as received, using the REST call
Response: a list of messages residing in the "inbox". Each item in the list contains meta data about the message along with the URL which should be used to retrieve the message: HTTP/1.1 200 OK
Content-Type: application/xml

Retrieve a single message in the inbox

If you know the message identification, i.e. you wish to check the status of a message having an id of 4:

GET /inbox/4

Reponse: the meta data details for the given message:

HTTP/1.1 200 OK
Content-Type: application/xml

If message with given number doesn't exist, 204 code will be returned.

Marking a message as read

To prevent the message from appearing in the list of unread messages residing in the "inbox", you need to mark it as "read":

POST /inbox/4/read

curl -X POST https://<username>:<password>@ap-test.unit4.com/inbox/4/read HTTP/1.1 200 OK
Content-Type: application/xml

This will set the "delivered" timestamp on the message to the current time stamp on the server. Consequently, this messages will no longer appear in the list of messages returned by "GET /inbox".

Searching for messages

All messages sent and received are available under the resource /messages

You may search messages based on one or more of the following criteria:

  • sent - The time the message was sent to the access point, can be used with any of \<=, =, \<, >, =>
  • sender - The Peppol participant Id of the sender
  • receiver - The Peppol participant Id of the reciever
  • direction - IN or OUT

For example:

GET /messages?sent='>2012-01-30'&sender='9908:976098897'&direction=OUT

With URL encoding, this would look like:

GET /messages?sent='%3E2012-01-30'&sender='9908:976098897'&direction=OUT

Response: a list of messages.

HTTP/1.1 200 OK
Content-Type: application/xml

WARNING

When accessing the /inbox, /outbox or /messages resource, only a maximum of 25 records will be retrieved. If there are more than 25 messages a navigation element will provide links to the previous and next page.

E.g. Accessing third page (https://ap-test.unit4.com/messages?index=3) will result in below output.

Checking if a recipient is connected to the PEPPOL network

In order to determine whether a recipient is connected to the PEPPOL network, you may check using their PEPPOL participant identification:

GET /directory/9908:976098897

The response will contain HTTP/1.1 200 OK if the recipient is connected to the Peppol network, otherwise the response will be HTTP/1.1 204 NOT FOUND:

If you are querying for a recipient using the standard Norwegian prefix of 9908 you may omit the prefix:

GET /directory/976098897

Looking up which document types and busines profiles the recipent accepts

In order to send any document to a given recipient, the proper PEPPOL Document Type Identifier and PEPPOL Process Type Identifier must be included in the XML message and provided in the message headers. You can fetch the list of accepted values by making GET request to the /directory resource specifying the PEPPOL Participant Identification followed by the document LocalName (i.e. 'Invoice', 'CreditNote', 'Order' etc)

GET /directory/9908:810017902/Invoice

NOTE! There can be several possible document types for the supplied "local name" and there might be rules when it comes to which you should use. For cross-border you might have to use the international BIS variant and within a country you might have to select a more specific local variant like EHF (ie, this is mandatory between Norwegian participants).

If there are no accepted document types, 204 code will be returned.

Statistics

In order to monitor the current state of an account a simple get request can be made to obtain the current statistics for the account:

GET /statistics

The response will contain HTTP/1.1 200 OK followed by an XML document containing information regarding the account

All time stamps are in the ISO8601 standard format

References

RESTful Web Services: https://shop.oreilly.com/product/9780596529260.do

RESTful Java with JAX-RS: http://shop.oreilly.com/product/9780596158057.do