E-Post API

User navigation



Language navigation

E-Post API

Close

    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

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

    5.3.2.1.1. Headers

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

    HTTP Status Code: 200 OK

    5.3.2.2.1. Body

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

     

    Body sample

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

    5.3.2.2.2. Errors

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

    {

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

    "httpStatusCode": 400

    }

    5.4. Attachments

    5.4.1. Add an attachment

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

    5.4.1.1. Request

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

    5.4.1.1.1. Headers

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

     5.4.1.1.2. Body

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

    Body sample

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

    HTTP Status Code: 201 Created

    The generated attachment id is returned in the location header.

    Headers

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

    5.4.2. Retrieve the metadata of an attachment

    5.4.2.1. Request

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

    5.4.2.1.1. Headers

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

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

    5.4.2.2.1. Errors

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

    5.4.3. Update metadata of the attachment

    Update the metadata of an attachment.

    5.4.3.1. Request

    HTTP Method: PUT

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

    5.4.3.1.1. Headers

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

    HTTP Status Code: 200 OK

    5.4.3.2.1. Errors

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

    5.4.4. Add or replace the binary of an attachment

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

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

    5.4.4.1.1. Headers

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

    5.4.4.1.2 Body

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

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

    HTTP Status Code: 200 OK

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

    5.4.5. Remove attachment

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

    5.4.5.1. Request

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

    5.4.5.1.1. Headers

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

    HTTP Status Code: 200 OK

    5.4.5.2.1. Errors

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

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

    5.5. Documents

    5.5.1. Add a document

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

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

    5.5.1.1.1. Headers

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

    5.5.1.1.2. Body

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

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

    Body sample

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

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


    Headers

    Location: 33

    5.5.1.2.1. Errors

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

    5.5.2. Retrieve the metadata of a document

    5.5.2.1. Request

    HTTP Method: GET

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

    5.5.2.1.1. Headers

    Key Value
    Authorization Bearer eyJlbm...zh9jQ

    5.5.2.2. Response

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

    5.5.3. Update metadata of the document

    Update a document's metadata.

    5.5.3.1. Request

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

    5.5.3.1.1. Headers

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

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

    5.5.3.2. Response

    HTTP Status Code: 200 OK

    5.5.4. Add or replace the binary of a document

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

    5.5.4.1. Request

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

    5.5.4.1.1. Headers

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

    5.5.4.1.2. Body

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

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

    HTTP Status Code: 200 OK

    5.5.4.2.1. Errors

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

    5.5.5. Remove document

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

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

    5.5.5.1.1. Headers

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

    HTTP Status Code: 200 OK

    5.6. UniqueKeys

    5.6.1. Check unique key

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

    5.6.1.1. Request

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

    5.6.1.1.1. Headers

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

    5.6.1.1.3. Body

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

    Body sample

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

    HTTP Status Code: 200 OK

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

    Body sample

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

    5.6.2. List unique keys

    This API returns a paged list of unique keys.

    5.6.2.1. Request

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

    5.6.2.1.1. Headers

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

    5.6.2.1.2. Query

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

    Amount of records to returned.

    5.6.2.2. Response

    HTTP Status Code: 200 OK

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

    Body sample

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

    5.7. Delivery, Document and Attachment Status

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

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

    5.7.1. Document Status

    Use this API to check the status of a document

    5.7.1.1. Document Statuses

    The following are the possible values for the documentStatus

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

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

    5.7.1.2.1.1. Headers

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

    Body sample

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

    5.7.1.2.3. Errors

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


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

    5.7.1.3.2. Query

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

    5.7.1.3.2.1. Headers

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

    Body sample

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

    5.7.1.3.4. Errors

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

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

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

    5.7.1.4.2. Query

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

    5.7.1.4.2.1. Headers

    Key Value
    Authorization Bearer eyJlbm...zh9jQ

    5.7.1.4.3. Response
    HTTP Status Code: 200 OK

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

    Body sample

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

    5.7.1.4.4. Errors

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

    5.7.1.5. Document Status History via CorrelationId's

    5.7.1.5.1. Request

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

    5.7.1.5.2. Query

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

    5.7.1.5.2.1. Headers

    Key Value
    Authorization Bearer eyJlbm...zh9jQ

    5.7.1.5.3. Response
    HTTP Status Code: 200 OK

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

    Body sample

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

    5.7.1.5.4. Errors

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

    5.7.2. Attachment Status

    Use this API to check the status of an attachment

    5.7.2.1. Attachment Statuses

    the following are the possible values for the attachmentStatus

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

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

    5.7.2.2.1.1. Headers

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

    Body sample

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

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

    AttachmentCorrelationId is mandatory

    DeliveryCorrelationId is optional

    5.7.2.3.1.1. Headers

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

    Body sample

    {
    "attachmentStatus": 0
    }

    5.7.3. Delivery Status

    Use this API to check the status of a delivery

    5.7.3.1. Delivery Statuses

    the following are the possible values for the deliveryStatus

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

    6

    Expired

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


    5.7.3.2. Delivery Status via DeliveryId

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

    5.7.3.2.1.1. Headers

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

    Body sample

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

    5.7.3.3.1. Request

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

    5.7.3.3.1.1. Headers

    Key Value
    Authorization Bearer eyJlbm...zh9jQ

    5.7.3.3.2. Response

    same as above, see here

    5.8. API StatusCheck

    5.8.1. Ping

    Check the status of a delivery API.

    5.8.1.1. Request

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

    5.8.1.1.1. Headers

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

    Body sample

    "pong"

    5.9. Error Codes

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

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

    5.10. Samples

    5.10.1. Sample Delivery

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

    5.10.1.1. Authentication

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

    5.10.1.1.1. Request

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

    Body

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

    5.10.1.1.2. Response
    HTTP Status Code: 200 OK

    Body

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

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

    5.10.1.2. Start Delivery

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

    Headers

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

    Body

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

    5.10.1.3.2. Response
    HTTP Status Code: 201 Created

    Headers

    Location: 33

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

    5.10.1.4. Submit Document Binary

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

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

    Headers

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

    Body

    multipart/form-data

    5.10.1.4.2. Response
    HTTP Status Code: 204 NoContent

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

    5.10.1.5. Complete Delivery

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

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

    Headers

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

    5.10.1.5.2. Response
    HTTP Status Code: 200 OK

    Body

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

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

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

    Headers

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

    Body

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

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

    5.10.2. Invoices Metadata Examples

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

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

    Body

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

    Body

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

    Body

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

    Body

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

    5.11. Special characters

    In all string fields the following characters are accepted:

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

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

    This is the regular expression being applied:

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

    6. Registration

    6.1. Introduction

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

    6.2. General Information

    6.2.1. Registration priorities

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

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

    6.3. Synchronous

    6.3.1. Overview

    The following diagram depicts the process for the synchronous registration.

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

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

    6.3.2. Authentication

    The sender has to provide the following information

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

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

    The service MUST follow the points listed below:

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

    6.3.3. Verifies the security answers

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

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

    6.3.3.1.1. Header

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

    6.3.3.1.2. Query

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

    6.3.3.1.3. Body

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

    Body sample

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

    HTTP Status Code: 200 OK

    6.3.3.2.1. Body

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

    Status description

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

    Body sample

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

    6.4. Asynchronous

    6.4.1. Overview

    The following diagram depicts the process for the asynchronous registration.

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

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

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

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

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

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

    6.4.2. Get pending registrations

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

    6.4.2.1. Request

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

    6.4.2.1.1. Headers

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

    6.4.2.1.2. Query

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

    HTTP Status Code: 200 OK

    6.4.2.2.1. Body

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

    Body sample

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

    6.4.3. Verify answers

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

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

    6.4.3.1.1. Headers

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

    6.4.3.1.2. Query

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

    6.4.3.1.3. Body

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

    Status description

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

    Body sample

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

    HTTP Status Code: 200 OK