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)

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

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.

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

 

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

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.

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

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

 

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

 

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

{
"title": "string",
"correlationId": "string"
}

5.4.1.2. Response

HTTP Status Code: 201 Created

The generated attachment id is returned in the location header.

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.

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

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

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.

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

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

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

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

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

[
{
"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

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

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

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

"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

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

5.10.1.1.2. Response
HTTP Status Code: 200 OK

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

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

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

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

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

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

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

5.10.1.5.2. Response
HTTP Status Code: 200 OK

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

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

5.10.1.6.2. Response
HTTP Status Code: 200 OK

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

• Template link: https://www.postfinance.ch/content/dam/pfch/doc/cust/download/441031_templ_de_fr_it.pdfNot Accessible

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

• Template link: https://www.postfinance.ch/content/dam/pfch/doc/cust/download/441032_templ_de_fr_it.pdf

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

• Template link: https://www.postfinance.ch/content/dam/pfch/doc/cust/download/44218_templ_de_fr_it.pdf

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

• Template link: https://www.postfinance.ch/content/dam/pfch/doc/cust/download/44205_templ_de_fr_it.pdf

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

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

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

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

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

6.4.3.2. Response

HTTP Status Code: 200 OK