E-Post API

User navigation



Language navigation

E-Post API

Close

E-Post API

1. Version History

Version Date  Author Comment
1.0 06.06.2018 Aquilini Sergio, I212Not AccessibleNot AccessibleNot AccessibleNot Accessible First tracked version. Delivery of documents/attachments and synchronous/asynchronous registration.
1.1 08.06.2018 Bernasconi Christian, I234Not AccessibleNot AccessibleNot AccessibleNot Accessible New generalized chapters "API Endpoints and Documentation", "Authentication", "Error response"
1.2 12.06.2018 Biedermann Nicolas, I233 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Added documentation for the asynchronous flow.
1.3 25.06.2018 Hertel Caroline, I212Not AccessibleNot AccessibleNot AccessibleNot Accessible Added url for key exchange
1.31 04.07.2018 Martin François, I313 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Added comment about list unique keys count being not the same as the receiver count
1.32 06.07.2018 Martin, François, I313 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Corrected mistake in "Check Unique Key", where the mode explanations were incorrectly assigned
1.4 23.07.2018 Biedermann Nicolas, I233 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Added chapter about registration priorities
1.5 06.09.2018 Michelucci Fabio, I234 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Added Base64 upload document documentation
1.6 16.10.2018 Aquilini Sergio, I212 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Documented string fields validation
1.61 16.10.2018 Biedermann Nicolas, I233Not AccessibleNot AccessibleNot AccessibleNot Accessible Documented the parameters in the synchronous call of the registration
1.7 15.01.2019 Michelucci Fabio, I234 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Documented new APIs for document status and document status history
1.71 25.01.2019 Biedermann Nicolas, I233 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Documented certificate change for asynchron flow
1.72 25.01.2019 Limonta Stefano, I234 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Added invoice title to the document
1.73 05.03.2019 Biedermann Nicolas, I233 externNot AccessibleNot AccessibleNot AccessibleNot Accessible Removed the max amount of an invoice (previously it was 20'000 CHF)

2. API Endpoints and Doumentation

The table below contains the Urls of the APIs. An interactive documentation which visualizes the API's resources and allows consumers to discover the
capabilities of the services is accessible through the Swagger Framework.

Integration (Stable) - Environment 

Auth. Token  API URI (entry point)  Documentation (Swagger)
https://epost.apiint.post.ch/OAuth/token https://epost.apiint.post.ch/transfer_stable https://epost.apiint.post.ch/transfer_stable/delivery/swagger/ui/index
Integration - Environment - -
Auth. Token API URI (entry point) Documentation (Swagger)
https://epost.apiint.post.ch/OAuth/token https://epost.apiint.post.ch/transfer/delivery/ https://epost.apiint.post.ch/transfer/orders/ https://epost.apiint.post.ch/transfer/keyexchange/ https://epost.apiint.post.ch/transfer/delivery/swagger/ui/index https://epost.apiint.post.ch/transfer/orders/swagger/ui/index https://epost.apiint.post.ch/transfer/keyexchange/swagger/ui/index
Production - Environment - -
Auth. Token
API URI (entry point)
Documentation (Swagger)
https://epost.api.post.ch/OAuth/token
https://epost.api.post.ch/transfer/delivery https://epost.api.post.ch/transfer/keyexchange/
-

The version of an APIs is specified by a version number in the URI, i.e.: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries

When a major change in the APIs is released, the version will be then incremented: https://epost.apiint.post.ch/transfer_stable/delivery/v2/deliveries

3. Authentication

The OAuth client credential flow is used (for more information: https://tools.ietf.org/html/rfc6749

A set of credentials (Client ID and Secret) is generated for each sender. All senders use the same APIs. To avoid any cross-sender-actions, the API will always
perform a cross check between the sender id provided in a request and the user's authentication.

3.1.1 Request

HTTP Method: POST

URL: https://epost.apiint.post.ch/OAuth/token

3.1.1.1. Headers

Key Value
Content-Type application/x-www-form-urlencoded

3.1.1.2. Body

Property
Name 
Type Mandatory Constraints Description
client_id string Y - Public identifier of a sender within the Transfer API.
client_secret string
Y A secret key only known to the application and the authorization server.
grant_type string Y client_credentials
The client can request an access token using its client credentials only.
scope string Y EPOFTRANSFERCLIENT
Mechanism allowing clients to tell the authorization server, what permissions are needed to access resources.

Body

client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy&grant_type=client_credentials&scope=EP
OFTRANSFERCLIENT

3.1.2 Response

HTTP Status Code : 200 OK

3.1.2.1. Body

Property Name Type Description
access_token
string Access token
token_type
string
Bearer
expires_in
int Expiration time in seconds

 

Body

{
"access_token": "eyJlbm...zh9jQ",
"token_type": "Bearer",
"expires_in": 120
}

4. Error response

Our current infrastructure prevents a response body to be returned in case HTTP status codes outside of the 2xx range. To work around that and be able to return further details about the error a 200 status code may be returned even in case of failure, with either one of the following JSON structures in the response body.

Error response sample

{
"httpStatusCode": 400,
"systemMessage": "Delivery with Id '123' not found",
"errorCode": 210
}

Error response sample

{
"httpStatusCode": 400,
"errors": [
{
"parameterName": "title",
"systemMessage": "The Title field is required."
},
{
"parameterName": "invoices[0].beneficiary.accountNumber",
"systemMessage": "The beneficiary account number is not valid."
},
{
"parameterName": "invoices[0].amount",
"systemMessage": "The minimum invoice amount is 0.05 Chf.
}
],
}

Important

If a JSON is returned the client must always look for an "httpStatusCode" parameter and check whether it's value is not in the 2xx range and consider the request as failed even if the actual HTTP Status Code is 200.

The "httpStatusCode" field is currently returned only in case of error but this behaviour may change in the future.

5. Delivery

5.1. Introduction

The purpose of this section is to give an overview of the process flow for the Delivery APIs and to describe the technical details of each API request.

5.2 Overview

The following diagram depicts the delivery process and the API requests. Please note: The authentication part isn't taken into account and is described in a separate chapter (see Chapter AuthenticationNot AccessibleNot Accessible)

Description
1 Create a new delivery order. (Chapter Start new DeliveryNot AccessibleNot Accessible)
2 The generated delivery identifier is returned. This identifier is required in all subsequent requests.
3 Upload the attachment's metadata. (Chapter Add an AttachmentNot AccessibleNot Accessible)
4 The generated attachment identifier is returned. This identifier is needed to upload the related binary file (PDF).
5 Upload the binary, only PDF files are currently supported. (Chapter Add or replace the binary of an attachmentNot AccessibleNot Accessible)
- Steps 3-5 are repeated for each attachment to be delivered.
6 Upload the document's metadata. (Chapter Add a DocumentNot AccessibleNot Accessible)
7 The generated document identifier is returned. This identifier is needed to upload the related binary file (PDF).
8 Upload the binary, only PDF files are currently supported. (Chapter Add or replace the binary of a documentNot AccessibleNot Accessible)
- Steps 6-8 are repeated for each document to be delivered.
9 Inform E-Post Office that all documents have been uploaded and the import process can now be started. If this request is not invoked within 48 hours
of its creation, the delivery expires automatically. Once the request is made, the delivery is in the status "processing". It is now impossible to edit the order or its documents. (Chapter Delivery completeNot AccessibleNot Accessible)
10 A brief summary is returned, containing the amount of documents that have been successfully transfered to E-Post Office. 
11 A background process is started, to import the documents into E-Post Office and deliver them into the receiver's mailbox. 
12 Using this API the sender can check the import status at any time. (Chapter Delivery StatusNot AccessibleNot Accessible
13 The import status along with a progress report is returned. 

5.3 Deliveries

The delivery represents the entire set of documents that need to be sent to a set of users.

5.3.1. Start new delivery

This request creates a new delivery in E-Post Office.

5.3.1.1. Request

HTTP Method: POST
URL:https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveriesNot AccessibleNot Accessible

5.3.1.1.1. Headers

Key  Value
Content-Type application/json
Authorization Bearer eyJlbm...zh9jQ

 5.3.1.1.2. Body
 

Name  Type Mandatory  Constraints  Description 
senderId string Y Max Length 8 The sender's identifier within E-Post Office. This identifier will be provided by SwissPost after the registration for the delivery online service.
correlationId string N Max Length 40 This optional value allows a sender to tag all data related to a delivery. This helps tracing and troubleshooting.

 

Body

{
"senderId": "00000005",
"correlationId": "213456ABCR213"
}
5.3.1.2. Response

HTTP Status Code: 201 Created

The delivery id is returned in the header.

5.3.1.2.1. Headers

Key Value
Location 33

5.3.1.2.2. Errors

Error HTTP Status Code Description Body
Unauthorized, Forbidden 401, 403 The token used is either invalid or expired. -
Invalid Sender Id
200 The sender id is invalid or the authenticated user does not have permission to create deliveries for the sender specified in the request.

{

"systemMessage": "Invalid sender id.",

"httpStatusCode": 400

}

Required body not submitted
200
If the expected body is not submitted, the following error is returned (only if the Content-Type is NOT set)

{

"systemMessage": "The delivery

was not specified",

"httpStatusCode": 400

}

5.3.2. Delivery complete

Signals that a delivery is completed and the import process can be started.
If this request is not invoked within 48 hours after the creation of the delivery, the delivery will automatically expire and no documents will be imported.

5.3.2.1. Request

HTTP Method: POST

URL:https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/{deliveryid}/completeNot AccessibleNot AccessibleNot Accessible

5.3.2.1.1. Headers

Key Value
Content-Type  application/json
Authorization
Bearer eyJlbm...zh9jQ
5.3.2.2. Response

HTTP Status Code: 200 OK

5.3.2.2.1. Body

Property Name Type Description
documents object Provides metrics for document's metadatas and binary files.
documents  metaData int Number of documents with metadata.
documents binaries int Number of documents with binary data.
attachments object Provides metrics for attachment's metadatas and binary files.
attachments metaData int Number of attachments with metadata.
attachments binaries int Number of attachments with binary data.
deliveryStatus int Status of the delivery. Created = 0, Processing = 1, Completed = 2, Expired = 3.

 

Body sample

{
"documents": {
"metaData": 5,
"binaries": 5
},
"attachments": {
"metaData": 2,
"binaries": 2
}
"deliveryStatus": 0
}

5.3.2.2.2. Errors

Error HTTP Status Code Description Body
Unauthorized, Forbidden
401, 403 The token used is either invalid or expired. -
Invalid delivery Id
200 The id provided is unknown or associated to another sender.

{

"systemMessage": "The delivery id is
invalid",

"httpStatusCode": 400

}

5.4. Attachments

5.4.1. Add an attachment

This request adds an attachment to a delivery. Please note that the attachment is defined with all its metadata, but not the binary itself and a maximum of 100
attachments can be associated to a delivery.

5.4.1.1. Request

HTTP Method: POST
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/{deliveryid}/attachments

5.4.1.1.1. Headers

Key Value
Content-Type  application/json 
Authorization  Bearer eyJlbm...zh9jQ 

 5.4.1.1.2. Body

Property Name Type Mandatory Constraints Description
itle string Y Max Length 65 The title / subject to be displayed to the user.
correlationId string N Max Length 40 Correlation id that allows tracing in logs.

Body sample

{
"title": "string",
"correlationId": "string"
}
5.4.1.2. Response

HTTP Status Code: 201 Created

The generated attachment id is returned in the location header.

Headers

Location: 33
5.4.1.2.1. Errors
Error HTTP Status Code Description Body
Unauthorized 401 The token used is either invalid or expired. -
Delivery not found 404 The specified delivery identifier was not found. -
Invalid request 200 The request is not valid. {
"errors": [
{
"parameterName": "title",
"systemMessage": "The field Title must be a string with a
maximum length of 65."
}
],
"httpStatusCode": 400
}
Number of attachments exceeded 200 The maximum number of attachments for a delivery is 8. {
"systemMessage": "Maximum number of attachments for a
delivery is 100.",
"httpStatusCode": 400
}

5.4.2. Retrieve the metadata of an attachment

5.4.2.1. Request

HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/attachments/{attachmentId}

5.4.2.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.4.2.2. Response

HTTP Status Code: 200 OK
The object retrieved is the same as described in Add attachment APINot Accessible chapter.

5.4.2.2.1. Errors

Error HTTP Status Code Description Body
Unauthorized 401 The token used is either invalid or expired. -
Attachment not found 404 The specified attachment identifier was not found. -

5.4.3. Update metadata of the attachment

Update the metadata of an attachment.

5.4.3.1. Request

HTTP Method: PUT

URL:https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/attachments/{attachmentId}

5.4.3.1.1. Headers

Key Value
Content-Type application/json
Authorization Bearer eyJlbm...zh9jQ
5.4.3.1.2. Body
The body is the same as described in Add attachment APINot Accessible chapter.
5.4.3.2. Response

HTTP Status Code: 200 OK

5.4.3.2.1. Errors

Error HTTP Status Code Description Body
Unauthorized 401 The token used is either invalid or expired. -
Delivery not found 404 The specified delivery identifier was not found. -
Attachment not found 404 The specified attachment identifier was not found. -

5.4.4. Add or replace the binary of an attachment

Add or replace the binary of an attachment. Only PDF files are currently supported.
Remark: the binary of an attachment is required.
5.4.4.1. Request

HTTP Method: PUT
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/attachments/{attachmentId}/attachment.{fileExtension}

5.4.4.1.1. Headers

Key Value
Content-Type multipart/form-data OR application/json
Authorization Bearer eyJlbm...zh9jQ

5.4.4.1.2 Body

Use the multipart/form-data encoding algorithm to add or replace the binary data.
Use the application/json to add or replace the binary data using Base64 encoding algoritm.

Property Name Type Mandatory Constraints Description
file string Y Base64 string The Base64 encoded document.
{
"file": "SGVsbG8gd29.........yZCE="
}
5.4.4.2. Response

HTTP Status Code: 200 OK

5.4.4.2.1. Errors
Error HTTP Status Code Description Body
Unauthorized,
Forbidden
401, 403
The token used is either invalid or expired. -
Delivery not found 404 The specified delivery identifier was not found. -
Attachment not
found
404 The specified attachment identifier was not found. -
Multipart form 200 If the content is not a MIME multipart content ("multipart/" content-type with properly set boundary). {
"systemMessage": "The request content is not a MIME
multipart content.",
"httpStatusCode": 400
}
Invalid type extension 200
This error is returned if the file extension (provided in the URL) is not in the list of accepted file types (only PDF to this day).
{
"systemMessage": "The specified file type (docx) is
currently not supported. Supported types are: pdf.",
"httpStatusCode": 400
Extension and content mismatch 200 The uploaded file is checked to match the type declared by the extension. In case of a mismatch, this error is returned. {
"systemMessage": "The specified file type (pdf)
doesn't match with the uploaded file content.",
"httpStatusCode": 400
File size 200 The limit on the webserver is 100MB (maxRequestLength and
maxAllowedContentLength).
If this size is exceeded, a 400 error code is raised.
The API has an additional limit of 20 MB.
{
"systemMessage": "The uploaded file exceeds the
maximum allowed size of 20 MB.",
"httpStatusCode": 400
}
Corrupted PDF 200
This error will be the result if the provided pdf is considered to
be corrupt.
{
"systemMessage": "Unable to open the file. Ensure it
is not corrupted or password protected.",
"httpStatusCode": 400
}
Password protected pdf 200 The pdf files are tested for password protection. Protected files can't be used.
{
"systemMessage": "Unable to open the file. Ensure it
is not corrupted or password protected.",
"httpStatusCode": 400
}
Invalid json object 200
This error is returned if the Json object does not contain the 'file' property.
{
"systemMessage": "Invalid json object. Property
'file' not found.",
"httpStatusCode": 400
}
Basic validation 200 This error is returned if the Json object does not contain the Base64 string as a value of 'file' property.
{
"systemMessage": "The Base64 string cannot be null.",
"httpStatusCode": 400
}
Json Deserialization 200
This error is returned if the Json object is invalid.
{
"systemMessage": "Cannot deserialize json object.",
"httpStatusCode": 400
}
Base64 decode 200
This error is returned if the Base64 string is invalid.
{
"systemMessage": "Cannot convert Base64 to document."
,
"httpStatusCode": 400
}

5.4.5. Remove attachment

This request removes an attachment (metadata and binary) from the delivery.

5.4.5.1. Request

HTTP Method: DELETE
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/{deliveryId}/attachments/{attachmentId}

5.4.5.1.1. Headers

Key Value
Content-Type
application/json
Authorization
Bearer eyJlbm...zh9jQ
5.4.5.2. Response

HTTP Status Code: 200 OK

5.4.5.2.1. Errors

Error HTTP Status Code Description Body
Unauthorized, Forbidden
401, 403
The token used is either invalid or expired.
-

One or more associated documents
200
This error is returned if there are some documents associated to the attachment. Document
{
"systemMessage": "The attachment 'Id' cannot be removed
because there are Count associated documents.
Please delete first the documents.",
"httpStatusCode": 400
}

5.5. Documents

5.5.1. Add a document

This request adds a document to a delivery. Please note that the document is defined with all its metadata, but not the binary itself.
5.5.1.1. Request

HTTP Method: POST
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/{deliveryid}/documents

5.5.1.1.1. Headers

Key Value
Content-Type application/json
Authorization Bearer eyJlbm...zh9jQ

5.5.1.1.2. Body

Property Name Type Mandatory Constraints Description
title string Y
Max Length 65 The title / subject to be displayed to the user.
correlationId string N Max Length 40 Correlation id that allows tracing in logs.
documentType int Y
- Invoice = 1, Offer = 2, Proposal = 3, Information = 4, EPaper = 5, Contract = 6
tag string N
Max Length 255 A tag to be applied to this document (e.g. urgent, important, etc.).
receiverUniqueKeys object list
Y
- A set of unique keys that identify the receiver.
Multiple receivers are not allowed, a document is for a single receiver.
Only 1 unique key can be specified for each document
Remarks:
For further implementation, this property is an object list.
receiverUniqueKeys[ 0 ] name string Y Max Length 300 Name of the unique key.
receiverUniqueKeys[ 0 ] value string Y Max Length 300 Value of the unique key.
containsInvoiceData boolean
N
- Flag to reflect if a document contains invoices. If the flag is not set the flag will be resolved depending on the list of invoices.
invoices object list
N
- The invoices attached.
invoices[ i ] title string N
Max Length 100
Title of the invoice.
invoices[ i ] paymentType int Y
1 or 2 or 3 or 4
Payment type (ES1 = 1, ES2 = 2, ESR = 3, BESR = 4).
invoices[ i ] executionDate string N
AAAA-MM-DDThh:mm:ss.zzzZ
Desired execution date (max: today + 720 days).
invoices[ i ] currency int Y
1 or 2
Currency (CHF = 1, EUR = 2).
invoices[ i ] amount decimal
N
- Due amount.
invoices[ i ] beneficiary object Y
- Beneficiary account.
invoices[ i ] beneficiary accountNumber string Y
Max Length 35
Account number (either postal account number or IBAN).
invoices[ i ] beneficiary address object
Y
- Domicil address of the account owner.
invoices[ i ] beneficiary address name string N
Max Length 70
Name.
invoices[ i ] beneficiary address additionalInfo string N
Max Length 32 Additional address line.
invoices[ i ] beneficiary address street string N
Max Length 70
Street name.
invoices[ i ] beneficiary address houseNr
string N
Max Length 16
House number.
invoices[ i ] beneficiary address zip
string
N
Max Length 10
ZIP code.
invoices[ i ] beneficiary address city
string
N
Max Length 35
City name.
invoices[ i ] slipPageNumber int
Y - Page number (in the related document) where this payment slip is located.
invoices[ i ] communication
string
N
Available if payment type is ES1 or ES2.Max Length 80
Communication to the beneficiary. ES1 and ES2 only.
invoices[ i ] beneficiaryAgent
object
N
Required if payment type is ES2
Beneficiary agent account (bank of the beneficiary).
invoices[ i ] beneficiaryAgent accountNumber
string
Y
Max Length 35
Account number.
invoices[ i ] beneficiaryAgent clearingNumber
string
N
Max Length 10
Clearing number.
invoices[ i ] beneficiaryAgent address
object Y
- Domicil address.
invoices[ i ] beneficiaryAgent address name
string
N Max Length 70
Name.
invoices[ i ] beneficiaryAgent address additionalInfo string
N
Max Length 32 Additional address line.
invoices[ i ] beneficiaryAgent address street
string N
Max Length 70
Street name.
invoices[ i ] beneficiaryAgent address houseNr

string
N
Max Length 16
House number.
invoices[ i ] beneficiaryAgent address zip
string
N
Max Length 10
ZIP code.
invoices[ i ] beneficiaryAgent address city
string
N
Max Length 35
City name.
invoices[ i ] referenceNr
string
N
Available if payment type is ESR or BESR. Max Length 36
Reference number.
invoices[ i ] finalBeneficiaryAddress address
object
N
Required if payment type is BERS
Final beneficiary address.
invoices[ i ] finalBeneficiaryAddress address name
string
N
Max Length 70
Name.
invoices[ i ] finalBeneficiaryAddress address additionalInfo
string
N
Max Length 32
Additional address line.
invoices[ i ] finalBeneficiaryAddress address street
string
N
Max Length 70
Street name.
invoices[ i ] finalBeneficiaryAddress address houseNr string
N
Max Length 16
House number.
invoices[ i ] finalBeneficiaryAddress address zip
string
N
Max Length 10
ZIP code.
invoices[ i ] finalBeneficiaryAddress address city
string N
Max Length 35
City name.
attachmentIds
number list
N
-
The identifiers of linked attachments. Are allowed a maximum of 8 attachments for document.

Body sample

{
"title": "string",
"correlationId": "string",
"documentType": 1,
"tag": "string",
"receiverUniqueKeys": [
{
"name": "string",
"value": "string"
}
],
"containsInvoiceData": true,
"invoices": [
{
"paymentType": 0,
"executionDate": "2017-09-01T08:15:27.642Z",
"currency": 0,
"amount": 0,
"beneficiary": {
"accountNumber": "string",
"address": {
"name": "string",
"additionalInfo": "string",
"street": "string",
"houseNr": "string",
"zip": "string",
"city": "string"
}
},
"slipPageNumber": 0,
"communication": "string",
"beneficiaryAgent": {
"accountNumber": "string",
"clearingNumber": "string",
"address": {
"name": "string",
"additionalInfo": "string",
"street": "string",
"houseNr": "string",
"zip": "string",
"city": "string"
}
},
"referenceNr": "string",
"finalBeneficiaryAddress": {
"name": "string",
"additionalInfo": "string",
"street": "string",
"houseNr": "string",
"zip": "string",
"city": "string"
}
}
],
"attachmentIds": [
0
]
}
5.5.1.2. Response

HTTP Status Code: 201 Created
The generated document id is returned in the location header.


Headers

Location: 33

5.5.1.2.1. Errors

Error HTTP Status Code Description Body
Unauthorized
401
The token used is either invalid or expired.
-
Receiver not found 200  If the specified unique key is not found. {
"systemMessage": "No receiver could be found with the
specified unique key 'epofKey=xyz'.",
"httpStatusCode": 400,
"errorCode": 200
}
Basic Validation 200 The document and all the invoices are validated according to the specified business rules. {
"errors": [
{
"parameterName": "title",
"systemMessage": "The Title field is required."
},
{
"parameterName": "invoices[0].beneficiary.
accountNumber",
"systemMessage": "The beneficiary account number is
not valid."
},
{
"parameterName": "invoices[0].amount",
"systemMessage": "The minimum invoice amount is 0.05 C
hf.
}
],
"httpStatusCode": 400
}
Invalid attachment identifiers
200 The specified attachment identifier doesn't exist or doesn't belong to the delivery.
{
"systemMessage": "The given attachment Id doesn't belong to delivery Id.",
"httpStatusCode": 400
}
Invalid attachment identifiers  200
Some attachment id are repeated.
{
"systemMessage": "Some attachment id are repeated.",
"httpStatusCode": 400
}
Number of attachments exceeded
200 The maximum number of attachments for a document 8.
{
"systemMessage": "The maximum number of attachments for a document is 8.",
"httpStatusCode": 400
}
Not unique key
200 The specified unique key has to be associated to a single user.
{
"systemMessage": "The unique key 'XYZ' belongs to multiple users.",
"httpStatusCode": 400,
"errorCode": 210
}

5.5.2. Retrieve the metadata of a document

5.5.2.1. Request

HTTP Method: GET

URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/documents/{documentId}

5.5.2.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ

5.5.2.2. Response

HTTP Status Code: 200 OK
The object retrieved is the same as described in Add document API.Not Accessible

5.5.3. Update metadata of the document

Update a document's metadata.

5.5.3.1. Request

HTTP Method: PUT
URL:https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/documents/{documentId}

5.5.3.1.1. Headers

Key Value
Content-Type application/json
Authorization Bearer eyJlbm...zh9jQ

5.5.3.1.2. Body
The body is the same as described in chapter 6.1 Add a document.Not Accessible

5.5.3.2. Response

HTTP Status Code: 200 OK

5.5.4. Add or replace the binary of a document

Add or replace the binary of a document. Only PDF files are currently supported.
Remark: the binary of a document is required.

5.5.4.1. Request

HTTP Method: PUT
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not AccessibledeliveryId}/documents/{documentId}/document.{fileExtension}

5.5.4.1.1. Headers

Key Value
Content-Type multipart/form-data OR application/json
Authorization
Bearer eyJlbm...zh9jQ

5.5.4.1.2. Body

Use the multipart/form-data encoding algorithm to add or replace the binary data.
Use the application/json to add or replace the binary data using Base64 encoding algoritm.

Property Name Type Mandatory Constraints Description
file string Y Base64 string The Base64 encoded document
{
"file": "SGVsbG8gd29.........yZCE="
}
5.5.4.2. Response

HTTP Status Code: 200 OK

5.5.4.2.1. Errors

Error HTTP Status Code Description Body
Unauthorized, Forbidden
200 The token used is either invalid or expired.
-
Multipart form
200
If the content is not a MIME multipart content ("multipart/" content-type with properly set boundary).
{
"systemMessage": "The request content is not a MIME
multipart content.",
"httpStatusCode": 400
}
Invalid type extension 200 This error is returned if the file extension (provided in the URL) is not in the list of accepted file types (only PDF to this day).
{
"systemMessage": "The specified file type (docx) is
currently not supported. Supported types are: pdf.",
"httpStatusCode": 400
}
Extension and content mismatch
200 The uploaded file is checked to match the type declared by the extension. In case of a mismatch, this error is returned. {
"systemMessage": "The specified file type (pdf)
doesn't match with the uploaded file content.",
"httpStatusCode": 400
}
File size 200
The limit on the webserver is 100MB (maxRequestLength and maxAllowedContentLength).
If this size is exceeded, a 400 error code is raised.
The API has an additional limit of 20 MB.
{
"systemMessage": "The uploaded file exceeds the
maximum allowed size of 20 MB.",
"httpStatusCode": 400
}
Corrupted PDF
200 This error will be the result if the provided pdf is considered to be corrupt.
{
"systemMessage": "Unable to open the file. Ensure it
is not corrupted or password protected.",
"httpStatusCode": 400
}
Password protected pdf
200 The pdf files are tested for password protection. Protected files can't be used.
{
"systemMessage": "Unable to open the file. Ensure it
is not corrupted or password protected.",
"httpStatusCode": 400
}
Invalid json object
200
This error is returned if the Json object does not contain the 'file' property.
{
"systemMessage": "Invalid json object. Property
'file' not found.",
"httpStatusCode": 400
}
Basic validation
200
This error is returned if the Json object does not contain the Base64 string as a value of 'file' property.
{
"systemMessage": "The Base64 string cannot be null.",
"httpStatusCode": 400
}
Json Deserialization 200 This error is returned if the Json object is invalid.
{
"systemMessage": "Cannot deserialize json object.",
"httpStatusCode": 400
}
Base64 decode 200 This error is returned if the Base64 string is invalid.
{
"systemMessage": "Cannot convert Base64 to document."
,
"httpStatusCode": 400
}

5.5.5. Remove document

This request removes a document (metadata and binary) from the delivery.
5.5.5.1. Request

HTTP Method: DELETE
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/Not Accessible{deliveryId}/documents/{documentId}

5.5.5.1.1. Headers

Key Value
Content-Type
application/json
Authorization
Bearer eyJlbm...zh9jQ
5.5.5.2. Response

HTTP Status Code: 200 OK

5.6. UniqueKeys

5.6.1. Check unique key

Use this API to check a list of unique keys for their validity.

5.6.1.1. Request

HTTP Method: POST
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/senders/Not Accessible{senderId}/uniquekeys/check

5.6.1.1.1. Headers

Key
Value
Content-Type
application/json
Authorization
Bearer eyJlbm...zh9jQ
5.6.1.1.2. Query
Property Name Type Mandatory Constraints Description
mode
int  N 0 = Return only valid UniqueKeys 
1 = Return only invalid UniqueKeys 
2 = Return all the submitted unique keys  
Default value= 0.
Specifies which keys should be returned depending on their validity.

5.6.1.1.3. Body

Property Name Type Mandatory Constraints Description
uniqueKeys
object list
Y
Max elements 2500
The unique keys to check.
uniqueKeys[ i ] name
string
Y
Max Length 300
The unique key name.
uniqueKeys[ i ] value
string
Y
Max Length 300
The unique key value.

Body sample

[
{
"name": "string",
"value": "string"
}
]
5.6.1.2. Response

HTTP Status Code: 200 OK

Property Name Type Constraints Description
validKeysCount
int - Amount of valid keys provided.
InvalidKeysCount int  - Amount of invalid keys provided.
validKeys
object list - Valid keys (returned if mode = 1 or mode = 2).
validKeys[ i ] name
string Max Length 300 Unique key name.
validKeys[ i ] value
string Max Length 300
Unique key value.
invalidKeys
object list - Invalid keys (returned if mode = 1 or mode = 2).
InvalidKeys[ i ] name
string Max Length 300
Unique key name.
InvalidKeys[ i ] value
string Max Length 300
Unique key value.

Body sample

{
"validKeysCount": 0,
"invalidKeysCount": 1,
"validKeys": [],
"invalidKeys": [
{
"name": "string",
"value": "string"
}
]
}

5.6.2. List unique keys

This API returns a paged list of unique keys.

5.6.2.1. Request

HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/senders/Not AccessibleNot Accessible{senderId}/uniquekeys

5.6.2.1.1. Headers

Key Value
Content-Type application/json
Authorization
Bearer eyJlbm...zh9jQ

5.6.2.1.2. Query

Parameter Name Type Mandatory Constraints Description
skip int N Default = 0
Amount of records to be skipped.
take int N Default = 1000, Max = 2500

Amount of records to returned.

5.6.2.2. Response

HTTP Status Code: 200 OK

Parameter Name Type Constraints Description
total int - Total amount of records.
Note: Doesn't directly represent the amount of activated receivers for a given sender.
At least one key (epofKey) will always exist, but then the sender may define as many keys as they want (0-n). The amount of keys
can furthermore be different from receiver to receiver.
count int - Amount of records returned.
data object list - Unique Key List.
data[ i ] name string Max Length 300. Unique key name.
data[ i ] value
string Max Length 300. Unique key value.

Body sample

{
"total": 0,
"data": [
{
"name": "string",
"value": "string"
}
],
"count": 0
}

5.7. Delivery, Document and Attachment Status

Use this API to check the status of a document, attachment or a delivery.

This APIs are currently not available under the /int_stable/ endpoint.

5.7.1. Document Status

Use this API to check the status of a document

5.7.1.1. Document Statuses

The following are the possible values for the documentStatus

Value Status
0 Created
1 Imported
2 Delivered
3 Error
4 Updated
5 Deleted
6 Rejected
5.7.1.2. Document Status via DocumentId

5.7.1.2.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/documents/{transferDocumentId}/status

5.7.1.2.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.7.1.2.2. Response
HTTP Status Code: 200 OK

Body sample

{
"documentStatus": 0,
"documentStatusDateTime": "2019-01-08T21:15:16.769"
}

5.7.1.2.3. Errors

Error HTTP Status Code Description
Unauthorized,Forbidden 401, 403
The token used is either invalid or expired.
Document not found
404
Document not found.
Invalid Sender Id 200 {
"systemMessage": "Invalid spsSender id.",
"httpStatusCode": 400
}
5.7.1.3. Document Status via CorrelationId's


5.7.1.3.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/documentStatus/?documentCorrelationId={documentCorrelationId}
&deliveryCorrelationId={deliveryCorrelationId}

5.7.1.3.2. Query

Parameter Name Type Mandatory Constraints Description
DocumentCorrelationId string Y - The document correlation id.
DeliveryCorrelationId string N - The delivery correlation id.

5.7.1.3.2.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.7.1.3.3. Response
HTTP Status Code: 200 OK

Body sample

{
"documentStatus": 0,
"documentStatusDateTime": "2019-01-08T21:15:16.769"
}

5.7.1.3.4. Errors

Error HTTP Status Code Description
Unauthorized,Forbidden
401, 403
The token used is either invalid or expired.
Document not found
404
Document not found.
Invalid Sender Id
200 {
"systemMessage": "Invalid spsSender id.",
"httpStatusCode": 400
}
5.7.1.4. Document Status History via DocumentId

Use this API to retrieve the status history of a document via DocumentId

5.7.1.4.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/documents/{transferDocumentId}/statusHistory?startDateTime={startDateTime}Not Accessible

5.7.1.4.2. Query

Parameter Name Type Mandatory Constraints Description
startDateTime
string
N
2019-01-08T15:01:51.328 ISO 8601 Date Time format.
Filter the document status history starting from this date and time.

5.7.1.4.2.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ

5.7.1.4.3. Response
HTTP Status Code: 200 OK

Parameter Name Type Constraints Description
status int Document status
Document status value.
dateTime string ISO 8601 Date Time format.
The date and time when the status was set.

Body sample

Body sample
[
{
"status": 0,
"dateTime": "2019-01-08T15:01:51.327"
},
{
"status": 2,
"dateTime": "2019-01-08T21:15:16.769"
}
]

5.7.1.4.4. Errors

Error HTTP Status Code Description
Unauthorized, Forbidden
401, 403
The token used is either invalid or expired.
Document not found
404
Document not found.
Invalid Sender Id 200
{
"systemMessage": "Invalid spsSender id.",
"httpStatusCode": 400
}
Invalid startDateTime format
200
{
"parameterName": "startDateTime",
"systemMessage": "The value '2018-12-' is not valid for StartDateTime."
}

5.7.1.5. Document Status History via CorrelationId's

5.7.1.5.1. Request

HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/documentStatusHistory/?documentCorrelationId={documentCorrelationId}
&deliveryCorrelationId={deliveryCorrelationId}&startDateTime={startDateTime}Not AccessibleNot Accessible

5.7.1.5.2. Query

Parameter Name Type Mandatory Constraints Description
DocumentCorrelationId
string
Y
- The document correlation id.
DeliveryCorrelationId
string N - The delivery correlation id.
startData Time string N 2019-01-08T15:01:51.328 ISO 8601 Date Time format.
Filter the document status history starting from this date and time.

5.7.1.5.2.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ

5.7.1.5.3. Response
HTTP Status Code: 200 OK

Parameter Name Type Constraints Description
status int Document status Document status value.
dateTime string ISO 8601 Date Time format.
The date and time when the status was set.

Body sample

[
{
"status": 0,
"dateTime": "2019-01-08T15:01:51.327"
},
{
"status": 2,
"dateTime": "2019-01-08T21:15:16.769"
}
]

5.7.1.5.4. Errors

Error HTTP Status Code Description
Unauthorized,Forbidden
401, 403
The token used is either invalid or expired.
Document not found
404
Document not found.
Invalid Sender Id
200
{
"systemMessage": "Invalid spsSender id.",
"httpStatusCode": 400
}
Invalid startDateTime format
200
{
"parameterName": "startDateTime",
"systemMessage": "The value '2018-12-' is not valid for StartDateTime."
}

5.7.2. Attachment Status

Use this API to check the status of an attachment

5.7.2.1. Attachment Statuses

the following are the possible values for the attachmentStatus

Value Status
0 Created
1 Imported
2 Delivered
3 Error
4 Updated
5 Deleted
6 Rejected
5.7.2.2. Attachment Status via AttachmentId

5.7.2.2.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/attachments/{transferAttachmentId}/status

5.7.2.2.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.7.2.2.2. Response
HTTP Status Code: 200 OK

Body sample

{
"attachmentStatus": 0
}
5.7.2.3. Attachment Status via CorrelationId

5.7.2.3.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/attachmentStatus/?attachmentCorrelationId={attachmentCorrelationId}&deliveryCorrelationId={deliveryCorrelationId}Not Accessible

AttachmentCorrelationId is mandatory

DeliveryCorrelationId is optional

5.7.2.3.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.7.2.3.2. Response
HTTP Status Code: 200 OK

Body sample

{
"attachmentStatus": 0
}

5.7.3. Delivery Status

Use this API to check the status of a delivery

5.7.3.1. Delivery Statuses

the following are the possible values for the deliveryStatus

Value Status Description
0 Created The delivery has been created. Documents and/or attachments can be added to the delivery.
1 Processing The delivery is beeing processed. No more documents and/or attachments can be added to the delivery at this time.
2 Imported The processing has completed, some or all documents are not yet visible to the users (delayed delivery, see deliveryDate parameter not yet implemented, so this status is not used at the moment).
3 ImportedWithErrors Same as above but some documents couldn't be imported.
4 Delivered The processing has completed and all the documents are now visible to the users.
5 DeliveredWithErrors Same as above but some documents couldn't be delivered.

6

Expired

The delivery has expired. This happens when the processing of a delivery was not started 48 hours after its creation.


5.7.3.2. Delivery Status via DeliveryId

5.7.3.2.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/deliveries/{transferDeliveryId}/status

5.7.3.2.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.7.3.2.2. Response
HTTP Status Code: 200 OK

Body sample

{
"status": 5,
"documents":
{
"imported": 39983,
"pending": 9,
"notImported": [
{
"documentId": 67519,
"correlationId": "156CF7A0-2563-4A24-A644-
E7D27853D3B2",
"errorMessage": "WLF",
"errorCode": 10
},
{
"documentId": 67520,
"correlationId": "88F1E817-29DC-490D-9FB5-
8CFF09CFC390",
"errorMessage": "TODO",
"errorCode": 20
}
]
}
"attachments":
{
"imported": 3,
"pending": 0,
"notImported": [
{
"attachmentId": 110,
"correlationId": "XbLF5onzDI",
"errorMessage": "WLF",
"errorCode": 10
},
{
"attachmentId": 134,
"correlationId": "vY6DQsXEub",
"errorMessage": "TODO",
"errorCode": 20
}
]
}
}
Key Type Description
status int
the delivery status value
documents
object
Summary of the document import status
documents.imported int Number of imported documents (Sum imported and delivered) 
documents.pending
int Number of documents still to be imported
documents.notImported
object list
Lists the details of errors for every document that could not be imported.
documents.notImported[i].documentId
int The document's identifier.
documents.notImported[i].correlationId
string
The document's Tracking id
documents.notImported[i].errorCode
int
The import error code (TODO: list of error codes)
documents.notImported[i].errorMessage
string
The import error full description
attachment
object
Summary of the attachment import status
attachment.imported
int Number of imported attachments (Sum imported and delivered)
attachment pending
int Number of attachments still to be imported
attachment.notImported
object list
Lists the details of errors for every attachment that could not be imported.
attachment.notImported[i].attachmentId
int Lists the details of errors for every attachment that could not be imported.
documents.notImported[i].correlationId
string
The attachent's Tracking id
attachment.notImported[i].errorCode
int The import error code (TODO: list of error codes)
attachment.notImported[i].errorMessage
string The import error full description
5.7.3.3. Delivery Status via CorrelationId's

5.7.3.3.1. Request

HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/orders/v1/senders/{spsSenderId}/deliveryStatus/?deliveryCorrelationId={deliveryCorrelationId}
DeliveryCorrelationId is mandatory

5.7.3.3.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ

5.7.3.3.2. Response

same as above, see here

5.8. API StatusCheck

5.8.1. Ping

Check the status of a delivery API.

5.8.1.1. Request

HTTP Method: GETURL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/statuscheck/ping

5.8.1.1.1. Headers

Key Value
Authorization Bearer eyJlbm...zh9jQ
5.8.1.2. Response
HTTP Status Code: 200 OK

Body sample

"pong"

5.9. Error Codes

As mentioned in chapter "Error Response", in case of errors a Status Code 200 with a JSON is returned. The JSON contains specific errorCodes allowing a client application to react differently. The following Table contains possible error codes and description regarding the deliveries.

Code Label Description
110 DeliveryExpired
The delivery has expired, therefore the process cannot be completed.
120 DeliveryReadOnly
The delivery can't be modified anymore.
200 ReceiverNotFound No user could be found with the specified unique key.
210 DuplicatedUniqueKey
The specified key is not unique, it has to be associated to a single user.
400 Validation
One or more validation errors occured. The errorMessage property will provide futher details (Not returned when the status code is 400.)
410 MissingBinary
No binary file was provided and therefore the document couldn't be imported.

5.10. Samples

5.10.1. Sample Delivery

This chapter describes the steps necessary to deliver a batch of documents.

5.10.1.1. Authentication

First step is to authenticate against the API platform, retrieving the access token to be used in all subsequent requests.

5.10.1.1.1. Request

HTTP Method: POST
URL: https://epost.apiint.post.ch/OAuth/tokenNot Accessible

Body

client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy&grant_type=client_credentials&scope=EP
OFTRANSFERCLIENT

5.10.1.1.2. Response
HTTP Status Code: 200 OK

Body

{
"access_token": "eyJlbm...zh9jQ",
"token_type": "Bearer",
"expires_in": 120
}

5.10.1.1.3. Remarks
"expires_in" : 120 (seconds). This eans that the system asks for a re-authentication every 2 minutes. It is best practise to store the expiration on the client and
check it, before trying a request. Furthermore we recommend a retry mechanism in case of 401 (Unauthorized) or 403 (Forbidden) responses, to get a new
access token before sending the same request again.

5.10.1.2. Start Delivery

Next step is to create a new delivery order.
5.10.1.2.1. Request
HTTP Method: POST
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries

Headers

Accept: application/json
Authorization: Bearer eyJlbm...zh9jQ

Body

{
"title": "(TC) Invoice 73",
"documentType": 1,
"tag": null,
"receiverUniqueKeys": [
{
"name": "PersonalNumber",
"value": "4052322"
}
],
"invoices": [
{
"paymentType": 1,
"currency": 0,
"amount": 79.8,
"beneficiary": {
"accountNumber": "65-92282-1",
"address": {
"name": "Hans Mustermann",
"street": "Viale Stazione",
"houseNr": "832",
"zip": "6500",
"city": "Bellinzona"
}
},
"slipPageNumber": 1,
}
]
}

5.10.1.3.2. Response
HTTP Status Code: 201 Created

Headers

Location: 33

5.10.1.3.3. Remarks
The generated document id is returned in the location header.This request must be performed for each document to be delivered.

5.10.1.4. Submit Document Binary

Once a document's metadata is validated and a document id is returned, the binary content can be added.

5.10.1.4.1. Request
HTTP Method: PUT
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/13/documents/33/document.pdf

Headers

Accept: application/json
Authorization: Bearer eyJlbm...zh9jQ

Body

multipart/form-data

5.10.1.4.2. Response
HTTP Status Code: 204 NoContent

5.10.1.4.3. Remarks
This request must be performed for each document to be delivered.

5.10.1.5. Complete Delivery

This request has to be made after all documents have been submitted. This will notify E-Post Office to start importing the delivery's documents.

5.10.1.5.1. Request
HTTP Method: POST
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/13/completeNot Accessible

Headers

Accept: application/json
Authorization: Bearer eyJlbm...zh9jQ

5.10.1.5.2. Response
HTTP Status Code: 200 OK

Body

{
"documents": {
"metaData": 5,
"binaries": 5
}
}
5.10.1.6. Check Status (optional)

At any time, the status of the delivery can be checked.

5.10.1.6.1. Request
HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer_stable/delivery/v1/deliveries/13/statusNot Accessible

Headers

Accept: application/json
Authorization: Bearer eyJlbm...pFfQw
5.10.1.6.2. Response
HTTP Status Code: 200 OK

Body

{
"status": 1,
"documents": {
"delivered": 0,
"pending": 5,
"notDelivered": []
}
}

5.10.1.6.3. Remarks
Completed deliveries will be archived in a maintenance task. An archived delivery's state can't be checked via API.

5.10.2. Invoices Metadata Examples

Below you will find some examples of documents containing invoice information and their translation into our JSON model.

5.10.2.1. Red payment slip - ES1
Language Type
DE ES
FR BV
IT PV

Body

{
"title": "ES1 Template - Robert Schneider SA - Rechnung Nr. 408",
"documentType": 2,
"tag": "Template",
"receiverUniqueKeys": [{
"value": "81893",
"name": "QS-ID"
}],
"containsInvoiceData": true,
"invoices": [{
"paymentType": 1,
"executionDate": "2018-12-21T18:00:00Z",
"currency": 1,
"amount": 8479.25,
"communication": "Rechnung Nr. 408",
"beneficiary": {
"accountNumber": "25-9034-2",
"address": {
"name": "Robert Schneider SA",
"additionalInfo": "Grands magasins",
"street": "Case postale",
"houseNr": "",
"zip": "2501",
"city": "Biel/Bienne"
}
}
}]
}
5.10.2.2. Red payment slip (bank) - ES2
Language Type
DE ES bank
FR BV banque
IT PV banca

Body

{
"title": "ES2 Template - Muster AG - Rechnung 7496",
"documentType": 2,
"tag": "Rechnung",
"receiverUniqueKeys": [{
"value": "92012",
"name": "QS-ID"
}],
"containsInvoiceData": true,
"invoices": [{
"paymentType": 2,
"executionDate": "2018-12-21T18:00:00.326Z",
"currency": 1,
"amount": 8479.25,
"beneficiary": {
"accountNumber": "CH3808888123456789012",
"address": {
"name": "MUSTER AG",
"additionalInfo": "",
"street": "BAHNHOFSTRASSE",
"houseNr": "5",
"zip": "8001",
"city": "ZUERICH"
}
},
"communication": "Rechnung\nNr.7496",
"beneficiaryAgent": {
"accountNumber": "80-2-2",
"address": {
"name": "SELDWYLA BANK",
"additionalInfo": "",
"street": "",
"houseNr": "",
"zip": "8021",
"city": "ZUERICH"
}
}
}]
}
5.10.2.3. Orange payment slip - ESR
Language Type
DE ESR
FR BVR
IT PVR

Body

{
"title": "ESR3 Template - Robert Schneider SA",
"documentType": 2,
"tag": "Template",
"receiverUniqueKeys": [{
"value": "81893",
"name": "QS-ID"
}],
"containsInvoiceData": true,
"invoices": [{
"paymentType": 3,
"executionDate": "2018-12-21T18:00:00.326Z",
"currency": 1,
"amount": 3949.75,
"beneficiary": {
"accountNumber": "01-39139-1",
"address": {
"name": "Robert Schneider SA",
"additionalInfo": "Grands magasins",
"street": "Case postale",
"houseNr": "",
"zip": "2501",
"city": "Biel/Bienne"
}
},
"referenceNr": "210000000003139471430009017",
"slipPageNumber": 1
}]
}
5.10.2.4. Orange bank payment slip (bank) - BESR
Language Type
DE ESR Bank
FR BVR Banque
IT PVR Banca

Body

{
"title": "BESR4 Template - H. Muster AG",
"documentType": 2,
"tag": "Template",
"receiverUniqueKeys": [{
"value": "81893",
"name": "QS-ID"
}],
"containsInvoiceData": true,
"invoices": [{
"paymentType": 4,
"executionDate": "2018-12-21T18:00:00.326Z",
"currency": 1,
"amount": 2830.5,
"beneficiary": {
"accountNumber": "01-145-6",
"address": {
"name": "Seldwyla Bank",
"additionalInfo": "",
"street": "",
"houseNr": "",
"zip": "8001",
"city": "Zürich"
}
},
"slipPageNumber": 0,
"referenceNr": "215703000075200334559000126",
"finalBeneficiaryAddress": {
"name": "H. Muster AG",
"additionalInfo": "Versandhaus",
"street": "Industriestrasse",
"houseNr": "88",
"zip": "8000",
"city": "Zürich"
}
}]
}

5.11. Special characters

In all string fields the following characters are accepted:

  • All uppercase and lowercase letters, with accents, umlauts etc.
  • Digits
  • White space
  • The following special characters: - _ / \ ( ) [ ] { } . , : ; ' + & @ ! ? * $ = % #
  • Line break: \r \n

All other characters are forbidden and will result in a bad request error (400).

This is the regular expression being applied:

^[a-zÀ-ÿ0-9 \-_\/\\()\[\]{}.,:;'+&@!?*$=%#\r\n]*$

6. Registration

6.1. Introduction

The purpose of this section is to give an overview of the Registration APIs and to describe the technical details of each API request. It also explains how the
registration process works and how to implement it on the sender's side depending of the choosen flow.

6.2. General Information

6.2.1. Registration priorities

In all cases, it's possible that a user registers multiple times. Note that by multiple registrations, it's meant either that the same user tries to register again or
another user with the same security answers.

We do not unregister an already registered user if the wrong answers were provided. If a registered user tries to register again without success, the existing
registration is retained.
In case of success, the new registration always replaces the existing one. This means that all existing UniqueKeys are replaced by the new ones. The replaced
UniqueKeys cannot be used anymore to deliver documents.

6.3. Synchronous

6.3.1. Overview

The following diagram depicts the process for the synchronous registration.

# Steps description
1 The E-Post Office calls the sender's API
2 The sender responds with a message telling E-Post Office about the status of the registration

E-Post Office sends the questions and answers to the sender for verification. The sender responds with a status code so that E-Post Office knows if the
verification was successful or not.

6.3.2. Authentication

The sender has to provide the following information

Name Type Mandatory Constraints Description
Url of the service
string
Y
Max length 500
The url where the service is hosted
Username
string N Max length 250 The username to use to access the service
Password string N Max lenght 250 The password to use to access the service

When the username and password are configured, E-Post Office will use basic authentication when calling the service. It means that it will automatically add an
Authorization header with the value "Basic <encoded-credentials>" in the request.

The service MUST follow the points listed below:

  • The url must be protected with HTTPS and use the standard port, 443.
  • The DNS address must be in the Internet
  • The SSL Certificate must be issued from a trusted Certificate Authority

6.3.3. Verifies the security answers

E-Post Office calls this method to verify the security answers. The sender gives the status of the verification back.
Note that you have maximum 10 seconds to answer, after that a timeout will be generated and the verification will be canceled with the status SenderError.  
6.3.3.1. Request

HTTP Method: PUT
URL: <senderUrl>/registrations/{correlationId}

6.3.3.1.1. Header

Key Value Remark
Authorization Basic XYZ XYZ is the base64 encoded result of "username:password"

6.3.3.1.2. Query

Variable Name Type Constraints Descriptions
correlationId
string
Max length 40
A unique identifier for the registration

6.3.3.1.3. Body

Property Name Type Description
senderId
string The id of the sender
data object list List of questions and answers
data[ i ] key string The key of the question
data[ i ] value string The answer to the question
epofKey object The unique key generated by E-Post Office
epofKey name
string The name of the key
epofKey value string The value of the key

Body sample

{
"senderId": "1234567",
"data": [
{
"key": "customerNumber",
"value": "1245.ABC-X"
},
{
"key": "customerPolicy",
"value": "123-456-789"
},
{
"key": "birthdate",
"value": "1960-12-20"
}
],
"epofKey": {
"name" : "epofKey",
"value": "0722e232-9cd7-4200-844d-1d6a6585c6fb"
}
}
6.3.3.2. Response

HTTP Status Code: 200 OK

6.3.3.2.1. Body

Property Name Type Mandatory Constraints Description
error string N - A description of the error in case of failure
receiverKeys
object list N - List of unique keys returned by the sender
receiverKeys[ i ] name
string Y Max length 300
The name of the key
receiverKeys[ i ] value
string Y Max length 300
The value of the key
status
int Y - The state of the registration. See table below for details

Status description

Value Name Description
0 Error The questions and answers do not match
1 Success The questions and answers match

Body sample

{
"error": "",
"receiverKeys": [
{
"name": "key1",
"value": "abcd"
},
{
"name": "key2",
"value": "defg"
}
],
"status": 1
}

6.4. Asynchronous

6.4.1. Overview

The following diagram depicts the process for the asynchronous registration.

# Steps description
1 The sender calls the E-Post Office API and asks for pending registrations
2 The E-Post Office API returns a list of pending registrations, including the encrypted answers
3 The sender decrypts the answers and validates them
4 The sender sends the validation result for each registration
5 HTTP status code

Each time a user registers with the asynchronous flow, a pending registration is created and stored in E-Post Office. The sender has to call the pending registration api method to get the current list of pending registration like shown in step 1 of the schema. After that, for each registration, the sender has to indicate the result of the verification to E-Post Office (successful or failed) by using the method described in step 4. Note that the sender has the possibility to provide its own UniqueKeys if the one provided by E-Post Office is not suitable or if more than one key is required.

Since the pending registrations are stored in the E-Post Office, the answers are encrypted with a public certificate provided by the sender. When the sender calls the api to get the pending registration, the encrypted answers are returned as well as the thumbprint of the public certificate used for the encryption, which may help the sender to manage multiple versions of the certificate. E-Post Office always uses the certificate that was configured at the time the user answers the security questions (not at the time the sender retrieves the pending registrations). So if the certificate changes between the two, the old one will be used for the encryption.

The standard used for the public key certificate is X.509. The minimal recommaeded key size is 2048, the maximal supported size is 16384.
This is the process used to encrypt the answers:

  1. The answers are encoded with UTF-8
  2. They are encrypted with the sender's public certificate (RSA algorithm is used)
  3. They are converted to a base64 string

The result will be sent when calling the pending registration api. To decrypt (step 3), you have to do the same operations in the reverse order so:
First, decode the base64 string, then decrypt the result with the associated private key and at the end, decode with UTF-8.

6.4.2. Get pending registrations

Gets a list of all pending registrations that needs to be verified by the sender.

6.4.2.1. Request

HTTP Method: GET
URL: https://epost.apiint.post.ch/transfer/keyexchange/v1/senders/{senderId}/pendingregistrations?from={from}&skip={skip}&take={take}

6.4.2.1.1. Headers

Key Value
Content-Type application/json
Authorization Bearer eyJlbm...zh9jQ

6.4.2.1.2. Query

Parameter Name Type Mandatory Constraints Description
senderId string Y - The id of the sender
from DateTime Y > 01.01.1753 00:00:00
Date to specify from when on the records should be fetched
skip int N Default = 0
Amount of records to be skipped
take int N Default = 1000, Max = 1000
Amount of records to be returned
6.4.2.2. Response

HTTP Status Code: 200 OK

6.4.2.2.1. Body

Property Name Type Description
certificateThumbprint
string The thumbprint associated to the certificate's public key used to encrypt the answers
correlationId Guid The identifier of the registration. This id has to be sent back when responding with the status
data object list List of questions and answers
data[ i ] key
string The key of the question
data[ i ] value
string The answer to the question
epofKey
object The default unique key
epofKey name
string The name of the key
epofKey value
string The value of the key
senderId
string The identifier of the sender
total integer The total number of pending registrations
count integer The number of pending registrations in this page only

Body sample

{
"total": 1,
"data": [
{
"certificateThumbprint": "DEADBEEF3FB2A6C21577380BAD7DC092B0BC6D09",
"correlationId": "26064d4c-818d-4e68-9ff6-e5dc99177fa0",
"data": [
{
"key": "Question1",
"value": "S21Z4QqW7F7EaKg6f55OEM
/kn+D3tJxUYcCIrGlWLip9g48b5cNseSOoFRV1nH02JxAOi1PZhSEgTHQWWTlfwMXsrQGbmTd99KPJiArYaT
UfqEozy..."
},
{
"key": "Question2",
"value": "h8Vy1d1YCbw01IGATr9K1WGTwaFD
/i408yMIHVg6aEsstRXaDHrAIvfijJrCnCsq6h45l1xjkYbSATQced7occ2U5xkBZSXZNcHQWWTlfwMHQWWT
l..."
}
],
"epofKey": {
"name": "aKey",
"value": "aValue"
},
"senderId": "90000001"
}
],
"count": 1
}

6.4.3. Verify answers

Sets the status of the answers and updates the registration.
6.4.3.1. Request

HTTP Method: PUT
URL: https://epost.apiint.post.ch/transfer/keyexchange/v1/senders/{senderId}/pendingregistrations/{correlationId}

6.4.3.1.1. Headers

Key Value
Content-Type
application/json
Authorization
Bearer eyJlbm...zh9jQ

6.4.3.1.2. Query

Parameter Name Type Mandatory Constraints Description
senderId
string
Y - The id of the sender
correlationId
string Y Guid The correlation id received when calling the GET method

6.4.3.1.3. Body

Property Name Type Mandatory Constraints Description
error string N - A description of the error in case of failure
receiverKeys
object list N - A list of unique keys that E-Post Office should use
data[ i ] name
string Y Max length 300
The name of the key
data[ i ] value
string Y - The value of the key
status int Y Max length 300
The state of the registration. See table below for details

Status description

Value Name Description
0 Error The questions and answers do not match
1 Success The questions and answers match

Body sample

{
"error": "",
"receiverKeys": [
{
"name": "key1",
"value": "abcd"
},
{
"name": "key2",
"value": "defg"
}
],
"status": 1
}
6.4.3.2. Response

HTTP Status Code: 200 OK