# Pagero Interchange and HTTP client solutions

# Introduction

Hypertext Transfer Protocol Secure (HTTPS) is an extension of HTTP.

HTTPS is a widely used secure transfer protocol that is encrypted using transport layer security (TLS).


# What we offer

We offer both an HTTP endpoint called Pagero Interchange and the possibility to send to an HTTP server utilizing a HTTP client.

The Pagero Interchange is a simple API in order to enable use-cases that don't need the full functionality that our REST APIs offer.

More information about our full set of APIs can be found in the REST APIs section.

REST APIs
../../../partners/apis/


# Prerequisites

Prior to being able to utilize the Pagero HTTP offering, your internal integration solution needs to support the sending of data through an HTTP client or being able to receive data through an HTTP server.

When ordering the HTTP Connectivity Setup, either from Pagero Store or by your sales representative, and the setup has been finalized by Pagero you will receive an interconnect specification with the connectivity details.


# Security

Security is achieved by using transport layer security (TLS).

TLS encrypts the connection and makes sure that only Pagero Online or the receiving server can read the transferred data.

# Supported TLS versions and cipher suites

For more information about supported TLS versions and cipher suites, please see the following section.

IPs, TLS and cipher suites
../../ips-tls-ciphers-suites/#transport-layer-security-tls


# Pagero Interchange

# How to send

An HTTP request is sent to the endpoint URL corresponding with the authentication method, document type and send mode for the expected use case.

# Authentication method

We support two methods of authentication.

More info about token authentication can be found in the API authentication section.

API authentication
../../../partners/apis/api-authentication-authorization/

# Response

For each request, a response will be given according to standard HTTP protocol responses.

# Success

For a successful request, Pagero Online will return HTTP response code 200.

Positive HTTP 200 response example
HTTP/1.1 200 OK
Date: Mon, 27 Jul 2022 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 22 Jul 2022 19:15:56 GMT
Content-Length: 88
Content-Type: text/html
Connection: Closed

# Error

Depending on the error, HTTP response codes 4xx or 5xx will be given.

Negative HTTP 400 response example
HTTP/1.1 400 Bad Request
Date: Sun, 18 Oct 2022 10:36:20 GMT
Server: Apache/2.2.14 (Win32)
Content-Length: 230
Content-Type: text/html; charset=iso-8859-1
Connection: Closed

For additional information, see HTTP protocol level response.

# Endpoint URL

The endpoint URLs consist of protocol + hostname + subpath.

The subpath consists of authentication method* + default + document type + send mode.

Endpoint URL structure
https://www.pageroonline.com/incoming/{authMethod}/default/{documentType}/{sendMode}

*only applicable for token authentication.

# Document types

The subpath in the URL consists of document type to be sent, send mode and the previously mentioned authentication method, if applicable.

The following table shows the possible document types.

Document Type URL subpath part
Application Response applicationresponse
Catalogue catalogue
Dispatch Advice dispatchadvice
Invoice invoice
Order order
Order Agreement orderagreement
Order Change orderchange
Order Cancellation ordercancellation
Order Response orderresponse
Payment Reminder paymentreminder
Receipt Advice receiptadvice
Technical Response receipt
Transport Instruction transportinstruction
Transport Status transportstatus
Utility Statement utilitystatement

# Send modes

Send mode is set as part of the subpath in the endpoint URL. For more information about what different send modes is supported, see send mode section.

Send modes
../../../additional-functionality/send-modes/

# Endpoint URL examples

URL example of sending an invoice in production mode with basic authentication
https://www.pageroonline.com/incoming/default/invoice/prod 
URL example of sending an invoice in production mode with token authentication
https://www.pageroonline.com/incoming/tokenauth/default/invoice/prod 

# Headers

The Pagero Interchange endpoint make use of the following HTTP headers.

Header name Description
x-interchange-id Sender's identifier for the payload. Filename is commonly used but could be a unique id such as UUID which is defined in RFC 4122.
x-company-id Unique identifier supplied by Pagero. Only required in multicompany setups.

# Example request

Example of an UBL XML invoice sent to Pagero Online using HTTPS with the x-interchange-id-header as described above.

HTTP Request example to Pagero interchange
POST incoming/default/invoice/test HTTP/1.1
x-interchange-id: Invoice-1234567890
Content-Type: application/xml
Content-Length: 151
Host: www.pageroonline.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5 (Java/1.7.0_72)

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:ID>1234567890</cbc:ID>
    <!-- Omitted for clarity -->
</Invoice>

# HTTP client solution

Pagero HTTP client is a simple client posting the business document in the body of the HTTP request.

# Authentication method

Our HTTP client supports the following methods of authentication.

# Headers

We can configure any specific HTTP header/s you may require.

# Static content

We can set any static content you may require.

There is no real limitation on how many separate headers we can configure.

# Dynamic content

We can also use business document content to set dynamic content in HTTP headers.

Of course, a prerequisite for this is that the data needs to exist in the business document in order for it to be able to be fetched and added as an HTTP header.

# Settings

We support a variety of HTTP settings in our HTTP client - please let us know what you need when ordering the setup.


# Attachment handling

This section shows available options for sending and receiving attachments with Pagero Interchange and HTTP client solution.

For more information about attachments, please see the attachment section.

Attachments
../../../additional-functionality/attachments/

# Embedded in the format

Transfer of the attachment can also be done by embedding the attachment in the business document if the document format you send supports it.

There are several ways to embed an attachment but the most common one is to encode the attachment using base64 and add to the business document according to format specification.

Embedded attachments
../../../additional-functionality/attachments/#embedded

# Batched

There are several different ways to batch files, one of the most common alternatives is to compress the files into a zip file. Please note that even though all files are batched and sent as one file there would still need to be a file naming convention inside the zip file to match attachments to the main document.

We recommend sending one business document with corresponding attachments per batched file. We do not recommend sending several business documents within the same file.

Batched attachments
../../../additional-functionality/attachments/#batched-attachments