Pagero Cloud Link : Integrating with Pagero Online                                                       Date: 2017-04-05

Authors: Pagero R&D                                                                        Information class: PUBLIC


Pagero Cloud Link - API

Integrating with Pagero Online


Introduction

This document describes the integration API available for connecting to the Pagero Online e-business network platform.

Pagero Online is a cloud platform for the exchange of business documents supporting the purchase to pay and order to cash processes; in particular

There are a number of options for integrating with Pagero Online. These all go under the concept name of Pagero Cloud Link Services.

The API is primarily for integrators, software houses and other cloud solution providers who want to integrate Pagero Online into their solution offering. The remainder of this document treats the API integration toolkit.

Scope

The current version of this document contains a description of an API that can be used to integrate with Pagero Online.

Purpose

The purpose of the API is to allow third party companies to integrate with Pagero Online directly from a business system that supports (parts of) the purchase-to-pay and order-to-cash processes. The primary focus in the current version of the API are

API version 1.0 documentation

This section describes the API to be used for access to Pagero Online to work with documents.

Terms and definitions

This section defines some terms relevant to the use of the API

Term

Definition

File

a file containing a set of documents sent to Pagero Online for processing

Document

a business document of a certain type (supplier invoice, purchase order, etc) that is the result of the processing of a File

Technology

The API for integrating with Pagero Online is based on REST technology. Data is transferred between the server and the client using Json objects.

Prerequisites

In order to start developing against this API you need to have an agreement with Pagero that allows you access to the API.

It is the integrator's responsibility to develop and test the API integration and make the judgement call about whether the client code is production ready. Pagero recommends thorough testing, and a defensive programming style in order to ensure proper error- and exception-handling on the client side.

Security

Access to the API is protected by requiring the use of SSL to secure the HTTP connection. Further to this, basic authentication is required for a client to get access to the service.

For auditing and security every application calling the REST APIs must supply valid credentials as well as a valid api key that will be issued by Pagero. The api key is transferred using an HTTP header with appropriate values to the request.

Header name

Header value

x-api-application

Name of the application

x-api-key

Password for the application

Accounts and access

Before you start coding, you need to have Pagero to set up an account in Pagero Online.

API Reference

This section describes the functionality provided in the API used to integrate with Pagero Online.

Service URLs

The base API URL is https://www.pageroonline.com/api/v1

Documentation

The services are documented and updated online, where a simple web based GUI is provided from which the services can be tested directly. This document provides examples of usage and some sample code.

Online documentation URLs

https://www.pageroonline.com/api/doc (requires valid credentials)

Please visit the url to get details about the latest version of the API and to download the example code, which you will find at the top of the page.

Identification of resources

CompanyIds, Documents, Attachments and so on are all identified by a resource id, that use the following identification schema:

<TYPE:NUMBER>

For example:

INVOICE:1223456

ORDER_RESPONSE:12345

More information about identifiers is here: Pagero Online business party identifiers

Error messages

Error messages are returned for all requests as well as the regular HTTP statuses.

Error messages look like this:

Example error response

{

   "status": 400,

   "message": "The parameter [payload] is mandatory",

   "technicalMessage": ""

}

General meaning of Status codes

Status codes follow the pattern found in http protocol spec, and thus should feel familiar to those developers familiar with HTTP.

Status code

Meaning

200

Ok

400

if there is something wrong with the (query-) parameters

404

requested object not found

500

Unknown internal error

Search results

Queries that can return multiple results will return a json structure as shown below

{
 "meta": {
   "offset":
0,
   "limit":
20,
   "total_count":
0
 },
 "objects": []

}

The meta structure contains information about the search query results and the objects structure contains the actual list of results. The meta data can be used for pagination when large results are returned.

Offset

Description

offset

Starting number in result list

limit

Number of results

total_count

Total number of results

The File endpoint

This section describes how to send files to Pagero Online using the API and check the status of uploaded files.

Base resource URL: /file

Method

Resource

Description

POST

/file/

Upload a file

GET

/file/{id}

Get meta-data and status of uploaded file

