Newspaper online services API

Newspaper online services API

Close

    Newspaper online services API

    1. Introduction

    A first API (no. 1) allows you to send the data for submitting newspapers to Swiss Post and receive a delivery note in PDF format in return. The transmitted data can be viewed via the “Dispatch list for newspapers” online service in the Swiss Post portal and, if necessary, supplemented with weight details. In addition, you can retrieve various reports about your newspaper. 

    The following newspaper products are supported by the first API: 

    Swiss newspapers:

    • Sorted
    • Unsorted
    • Large print run
    • Unaddressed
    • Military 

    International newspapers:

    • Products per country (Eco/Priority)
    • List prices
    • Contract prices 

    Gratis newspapers:

    • Current circulation
    • Partial delivery notes
    • GZA flex 

    Inserts:

    • for Swiss newspapers
    • for gratis newspapers
    • from the same mailer 

    Statistical data:

    • at house key/mail carrier district level
    • at postcode level 

    Another API (no. 2) supports the transmission of statistical data regarding newspaper submissions. The third API (no. 3) is used for placing an order to have your addresses verified and the dispatch documents prepared. It covers the functions of the “Preparation of newspaper dispatch” online service. 

    2. Use cases

    The following use cases are covered by the three APIs: 

    Use case API (no. and name) Request type(s)
    Register for newspaper delivery (submission of dispatch list)
    1, order
    POST
    Status check of the registered newspaper delivery
    1, order
    GET
    Retrieve the delivery note for the newspaper submission
    1, order
    GET
    Retrieve reports for an order
    1, order
    GET
    Request basic information about a newspaper
    1, newspaper
    GET
    Download distribution list and/or purge list for a gratis newspaper
    1, distribution GET
    Transmit statistical data
    2, statistics
    POST
    Verify, correct and sort addresses
    3, address
    POST, GET
    Retrieve structure file
    3, structurefile
    GET

    3. Overview

    The diagram below shows the possible processes associated with the first API.

    (1) Registration and transmission of the submission data and/or addresses to the API

    (2) When all data has been transmitted, a delivery note and, if necessary, the sorted addresses and a sorting protocol are returned.

    (3) If no weights were specified in section (1), they are now added manually via the “Dispatch list for newspapers” online service on the Swiss Post portal.

    (4) The dispatch documents are printed out directly or via the “Dispatch list for newspapers” online service on the Swiss Post portal.

    (5) Information (in cases of discrepancy and upon completion) is retrieved via the API or sent to publishers via e-mail.

    4. Status sequence of an order

    5. The scope SENDINGS_NEWSPAPER_SUBMISSION_ORDERS of the “submission” API

    The API scope “orders” allows you to transmit a complete order with all necessary parameters to the “Dispatch list for newspapers” online service. As a response, you will receive an order ID. This ID can then be used to retrieve the delivery note and proof of mailing via the API. At the same time, it enables you to check the order status and to retrieve various reports.

    The API processes the following requests:

    Type Request Description Response Class (Status 200)
    POST /logistics/newspaper/submission/v1/orders/standard
    Create an order for standard newspapers with swiss and/or international shipments
    The order is created
    POST /logistics/newspaper/submission/v1/orders/gratis
    Create an order for gratis newspapers with swiss shipments
    The order is created
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ delivery-note
    Get the documents requested to deposit the newspapers in a postal center. For gratis newspapers, the partial delivery notes are available with this request too
    The delivery documents available for the order
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ status 
    Get the current status of the order
    The current status of the order
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ summary 
    Get the basis information of the order. This request is not allowed when the order is in the status CONTROL 
    All the basis information of the order
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ sendings 
    Get the national, international and gratis items information for the order. This request is not allowed when the order is in the status CONTROL
    All the basis contained in an order
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ original-standard-order
    Get all the originally sent order
    The order as it was originally sent
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ corrected-standard-order
    Get all the order with the corrections done by the Swiss Post
    The order released by the Swiss Post including possible corrections
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ original-gratis-order 
    Get all the originally sent order 
    The order as it was originally sent
    GET /logistics/newspaper/submission/v1/orders/{orderId}/ corrected-gratis-order
    Get all the order with the corrections done by the Swiss Post 
    The order released by the Swiss Post including possible corrections

    The full documentation can be found at the developer portal.


    6. The scope SENDINGS_NEWSPAPER_SUBMISSION_NEWSPAPERS of the “submission” API

    The API scope “newspapers” allows you to retrieve the basic information about a newspaper title. It processes the following request:

    Type Request Description Response Class (Status 200)
    GET /logistics/newspaper/submission/v1/newspapers/ {newspaperNumber}/summary
    Get the basic information for a newspaper.
    The basic information for a newspaper

    The full documentation can be found at the developer portal.


    7. The scope SENDINGS_NEWSPAPER_SUBMISSION_DISTRIBUTION of the “submission” API

    The API scope “distribution” allows you to retrieve additional documents related to a gratis newspaper title. 

    The API processes the following requests:

    Type Request Description  Response Class (Status 200)
    GET /logistics/newspaper/submission/v1/distribution/newspapers/ {newspaperNumber}/distribution-list
    Get the distribution list of a gratis newspaper 
    The complete distribution list
    GET /logistics/newspaper/submission/v1/distribution/newspapers/ {newspaperNumber}/black-list
    Get the black list of a gratis newspaper
    The complete black list. 

    The full documentation can be found at the developer portal.

    8. The scope SENDINGS_NEWSPAPER_STATISTIC of the “statistics” API

    The API scope “statistics” is used for transmitting statistical data related to a newspaper title. This transmission takes place at certain intervals, depending on the frequency of publication of each title.

    • AZ: quarterly, for the last submission of each quarter
    • AZA: every six months, for the last submission of each semester
    • AZB: every twelve months, for the last submission of each year 

    The API processes the following request:

    Type
    Request
    Description
    Response Class (Status 200)
    POST
    /logistics/newspaper/statistic/v1/standard/statistics
    Send statistics for a standard newspaper
    The statistics are successfully transmitted

    The full documentation can be found at the developer portal.

    9. The scope SENDINGS_NEWSPAPER_ADDRESS of the “address” API

    This API scope is not dependent on a newspaper number and can therefore also be used for other products. It provides access to the “Preparation of newspaper dispatch” online service, which validates and/or corrects a complete address database upon request and sorts the address list for dispatch by mail carrier district and route. 

    Outputs include the sorted address list, the invalid addresses as well as the required dispatch documents (bundle labels, pallet addresses, bundle protocol). 

    The API subgroup “address” processes the following requests:

    Type
    Request
    Description
    Response Class (Status 200)
    POST /logistics/newspaper/address/v1/purchases
    Create a purchase to validate and/or sort the given addresses.
    The purchase is created
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ progress
    Get the progress of the purchase
    The current progress of the purchase 
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ output-addresses 
    Get the validated and/or sorted addresses of the purchase 
    The list of output addresses
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/original-addresse
    Get the document containing the original addresses (= the originally uploaded addresses) 
    The document containing the original addresses
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/output-addresses
    Get the document containing the output addresses 
    The document containing the output addresses
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/non-reusable-addresses 
    Get the document containing the not reusable addresses. Not reusable addresses are only available if the option for 'address clean up' was selected in the purchas
    The document containing the not reusable addresses
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/bundle-labels
    Get the document containing the bundle labels 
    The document containing the bundle labels
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/container-labels
    Get the document containing the container labels 
    The document containing the container labels
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/sort-protocol
    Get the document containing the sorting protocol
    The document containing the sorting protocol 
    GET /logistics/newspaper/address/v1/purchases/{purchaseId}/ document/order-confirmation
    Get the document containing the order confirmation
    The document containing the order confirmation

    The full documentation can be found at the developer portal

    The API subgroup “structurefile” processes the following requests regarding the structure files: 

    Type
    Request
    Description
    Response Class (Status 200)
    GET /logistics/newspaper/address/v1/structurefiles/{fileCode}
    Get the structure files according to the given code (1=AZ/GZA, 2=AZA/AZB, 9=both)
    The list with the binary representation of the structure files
    POST /logistics/newspaper/address/v1/structurefiles/email
    Set an email address as the recipient of notification if there are new versions of structure files
    Confirmation of acceptance

    The full documentation can be found at the developer portal.

    10. Examples of JSON objects

    10.1 Submission of a new order for a new issue of a newspaper

    Methode: POST, Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/submission/v1/orders/standard

    Scope: SENDINGS_NEWSPAPER_SUBMISSION_ORDERS

    Body (JSON):

    {   "language": "DE",   "basisInformation": {     "newspaperNumber": "31224",     "issueNumber": {       "from": 9     },     "lateDelivery": false,     "deliveryDate": "2020-04-09",     "differenceEmails": [       "dietrich.draeyer@post.ch"     ],     "confirmationEmails": [ 
          "dietrich.draeyer@post.ch"     ]   },   "sender": {     "companyName1": "Zeitungskunde_1",     "address1": "Wankdorfallee 4",     "zipCode": 3014,     "city": "Bern"   },   "nationalDelivery": {     "sortedDelivery": {       "sortedShipments": [         {           "weight": 289,           "countMailMan": 47560,           "countCity": 1715,           "countRest": 162,           "shipmentRemark": "GL1-1"         },         {           "weight": 294,           "countMailMan": 169,           "countCity": 576,           "countRest": 366,           "shipmentRemark": "ZH3-1"         },         {           "weight": 297,           "countMailMan": 50672,           "countCity": 1734,           "countRest": 751,           "shipmentRemark": "GR1-1"         },         {           "weight": 297,           "countMailMan": 203229,           "countCity": 2210,           "countRest": 633,           "shipmentRemark": "ML1-1"         },         {           "weight": 297,           "countMailMan": 51,           "countCity": 370,           "countRest": 533,           "shipmentRemark": "ML3-1"         },         {           "weight": 297,           "countMailMan": 142707,           "countCity": 2677,           "countRest": 784,           "shipmentRemark": "SG1-1"         },         {           "weight": 297,           "countMailMan": 174245,           "countCity": 1998,           "countRest": 611, 
              "shipmentRemark": "WI1-1"         },         {           "weight": 297,           "countMailMan": 14,           "countCity": 314,           "countRest": 450,           "shipmentRemark": "WI3-1"         },         {           "weight": 297,           "countMailMan": 215743,           "countCity": 2394,           "countRest": 597,           "shipmentRemark": "ZE1-1"         },         {           "weight": 297,           "countMailMan": 354436,           "countCity": 7480,           "countRest": 829,           "shipmentRemark": "ZH1-1"         }       ],       "largeEditionShipments": [],       "appendixShipments": [],       "sortFile": {}     }   },   "internationalDelivery": {     "internationalShipments": [       {         "productLabel": "Press",         "country": "EUR",         "contractPrice": false,         "priorityShipments": [],         "economyShipments": [           {             "weight": 181,             "count": 1805,             "shipmentRemark": "Test"           }         ]       }     ]   } } 

    Note: 

    • The value for “deliveryDate” must be greater than or equal to the current date.

    Sample response:

    {   "id": 25543 }

    10.2 Order status query

    Methode: GET, Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/submission/v1/orders/25543/status

    Scope: SENDINGS_NEWSPAPER_SUBMISSION_ORDERS

    Sample response:

    {   "statusValue": "LOADED",   "statusDate": "2020-04-09T15:31:11+02:00" }

    10.3 Order summary query

    Methode: GET,

    Endpoint: https://sendings-newspaper.apis.post.ch/logistics/newspaper/submission/v1/orders/25543/summary

    Scope: SENDINGS_NEWSPAPER_SUBMISSION_ORDERS

    Sample response:

    {   "issueDate": "2020-04-09",   "issueNumber": {     "from": 9   },   "barcodeNumber": "981813122402554300",   "totalNewspaper": 1217815,   "statusValue": "LOADED",   "difference": false }

    10.4 Newspaper master data query

    Methode: GET,

    Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/submission/v1/newspapers/31224/summary

    Scope: SENDINGS_NEWSPAPER_SUBMISSION_NEWSPAPERS

    Sample response:

    {   "newspaperNumber": 31224,   "newspaperID": 8781,   "title": "Coop Zeitung (AZ Medien)",   "publisherName": "Coop Genossenschaft",   "printerName": "Mittelland Zeitungsdruck AG",   "postCustomerService": "CENTRAL",   "region": "Basel",   "periodicity": 52,   "format": "TALLER_THAN_B_5",   "language": "DE",   "textQuota": 50,   "addressMethod": "ADDRESSED",   "sendingZipCode": 462167,   "sendingCity": "Härkingen BZ Annahme",   "postagePaidImpression": "AZA",   "postagePaidImpressionZipCode": 195300,   "postagePaidImpressionCity": "Sion Response Zentral" }

    10.5 Gratis newspaper distribution list query

    Methode: GET,

    Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/submission/v1/distribution/newspapers/65304/distribution-list

    Scope: SENDINGS_NEWSPAPER_SUBMISSION_DISTRIBUTION

    Sample response:

    {   "distributionType": [     "OFFICIAL_PLUS"   ],   "startDate": "2019-12-02",   "lastDistributionDataUpdate": "2019-04-08",   "depositDay": [],   "distributionDay": [],   "periodicity": 220,   "distributionListDetails": [     {       "zipCode": 3054,       "city": "Schüpfen",       "canton": "BE",       "locationCategory": "B",       "count": 1792,       "poBox": false,       "distributionType": "OFFICIAL_PLUS",       "packedInSacks": false,       "bundlesInSB": true,       "deliveryZipCode": 305400,       "unloadZipCode": 305400,       "unloadPlace": "Schüpfen",       "unloadTime": "18:00:00",       "containerTargetId": "3054000002"     },     {       "zipCode": 3054,       "city": "Schüpfen",       "canton": "BE", 
     
    .. snip ..

    10.6 Statistical data submission

    Methode: POST,

    Endpoint: https://sendings-newspaper.apis.post.ch/logistics/newspaper/statistic/v1/standard/statistics

    Scope: SENDINGS_NEWSPAPER_STATISTIC

    Body (JSON):

    {     "statistics": [   {    "newspaperId": 10001,    "split": "0",    "product": "TUESDAY_EDITION",    "houseKey": 1,    "bbz": 2,    "aplz": 3,    "city": "City",    "deliveryDate": "2019-11-06",    "bundleType": "NOT_BUNDLED",    "count": 1000   },   {    "newspaperId": 10001,    "split": "0",    "product": "FRIDAY_EDITION",    "houseKey": 4,    "bbz": 5,    "aplz": 6,    "city": "Neuchâtel",    "deliveryDate": "2019-11-01",    "bundleType": "CITY",    "count": 500   }  ] } 

    Sample response:

    "Statistic File successfully uploaded"

    10.7 Submission of a new order for address sorting and dispatch document creation

    Methode: POST,
    Endpoint: https://sendings-newspaper.apis.post.ch/logistics/newspaper/address/v1/purchases

    Scope: SENDINGS_NEWSPAPER_ADDRESS

    Body (JSON):

    {   "title": "Test API XY",   "depositDate": "2020-04-08",   "language": "EN",   "frankingLicence": "300765",   "offerOption": "NO_PRICE",   "offerEmail": "dietrich.draeyer@post.ch",   "addresses": [     {       "id": "1",       "firstName": "Jules",       "lastName": "Richard",       "street": "Rue de la Gare",       "houseNumber": "12",       "zipCode": 2000,       "city": "Neuchâtel",       "isoCode": "CH"     },     {       "id": "2",       "firstName": "firstName",       "lastName": "lastName",       "street": "Bahnhofstrasse",       "houseNumber": "12B",       "zipCode": 3001,       "city": "Berne",       "isoCode": "CH"     }   ],   "levelValidation": "COMPLETE",   "sortingModule": {     "levelSorting": "NORMAL",     "sortingParameters": {       "customerReference": "customerReference",       "dispatcher": "dispatcher",       "forwardingName": "forwardingName",       "issueNumberFrom": 1,       "language": "EN",       "productCode": "AZA_WEEKLY_AND_BI_MONTHLY",       "sender": "sender",       "sendingInternational": "POST_CH",       "sendingSwiss": "PRIORITY",       "weightPerCopyInGram": 12,       "postagePaidImpressionSwiss": "impressionSwiss",       "postagePaidImpressionInternational": "impressinInter"     },     "simplifiedConfiguration": {       "bundle": {         "min": 250,         "max": 3000,         "unit": "GRAM"       },       "container": {         "min": 250,         "max": 3000,         "unit": "GRAM"       }     }   } }

    Sample response (= OrderID):

    12004

    10.8 Order processing status query

    Methode: GET,

    Endpoint: https://sendings-newspaper.apis.post.ch/logistics/newspaper/address/v1/purchases/12004/progress

    Scope: SENDINGS_NEWSPAPER_ADDRESS

    Sample response:

    {   "validationStatus": "READY",   "validationProgressPercent": 100,   "sortingStatus": "READY" }

    10.9 Collection of the sorted addresses

    Methode: GET,

    Endpoint: https://sendings-newspaper.apis.post.ch/logistics/newspaper/address/v1/purchases/12004/outputaddresses

    Scope: SENDINGS_NEWSPAPER_ADDRESS

    Sample response:

    {   "outputAddresses": [     {       "statusCode": "51",       "bundleId": "1",       "bundleInfo": "MANUALLY",       "id": "1",       "firstName": "Jules",       "lastName": "Richard",       "street": "Rue de la Gare",       "houseNumber": "12",       "zipCode": 2000,       "city": "Neuchâtel",       "isoCode": "CH",       "quantity": 1     },     {       "statusCode": "51",       "bundleId": "1",       "bundleInfo": "MANUALLY",       "id": "2",       "firstName": "firstName",       "lastName": "lastName",       "street": "Bahnhofstrasse",       "houseNumber": "12B",       "zipCode": 3001,       "city": "Berne",       "isoCode": "CH",       "quantity": 1     }   ] }

    10.10 Retrieval of the order confirmation

    Methode: GET,

    Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/address/v1/purchases/12004/document/order-confirmation

    Scope: SENDINGS_NEWSPAPER_ADDRESS

    Sample response:

    {   "document": {     "mimeType": "application/pdf",     "size": 31673,     "data": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9Db2xvclNwYWNlWy9DYWxHcmF5PDwvR2FtbWEgMi4y L1doaXRlUG9pbnQgWzEgMSAxXT4+XS9JbnRlbnQvUGVyY2VwdHVhbC9TdWJ0eXBlL0ltYWdlL0hlaWdodCAyMzMvR mlsdGVyL0ZsYXRlRGVjb2RlL1R5cGUvWE9iamVjdC9EZWNvZGVQYXJtczw8L0NvbHVtbnMgOTI1L0NvbG9ycyAxL1 ByZWRpY3RvciAxNS9CaXRzUGVyQ29tcG9uZW50IDg+Pi9XaWR0aCA5MjUvTGVuZ3RoIDI0NzIvQml0c1BlckNvbXB vbmVudCA4Pj5zdHJlYW0KeNrtndtu5EYMBU1hPmz05Zo/Yx4WWSBZe2ckNdmH7KqHIEhsXdisJqm52PwLACTZCAGA KA9CAMti4We415pSOwHobAGWK53YCUDtBIDMsRM7AaidAICdAB9h2AkA2AkghmMnALUTALATIB7DTgDGTuwEoLMFA OwEWHrsxE4A7ARYDMdOAGonAGAnQDyGnQCAnQBiDPged77PFuCOVJEtMrUTgM4WQAeTOxB2AsRPi9gJ0F9z7ARg7g ToN3ZiJ8CammMnwNhpcdyBsB 
     
    .. snip .. 

    10.11 Retrieval of the newspaper bundle labels

    Methode: GET,

    Endpoint: https://sendingsnewspaper.apis.post.ch/logistics/newspaper/address/v1/purchases/12004/document/bundle-labels

    Scope: SENDINGS_NEWSPAPER_ADDRESS

    Sample response:

    {   "document": {     "mimeType": "PDF",     "size": 1521,     "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3RoIDUzNT4+ c3RyZWFtCnicjZTBcpswEIbveoo90gOptFphcXSmbi5up43JobkRo6R0bOyAnUzevpLwAYSoa2Z8WH720+7+Kw4CU gEcVK7s/3bPXtltwWQGSuVQVGxVsJ9MwDvj4J77O6Y5oM5AIIeUNLSGbezLO/eZ8BoBmgAzDcWeff4qQBAUzywpfp /brio/PhV/RkJaOGHC8xtON8iRO8GqmEClpGtQidhD0So9dFXVp/rQBEzJKTicmINqvApd8AB6e26qnYHt4VibLkQ rDNA4gybJr6FJ6Di6Oe+fTBugifP/rFpx1aMXag6tSAbozjRVzwwzok0lMyu0zUwFUjQn2riksJWr5tSWzdYMS/HK ftLJ2pRv05f9eJPN+anbtvXROSAyDSd1TnbSe9OZdprp4uJkczTbutzZg8dlyp87+WJ29ZtpP+B0OJW7SysGNUqyh 5vMbJjNK/icRYJUqMN2hakw6zsxiVO4nVEXusF5G7rBDW04UXnHONWMYxA1UB5u58a8ns1kula5mB7bx1UWHJvbX6 Q5QkZoD83uUFZ18wLHQ92cRj1xH0SgPj6B/lg/gkjzCxeHvSA7O2d1mfF5q5NwAvrH7Lyin9E0LjEeF1k8Plh77Un flt8fluv1r9jIXQH9+mfjYY7KVDn1KrsfqbBXQdwZPlkmvFHnrjHi2l4mi6AZy8flqA4nwtzXV++Pdg07u9Ob97rr LkX8BYEJcVEKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8L0NvbnRlbnRzIDMgMCBSL1R5cGUvUGFnZS9SZXNvd XJjZXM8PC9Qcm9jU2V0IFsvUERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJXS9Gb250PDwvRjEgMSAwIF IvRjIgMiAwIFI+Pj4+L1BhcmVudCA0IDAgUi9Sb3RhdGUgOTAvTWVkaWFCb3hbMCAwIDU5NSA4NDJdPj4KZW5kb2J qCjEgMCBvYmoKPDwvU3VidHlwZS9UeXBlMS9UeXBlL0ZvbnQvQmFzZUZvbnQvSGVsdmV0aWNhLUJvbGQvRW5jb2Rp bmcvV2luQW5zaUVuY29kaW5nPj4KZW5kb2JqCjIgMCBvYmoKPDwvU3VidHlwZS9UeXBlMS9UeXBlL0ZvbnQvQmFzZ UZvbnQvSGVsdmV0aWNhL0VuY29kaW5nL1dpbkFuc2lFbmNvZGluZz4+CmVuZG9iago0IDAgb2JqCjw8L0tpZHNbNS AwIFJdL1R5cGUvUGFnZXMvQ291bnQgMS9JVFhUKDEuMC4wLVNOQVBTSE9UKT4+CmVuZG9iago2IDAgb2JqCjw8L1R 5cGUvQ2F0YWxvZy9QYWdlcyA0IDAgUj4+CmVuZG9iago3IDAgb2JqCjw8L01vZERhdGUoRDoyMDIwMDQwOTE3MTM1 NyswMicwMCcpL0NyZWF0aW9uRGF0ZShEOjIwMjAwNDA5MTcxMzU3KzAyJzAwJykvUHJvZHVjZXIoT3BlblBERiAxL jAuMC1TTkFQU0hPVCk+PgplbmRvYmoKeHJlZgowIDgKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwNzkzIDAwMD AwIG4gCjAwMDAwMDA4ODYgMDAwMDAgbiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwOTc0IDAwMDAwIG4gCjA wMDAwMDA2MTcgMDAwMDAgbiAKMDAwMDAwMTA0NiAwMDAwMCBuIAowMDAwMDAxMDkxIDAwMDAwIG4gCnRyYWlsZXIK PDwvSW5mbyA3IDAgUi9JRCBbPDM4YTRmOGFkYTBkMjZhMTEyOWY5Y2Q0MzQzZmUzMjMzPjw2ZTFhMDZjMmVmM2MxM WE5NDFlYTkzNDI3OTM5NWIxMT5dL1Jvb3QgNiAwIFIvU2l6ZSA4Pj4Kc3RhcnR4cmVmCjEyMTUKJSVFT0YK"   } }

    11. Authentication

    The access to the Swiss Post Newspaper API is controlled by OAuth 2.0 client credential flow.

    Only Swiss Post registered clients can be authorized to consume the Swiss Post Newspaper API. The endpoints of the Newspaper API require the authorization of the end users when personal data is queried.

    OAuth is an authorization protocol and not an authentication protocol. The client and the end user have to be authenticated; consequently the authentication is an implicit part of the protocol.

    For more information see RFC 6749 - Client Credentials Grant.

    11.1 OAuth 2.0

    A client of the Swiss Post Newspaper API must first obtain an OAuth access token in order to consume the endpoints of the API.

    • The client is authenticated by the OAuth credentials received after a successful registration: client-id, client-secret.
    • A set of scopes need to be mentioned when ordering the access token, a scope corresponds to a use case applied on one or more endpoints of the API.
    • These scopes must be a subset of the ones configured during the registration process.
    • Moreover the end user may have to be authenticated and have to authorize the client for the set of ordered scopes.
    • Finally an access token is returned to the client through a redirection URL configured during the registration. The returned access token is a bearer token.
    • Depending on the implemented OAuth flow for the query of the access token, a refresh token is returned. This is used for access token renewal without user consent.

    The OAuth authorization protocol defines a set of standard flows for querying an access token. A client of the Swiss Post Newspaper API is responsible for the integration of the desired flows in his use cases.

    For more information see: https://tools.ietf.org/html/rfc6749

    11.2 Request

    Auth URL provided following contract signing 
    Access Token URL
    provided following contract signing 

    An access token has to be requested with the following key-value pairs in a POST request:

    key value
    client_id
    provided following contract signing
    client_secret
    provided following contract signing
    scope
    TBD
    grant_type
    client_credentials

    11.3 Sample response

    { "access_token": "n0xtJFWREwWhAq_Lzq6ahROIcc5N59l-SN3Yi0TXwxUuQ5yVpYm-kY8iRB1byc57rtmtJivH7lhlP11CX 
    taoiE2Jh6y7fHn6Lqf0NJ1ONL7fxrkPpqIENDsprGMfXjC2.CMeSDXXJ5NylTWXX5Li-mM.1yLQ_q7KYZP.UMAzyj_km8nZayw 
    brrtqBH4oeMG9hFEcerxVv9yPXD0376bJOJQRyZT6bSuiHyzJxtIcMy3Tlg8ZaU6fRm.jGxjulisJ6x_STG0zK1nI16W0bJGit 
    PiDStG6bTED4XHriOLZUPUSZDxcjnm2JeTywgmncnrDReteJSe7BuHI6lCYTD9S5SZiK24u67vcFS8xVtwZyl7YM1zN64r1BSR 
    sy4icGeMSKowirMRpm0wZ40xYMzABh5baP-TUvvJPlLAsF-CZo6RuWNkJZATR4N7CPXlzx_YemXc32-FY08F6go9wCa-aFDAFZ 
    BRXJc8Ds3ACsjhy.UnYPlWoDOrOellexv11QIoz.Pqrohn7jMcWxyTumtDroVsECaohXllLUvUBTufa8Abl162Rc4pXuI1Pcm. 
    eL22Lx.A6VLRgu28Lm.wfszskMbfVVFLh7-iZeuFESU-GcEbt.03-DbICraUH1QRA_0pHUuulQTpK_F-v29FIfM-8_Zq4-hMF. 7W2r6o_I
    bZlyDr_OavG93EjSq9L_21q7pLyL7lrVS_cjinQDW_UFRk26vuBsTrzYsHm3U7B8qNxW3w7TFQ_VPJ8hDRqOb4VFn 
    Gp1u1eMFRxgR9HWO3ccw-NPPxJJja.Ipqb2b8tV1CjQUmomLzcvWefH3bE6QM.iq4ksky5F3iFLuO_rIAAgfGQ8b-z53F3jeU9 
    _ab7gwcPIq0fIPpG81H64S-.l4MJ1wjvILLM_jlqZHf85K8LSXZH1CMoMg0yMRmgR2rF38AfIKmVcc9-aFZAJMZRJzJaAf3AaH b1
    g3LwPL073oG8QDem5LZ0mXPSCWP47nODNBq1DDTChRnnJZ8W_uWR0Yj7wOzBwrVjpumKCCRBhf2q2y96hU-FLiRR7fZ6KG1 4gZcaFcCRrQYKa5j_rqH3bne_ZnigEl2",  "token_type": "Bearer",  "expires_in": 60 }

    Use the returned Bearer token in the request header to access the API within the time limit returned in the expires_in attribute.

    key
    value
    Authorization
    Bearer n0xtJFWREwWhAq_Lzq6ahROIcc5N59l-SN3Yi0TXwxUuQ5yVpYmkY8iRB1byc57rtmtJivH7lhlP11CX...

    11.4 OAuth 2.0 Libraries

    We do suggest that you do not implement the OAuth2.0 protocol by yourself. Many libraries/frameworks exist and handle the standard OAuth2.0 authentication and we suggest you to choose one of them.

    For example, you could use https://oauth.net/code/

    11.5 Use of the client credentials in test tools

    The use of client credentials is explained based on the example of the Postman test tool.

    Figure 1: Order status query 
    Figure 2: Prior retrieval of the access token

    12. Error and warning messages

    Errors and warnings are returned in the following format:

    {   "error": "The order doesn't exist.",   "resource": null } 

    Important: be aware that the status code of a request can be 200 but the response contains errors and warnings. Do not treat a status code 200 as a successful call per se. Always evaluate the error and warning arrays.

    [No.]
    [Comment]
    0000
    This function is not available yet.
    0001
    User {username} has no authorization for title {newspaper number}.
    0002
    Newspaper number {number} not found. 
    0003
    Newspaper {number} does not use a sort file and can therefore not be transmitted via the API.
    0004
    A cash payment is required for this issue before it can be processed further. Please contact our customer service at {telephone number} or e-mail {e-mail address}.
    0005
    Invalid date format or issue date is in the past. 
    0006
    Postcode {4 digits} not permitted as an acceptance point. Permitted values are: {postcode list}. 
    0007
    This issue number {value} was previously used for another issue. 
    0008
    Wrong issue number {value}: “Issue number to” must be greater than the issue number. 
    0009
    Issue number {value} not permitted.
    0020
    District bundles not possible for this newspaper. 
    0021
    Locality bundles not possible for this newspaper.
    0022
    Other bundles not possible for this newspaper. 
    0023
    Unaddressed copies not possible for this newspaper.
    0024
    Military copies not possible for this newspaper. 
    0030
    The permitted weight range for district bundles is {grams} to {grams} only.
    0031
    The permitted weight range for locality bundles is {grams} to {grams} only.
    0032
    The permitted weight range for other bundles is {grams} to {grams} only.
    0033
    The permitted weight range for unaddressed copies is {grams} to {grams} only. 
    0034
    The permitted weight range for military copies is {grams} to {grams} only. 
    0040
    Monday to Friday large print run not possible for this newspaper. 
    0041
    Saturday large print run not possible for this newspaper. 
    0042
    The permitted weight range for Monday to Friday large print runs is {grams} to {grams} only. 
    0043
    The permitted weight range for Saturday large print runs is {grams} to {grams} only. 
    0050
    Number of inserts greater than number of newspaper copies. 
    0051
    Insert description too long. Maximum of {number} characters permitted. 
    0052
    Insert lighter than newspaper not possible for this newspaper. 
    0053
    Insert heavier than newspaper not possible for this newspaper. 
    0054
    The permitted weight range for inserts lighter than the newspaper is {grams} to {grams} only.
    0055
    The permitted weight range for inserts heavier than the newspaper is {grams} to {grams} only. 
    0070
    Unsorted copies not possible for this newspaper. 
    0071
    Unsorted military copies not possible for this newspaper. 
    0072
    The permitted weight range for unsorted copies is {grams} to {grams} only. 
    0073
    The permitted weight range for unsorted military copies is {grams} to {grams} only. 
    0100
    No distribution list available for this newspaper. Please contact our customer service at {telephone number} or e-mail {e-mail address}.
    0101
    Distribution list for this newspaper invalid. Please contact our customer service at {telephone number} or e-mail {e-mail address}. 
    0102
    Location category A Gratis Newspaper not possible for this newspaper.
    0103
    Location category B Gratis Newspaper not possible for this newspaper. 
    0104
    Location category C Gratis Newspaper not possible for this newspaper. 
    0105
    The permitted weight range for Location category A Gratis Newspaper copies is {grams} to {grams} only. 
    0106
    The permitted weight range for Location category B Gratis Newspaper copies is {grams} to {grams} only.
    0107
    The permitted weight range for Location category C Gratis Newspaper copies is {grams} to {grams} only.
    0110
    Gratis newspaper insert lighter than newspaper not possible for this newspaper. 
    0111
    Gratis newspaper insert heavier than newspaper not possible for this newspaper. 
    0150
    {Product name} is not a valid international product.
    0151
    No country found for ISO code {ISO code}.
    0152
    Comment too long. Maximum of {number} characters permitted. 
    0153
    {category}/{tariff group} {ISO code} - {dynamically defined error message}
    0170
    No list price for Economy {product} permitted for {country name}. 
    0171
    No list price for Priority {product} permitted for {country name}. 
    0172
    No contract price for Economy {product} permitted for {country name}. 
    0173
    No contract price for Priority {product} permitted for {country name}. 
    0174
    The permitted weight range for International {product } Economy (list price) country: {name} is {grams} to {grams} only.
    0175
    The permitted weight range for International {product } Priority (list price) country: {name} is {grams} to {grams} only. 
    0176
    The permitted weight range for International {product } Economy (contract price) country: {name} is {grams} to {grams} only. 
    0177
    The permitted weight range for International {product } Priority (contract price) country: {name} is {grams} to {grams} only. 
    0200
    Statistics cannot be processed.