E-Post API
1. Version History
Version | Date |
---|---|
1.0 | 06.06.2018 |
1.1 | 08.06.2018 |
1.2 | 12.06.2018 |
1.3 | 25.06.2018 |
1.31 | 04.07.2018 |
1.32 | 06.07.2018 |
1.4 | 23.07.2018 |
1.5 | 06.09.2018 |
1.6 | 16.10.2018 |
1.61 | 16.10.2018 |
1.7 | 15.01.2019 |
1.71 | 25.01.2019 |
1.72 | 25.01.2019 |
1.73 | 05.03.2019 |
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
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 "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
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 |
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 |
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 |
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 |
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. Request5.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 |
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 |
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 |
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 OKBody 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
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:
- The answers are encoded with UTF-8
- They are encrypted with the sender's public certificate (RSA algorithm is used)
- 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