Upload file

Uploading a file is done by populating a multipart HTTP request with valid data and posting it to the resource.

The file that can be uploaded can be of various types, best described through a few examples:

documents the main document must be in a structured format (XML, text or EDIFACT).

OK

Nothing is returned, only a header is set [Location] => <created file id>

Examples
Ok - Request payload

------SomeBoundary

Content-Disposition: form-data; name="fileId"

myfile.xml

------SomeBoundary

Content-Disposition: form-data; name="sendType"

Test

------SomeBoundary

Content-Disposition: form-data; name="mimeType"

application/xml

------SomeBoundary

Content-Disposition: form-data; name="encoding"

UTF-8

------SomeBoundary

Content-Disposition: form-data; name="payload"; filename="myfile.xml"

Content-Type: text/xml

------SomeBoundary--

Ok - Response data
Ok - Response headers

Location: FILE:500000011

Check status of uploaded file

Check status by performing a GET against the base URL with the id of the file.

OK

Returns a json structure containing meta data about the file. Possible status content:

Examples
Ok - Request

https://www.pageroonline.com/api/v1/file/FILE:00000011

Ok - Response data

{
 "id":
500000011,
 "fileId":
"MyFile",
 "mainStatus": {
   "status":
"Received by Pagero Online",
   "statusDescription":
"The document is received by Pagero Online and is waiting to be processed."
 },
 "modifiedTime":
"2013-04-09T09:22:12.669+0200",
 "failedFileParts": [],
 "manualHandlingNeededFileParts": []
}

Missing file - Request

https://www.pageroonline.com/api/v1/file/FILE:00000011

Missing file - Response data

{
 "status":
404,
 "message":
"No file found for id: 00000011",
 "technicalMessage":
""
}

The Document endpoint

This section describes the API for accessing the document service, that is accessing documents that are the result of file processing.

Base resource URL: /document

Method

Resource

Description

GET

 /document/

List documents for the logged in user. NOTE!! Use the offset and limit (max limit  at a time) parameters in the meta data to page the result. Otherwise, you may experience performance issues. The default limit is 20.

GET

 /document/{id}

Retrieve meta-data for a specific document

GET

/document/download/{id}

Download actual document or attachment data

GET

/document/presentation/{id}

Download the primary presentation for the document. If no primary presentation exists, it will be generated.

Handling timestamps

When using the parameters that holds a timestamp including timezone, be sure to URL encode the value before sending it to Pagero Online otherwise some information may be scrambled and you will not get the intended result.

Example

The value 2013-01-17T11:56:21.765+0100 needs to be sent as 2013-01-17T11%3A56%3A21.765%2B0100

If you do not follow this requirement an error similar to this will be returned as the response:

{

  "status": 400,

  "message": "The date: 2016-12-01T11:11:11.765 0100 does not have a valid format",

  "technicalMessage": ""

}

Attachments

There is only one primary presentation attachment - the one intended to be presented as a human readable document in a workflow system or similar. Use the isPrimaryPresentation propertyof the DocumentAttachmentDTO to determine whether an attachment is the primary presentation.

There will always be only one legal document attached to an invoice document. By default the legal document attachment is made available through the API. However, note that settings in Pagero Online may turn off the distribution of a legal doc. Use the legalDocument property of the DocumentAttachmentDTO to determine whether an attachment is the legal document.

Please also note that one attachment may both be the legal doc and the primary presentation. An API client should take this into consideration when looping the list of attachments.

Attachment types

Description

PROVIDED_PRESENTATION

A presentation document provided by the sender of the document.

GENERATED_PRESENTATION_SENDER

A presentation (human readable) document generated by Pagero Online on behalf of the sender

GENERATED_PRESENTATION_RECEIVER

A presentation (human readable) document generated by Pagero Online on behalf of the receiver

SOURCE

Document that is the source for the  machine readable file generated for the receiver.

SOURCE_PRESENTATION

Document that is the source for the  machine readable file generated for the receiver, where the source is also a presentation document.

SOURCE_ATTACHMENT

MISC

Misc attachment

