REST API

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.

Establish access with the access point

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

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 and can verify your integration by sending a single test invoice to DIFI's test recipient. You should shortly after (within 15 minutes) be able to see that it has been delivered to DIFI.

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 front page. You will instantly be able to exchange messages with all other PEPPOL receivers in production.

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.

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 0192:810017902.

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:ORG is 0192. A full ParticipantID could then be 0192:976098897.

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

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.

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.

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

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

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

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.

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=@invoice_bis30_ubl.xml'
    -F 'SenderID=0192:976098897'
    -F 'RecipientID=0192:987601787'
    -F 'ChannelID=PEPPOL'
    -F 'ProcessID=urn:fdc:peppol.eu:2017:poacc:billing:01:1.0'
    -F 'DocumentID=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'
    https://ap-test.unit4.com/outbox

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

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

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:

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='0192:976098897'&direction=OUT

With URL encoding, this would look like:

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

Response: a list of messages.

WARNING

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

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