DELIVERY_NOTE

A delivery note attachment

CONTRACT

A contract attachment

REGISTRATION_LETTER

Registration letter used for onboarding of e-document receivers.

PRINTING_AGENCY_GENERATED_PRESENTATION

A presentation document generated by the printing agency (when the document was sent via print/paper)

LEGAL_PROVIDED

A legal document (invoice) provided by the sender

LEGAL_PROVIDED_PRESENTATION

A legal document (invoice) provided by the sender, where the legal document is also a presentation/human readable.

LEGAL_SOURCE

A legal document (invoice) provided by the sender, where the legal document is also used to extract data for a machine readable format provided to the receiver.

LEGAL_SOURCE_PRESENTATION

A legal document (invoice) provided by the sender, where the legal document is also a presentation/human readable and was used to extract data for a machine readable format provided to the receiver.

LEGAL_GENERATED_UNSIGNED_PRESENTATION

A legal document generated by Pagero Online, without the use of digital signatures

LEGAL_SIGNED_DOCUMENT

A legal document generated by Pagero Online, with the use of digital signatures

LEGAL_SIGNED_PRESENTATION

A legal document generated by Pagero Online, with the use of digital signatures, and where the legal document is also a presentation/human readable document.

LEGAL_VALIDATED_DOCUMENT

A legal document that is digitally signed, and where the signature has been validated.

LEGAL_VALIDATED_PRESENTATION

A legal document that is digitally signed, and where the signature has been validated. The document is also a presentation document

List documents

Return information about the given company’s documents; or if companyId was not given return information about documents for all companies the user has access to.

Examples
Ok - request

https://www.pageroonline.com/api/v1/document?direction=RECEIVED&attachmentFilter=DISTRIBUTED&offset=0&limit=20

Ok - response, no document matched query

{
 "meta": {
   "offset":
0,
   "limit":
20,
   "total_count":
0
 },
 "objects": []
}

Ok - request

https://www.pageroonline.com/api/v1/document?direction=RECEIVED&attachmentFilter=DISTRIBUTED&offset=0&limit=20

Ok - response, documents matched query

{
 "meta": {
   "offset":
0,
   "limit":
20,
   "total_count":
1
 },
 "objects": [
   {
     "id":
"INVOICE:44915910",
     "documentId":
"I2387”,
      "createDate": "2011-06-23T11:37:50.155+0200",
     "modifiedDate":
"2011-11-03T14:02:34.648+0100",
     "attachments": [
       {
         "type":
"LEGAL_SOURCE",
         "mimeType":
"application/pdf",
         "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/ATTACHMENT:44915911",
         "primaryPresentation":
false,

   "legalDocument": “true”,
         "name":
"ATTACHMENT",
         "createDate":
"2011-06-23T11:37:50.451+0200",
         "modifiedDate":
"2011-06-23T11:37:50.451+0200"
       },
       {
         "type":
"GENERATED_PRESENTATION_SENDER",
         "mimeType":
"application/pdf",
         "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/ATTACHMENT:44916286",
         "primaryPresentation":
true,

   "legalDocument": false
         "name":
"ATTACHMENT",
         "createDate":
"2011-06-23T11:40:37.121+0200",
         "modifiedDate":
"2011-06-23T11:40:37.121+0200"
       }
     ],
     "partyInformation": {
       "name":
"Test: EDBReceiver",
       "department":
"Test",
       "orgNo":
"123456785",
       "vatNo":
"NO123456785MVA",
       "gs1prefix":
null
     },
     "sendtype":
"Certification",
     "mimeType":
"text/xml",
     "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/INVOICE:44915910",
     "name":
"test_44915910.xml",
     "invoiceDate":
"2011-06-23", //NOTE!! Will be  removed, use documentDate instead
     "documentDate":
"2011-06-23",

      "sourceMediaType": "E_DOCUMENT", // E_DOCUMENT, SCAN_PAPER, SCAN_EMAIL
     "deliveryStatus":
"W", // List of status below
     "dueDate":
"2011-07-14",
     "currency":
"NOK",
     "totalAmount":
2465,
     "netAmount":
null,
     "vatAmount":
390.21
   }
 ]
}

Retrieve a specific document

Return information of the document.

Examples
Ok - request

https://www.pageroonline.com/api/v1/document/INVOICE:123456?attachmentFilter=DISTRIBUTED

Ok - response, no document matched query

{
 "status":
404,
 "message":
"Unable to locate a document with id <INVOICE:123456>.",
 "technicalMessage":
""
}

Ok - request

https://www.pageroonline.com/api/v1/document/INVOICE:44915910?attachmentFilter=DISTRIBUTED

Ok - response, document matched query

{
 "id":
"INVOICE:44915910",
 "createDate":
"2011-06-23T11:37:50.155+0200",
 "modifiedDate":
"2011-11-03T14:02:34.648+0100",
 "attachments": [
   {
     "type":
"LEGALS_SOURCE",
     "mimeType":
"application/pdf",
     "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/ATTACHMENT:44915911",
     "primaryPresentation":
false,

"legalDocument": true     
     "name":
"ATTACHMENT",
     "createDate":
"2011-06-23T11:37:50.451+0200",
     "modifiedDate":
"2011-06-23T11:37:50.451+0200"
   },
   {
     "type":
"GENERATED_PRESENTATION_SENDER",
     "mimeType":
"application/pdf",
     "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/ATTACHMENT:44916286",
     "primaryPresentation":
true,

      "legalDocument": false
     "name":
"ATTACHMENT",
     "createDate":
"2011-06-23T11:40:37.121+0200",
     "modifiedDate":
"2011-06-23T11:40:37.121+0200"
   }
 ],
 "partyInformation": {
   "name":
"Test: EDBReceiver",
   "department":
"Test",
   "orgNo":
"123456785",
   "vatNo":
"NO123456785MVA",
   "gs1prefix":
null
 },
 "sendtype":
"Certification",
 "mimeType":
"text/xml",
 "downloadUrl":
"https://www.pageroonline.com/api/v1/document/download/INVOICE:44915910",

  “primaryPresentation" : "https://www.pageroonline.com/api/v1/document/presentation/INVOICE:131700",
 "name":
"test_44915910.xml",
 "invoiceDate":
"2011-06-23", // Will be removed, use documentDate instead

  "documentDate": "2011-06-23",

  "sourceMediaType": "E_DOCUMENT", // E_DOCUMENT, SCAN_PAPER, SCAN_EMAIL
 "deliveryStatus":
"W", // List of status below
 "dueDate":
"2011-07-14",
 "currency":
"NOK",
 "totalAmount":
2465,
 "netAmount":
null,
 "vatAmount":
390.21
}

List of document status

Status

Description

status.WAITING

Waiting to be sent, sending in progress, or sending complete but waiting for acknowledgement

status.ERRORRECEIVER

Sent, but there was a problem on the receiver end. Pagero handles the issue

status.ERRORRECEIVERUSER

Sent, but there was a problem on the receiver end. The customer/User has gotten a notification and needs to handle the issue.

status.DONE

The document has been sent and the transfer was successful

The Provisioning endpoint

The provisioning part of the API covers the registration of new customers for the use of Pagero Online services.

The provisioning API will enable a Pagero partner with a valid API key to register a new company in Pagero Online. At the same time, an administration account for that company will be created. An email will be sent to the owner of the administration account. The email contains an activation link. Upon activation, the user will have to accept the general terms and conditions of the service, and set a password.

Provisioning is initiated using a project code, which defines the services that will be provisioned to the newly registered customer account. The project code will also define default settings to be used for the account, such as formats, etc. Pagero will issue a new project code per partner.

Automatically adding a company to a company group

In Pagero Online it is possible to group companies into “company groups”. This is common for big corporations that consist of many companies, service bureaus or similar where users need to have access to more than one company.

When creating a new company through the API, it is possible to automatically add the company to an existing company group. This is done by providing the name of the company group in the “companyGroup” parameter.

When a company group is specified, it is not mandatory to provide a user (parameter “firstuser”) in the request. Also, if company group is specified, the company will automatically become activated. If a user is provided, an activation mail will be sent to that user.

A company group must be created by Pagero support before it can be used in the API.

SubGroup

In a company group it is possible to organize companies in “sub groups”. It is possible to make a new company end up in a specific sub group by providing the name of the desired sub group in the “subGroup” parameter.

API

Base resource URL: /provisioning

Method

Resource

Description

POST

 /provisioning/company

Register a new company in Pagero Online

GET

 /provisioning/company/{id}

Retrieve data for a company by id for which the logged in user has access to.

Id is a business party id, returned to the client when registering the company.

Register company

https://www.pageroonline.com/api/v1/provisioning/company

Ok - Request data

{

  "numExtraUsers": 0,

  "projectCode": "",

  "companyGroup": "",

  "subGroup": "",

  "company": {

    "companyEmail": "",

    "glnNumber": "",

    "unit": "Finance",

    "address": {

      "additionalStreet": "",

      "department": "Finance",

      "zipCode": "12345",

      "street": "Lilla torget 1",

      "name": "TestCompany",

      "countryCode": "SE",

      "province": "",

      "city": "Gothenburg",

      "postBox": ""

    },

    "companyPhone": "",

    "organizationalId": "",

    "internalUnitNumber": "",

    "orgNo": "5568066913", //mandatory(1)

    "activeUserLimit": 0,

    "vatNo": "", //mandatory(1)

    "gs1prefix": "", //mandatory(1)

    "ovtNo": "", //mandatory(1)

    "ibanNo": "" //mandatory(1)  

  },

  "firstUser": {

    "firstUserUsername": "",

    "language": "",

    "firstUserFullName": "",

    "firstUserEmail": "",

    "firstUserPhone": ""

  }

}* mandatory(1): one of the values are required.

Ok - Response data

{

  "companyName": "TestCompany",

  "department": "Finance",

  "street": "Lilla torget 1",

  "additionalStreet": null,

  "postBox": null,

  "zipCode": "12345",

  "city": "Gothenburg",

  "province": null,

  "countryCode": "SE",

  "companyInternalUnitNumber": null,

  "companyOrgNo": "556806-6913",

  "companyVatNo": null,

  "companyGln": null,

  "authCompanyId": "1344420996",

  "authUserId": null,

  "unit": "Finance"

}

Ok - Response headers
Registration unsuccessful - Response data

Insufficient or bad data will yield a list of errors back to the caller. The response code will be 400 (Bad request)

Example:

[

   "Company organization number is incorrect",

   "Company vat number is incorrect",

   "Company ean number is incorrect"

]

Since this version of the API makes use of data filtering that is based on the logged in user, we need to set up a session. This is done using Basic Authentication. Therefore, if a request is made without being in the context of a session, a 401-challenge will be sent back to the caller.

If a challenge cannot be met with acceptable credentials, or if the data requested is not available to that user, a 403 Unauthorized response will be returned.

Data that cannot be interpreted by the receiving end will render a response with status code 500 (Internal server error)

The Registry endpoint

This section describes the API for interacting with the network of companies registered as part of Pagero Online. The network registry consists of companies that are direct customer of Pagero Online as well as companies that are reachable through other service providers.

Search for a company

https://www.pageroonline.com/api/v1/businessparty/registry?searchTerm=<the term to search for>

The search term can be an organizational number, a vat number or EAN number.

OK response data

{
 "meta": {
   "offset":
0,
   "limit":
20,
   "total_count":
0
 },
 "objects": []
}

Import a list of customers to your customer registry

The ability to upload a list of customers or suppliers to the registry currently requires support credentials and thus is not described here in more detail, since partners do not have this level of access.


Pagero AB | Box 11006 | SE-404 21 Göteborg  | Org.nr: 556581-4695 | Phone: +46-31 730 88 00 | Fax: +46-31 730 88 01

www.pagero.com | www.facebook.com/PageroAB | www.twitter.com/pagero


[1] Not deemed as secure as security is not built in to the protocol