Skip to content

How to work with the B2B marketplace service

Technical definitions of each API, sample code, test UI and Open API definitions to download you can find in the developer portal.
-> developer.discover.swiss/apis

Overview

Detailed definitions of the endpoints you can find for each api in the developer portal of our Api Management including sample code and Open API definition download. B2b Marketplace service is responsible for placing and paying orders for partners.

The discover.swiss Checkout process is defined and implemented by the order-state machine defined on Order item states. This is a step by step how-to for implementing the client side.

Profile and customer

In the B2B case, we connect the order with the partner's profile which we must create for you during the onboarding process. Any customer can be provided when placing the order.

Create, configure and place an order

On the client side the full order object is created with references to products and travelers.

POST {{marketUrl}}/orders  
PUT {{marketUrl}}/orders/{{orderNumber}}
This is the minimal data the client needs to send to create an order for a Zürich-card 24h.

minimal order

{
  "orderStatus": "Placed",
  "priceCurrency": "CHF",
  "Customer": {
    "givenName": "John",
    "familyName": "Dou",
    "birthDate": "1974-12-18T00:00:00Z",
    "email": "j.dou@test.biz"
  },
  "orderedItem": [
      {
          "orderQuantity": 1,
          "orderedItem": {
              "product": {
                    "identifier": "NOVA_zurichcard24"
              },
              "validFrom": "2019-12-24T06:15:00+01:00",
              "traveler": [
                  {
                      "givenName": "Philipp",
                      "familyName": "Muster",
                      "birthDate": "1968-06-26T00:00:00+02:00"
                  }
              ]
          }
      },
      {
          "orderQuantity": 1,
          "orderedItem": {
              "product": {
                    "identifier": "NOVA_zurichcard72"
              },
              "validFrom": "2019-12-28T06:15:00+01:00",
              "traveler": [
                  {
                      "givenName": "Sohn",
                      "familyName": "Tester",
                      "birthDate": "2008-01-01T00:00:00+01:00"
                  }
              ]
          }
      }
  ],
  "term": [
      {
          "termCode": "ZHT-AGB|ZHT-DPP",
          "accepted": true
      }
  ]
}

  • The customer must have a GivenName, FamilyName and Email
  • A BillingAddress is not mandatory, because we create e-tickets only
  • The product Identifier is the same in all environments (test/prod) but prices can change.
  • the order validation will add the name and the price on the orderItem
  • ValidFrom is the desired starting date and time of the ticket
  • Travelers must have a GivenName, FamilyName and BirthDate
  • orderNumber and orderItem-number is determined by the server and must not be part of the request
  • orderItem-state is determined by the server and not part of the request

accept terms and conditions

  • term list is created by the server based on the products in the order.
  • all terms must be accepted to initialize the payment (next step)
  • for this the terms must be part of the order-request
  • the property termDocument contains a link to the terms

Saving the order on the server (Post or Put) with

  • Status = Checkout validates the order but does not start anything more.
  • Status = Placed validates the order and if possible moves it to the placed state and the order is ready to get paid

The response contains the updated order object (product information, prices) and the validation errors if there are any.

sample response

{
    "order": {
        "orderNumber": "19-100164",
        "orderDate": "2019-12-13T14:47:51.6524834+00:00",
        "customer": {
            "profileId": "11661e9b-39a5-4d42-9b19-d0c2d6e14071",
            "address": {},
            "email": "sample@gmail.com",
            "familyName": "Muster",
            "faxNumber": "xxx",
            "givenName": "Philipp",
            "birthDate": "1967-12-07T01:00:00+01:00",
            "telephone": "033 100 11 11",
            "displayName": "Philipp Muster",
            "isGuest": "False",
            "createdDateTime": "2019-11-28T11:38:01.0845805+01:00",
            "lastModified": "2019-11-28T11:38:01.0845807+01:00"
        },
        "orderStatus": "Placed",
        "priceCurrency": "CHF",
        "totalAmount": 64.0,
        "totalAmountCHF": 64.0,
        "language": "en",
        "orderedItem": [
            {
                "orderItemNumber": "19-100164-1",
                "orderItemStatus": "Placed",
                "orderQuantity": 1,
                "orderedItem": {
                    "product": {
                        "@id": "http://localhost:7071/api/products/NOVA_zurichcard24",
                        "identifier": "NOVA_zurichcard24",
                        "name": "ZVV Zürich Card 24h",
                        "sku": "339102",
                        "priceList": [
                            {
                                "priceCHF": 0.0,
                                "maxAllowedAge": 5
                            },
                            {
                                "priceCHF": 19.0,
                                "maxAllowedAge": 15
                            },
                            {
                                "priceCHF": 27.0,
                                "maxAllowedAge": 2500
                            }
                        ],
                        "taxRate": 0.077
                    },
                    "validFrom": "2019-12-24T06:15:00+01:00",
                    "traveler": [
                        {
                            "priceCHF": 27.0,
                            "givenName": "Philipp",
                            "familyName": "Muster",
                            "birthDate": "1968-06-26T00:00:00+02:00"
                        }
                    ]
                },
                "orderDelivery": "e-ticket",
                "amount": 27.0,
                "amountCHF": 27.0,
                "tax": 2.079,
                "ticket": []
            },
            {
                "orderItemNumber": "19-100164-2",
                "orderItemStatus": "Placed",
                "orderQuantity": 1,
                "orderedItem": {
                    "product": {
                        "@id": "http://localhost:7071/api/products/NOVA_zurichcard72",
                        "identifier": "NOVA_zurichcard72",
                        "name": "ZVV Zürich Card 72h",
                        "sku": "387804",
                        "priceList": [
                            {
                                "priceCHF": 0.0,
                                "maxAllowedAge": 5
                            },
                            {
                                "priceCHF": 37.0,
                                "maxAllowedAge": 15
                            },
                            {
                                "priceCHF": 53.0,
                                "maxAllowedAge": 2500
                            }
                        ],
                        "taxRate": 0.077
                    },
                    "validFrom": "2019-12-28T06:15:00+01:00",
                    "traveler": [
                        {
                            "priceCHF": 37.0,
                            "givenName": "Sohn",
                            "familyName": "Muster",
                            "birthDate": "2008-01-01T00:00:00+01:00"
                        }
                    ]
                },
                "orderDelivery": "e-ticket",
                "amount": 37.0,
                "amountCHF": 37.0,
                "tax": 2.8489999999999998,
                "ticket": []
            }
        ],
        "term": [
            {             
                "termCode": "ZHT-AGB|ZHT-DPP",
                "accepted": true,
                "acceptedDate": "2020-02-06T18:43:39.203324+01:00",
                "termVersions": [
                    {
                        "@id": "http://localhost:7071/api/termversion/ZHT-AGB-2.0",
                        "code": "ZHT-AGB-2.0",
                        "name": "Allgemeine Geschäftsbedingungen von Zürich Tourismus",
                        "termDocument": "https://www.zuerich.com/gtc",
                        "validFrom": "2018-08-29T02:00:00+02:00",
                        "termCode": "ZHT-AGB"
                    },
                    {
                        "@id": "http://localhost:7071/api/termversion/ZHT-DPP-2019-10-28",
                        "code": "ZHT-DPP-2019-10-28",
                        "name": "Datenschutzerklärung von Zürich Tourismus",
                        "termDocument": "https://www.zuerich.com/datenschutz",
                        "validFrom": "2019-10-28T01:00:00+01:00",
                        "termCode": "ZHT-DPP"
                    }
                ]
            }
        ],
        "partnerAcronym": "Philipp",
        "profileId": "11661e9b-39a5-4d42-9b19-d0c2d6e14071",
        "@id": "http://localhost:7073/api/orders/19-100164",
        "createdDateTime": "2019-12-12T14:18:38.8819476+01:00",
        "lastModified": "2019-12-13T15:48:01.6872831+01:00"
    },
    "validationMessages": []
}
For possible errors and hints how to solve them see the list of the order validation messages in the reference section.

Payment

The payment step can be initialized by sending a request to the payment endpoint. This is not really a payment, but you can send a reference with it which will be on the invoice you get from discover.swiss. After this step, the fulfillment process starts automatically.

You can call the payment endpoint only successfully if the order is in state Placed. The URL of the endpoint (PUT):

PUT {{b2bmarketUrl}}/orders/{{orderNumber}}/payment

payment request

Fulfillment

During the fulfillment process, we communicate asynchronously with the partners and things can go wrong as we all know. If so - Information about all steps in the order workflow can be found in the BusinessTrail and in the partner portal.

Delivery

Delivery process starts automatically.
The delivery process is different for each supplier who delivers items in the order. We split the total amount of the order up settle with the various suppliers.

Get the tickets.

Polling the order

The client can poll the order (get /orders/{id}) and can check its state.
When the fulfillment process has finished the order Status = Fulfilled

In this state the order holds information about all tickets including the url to directly accessing it (ticketToken) and the qr-code (qrCodeToken).

Localization

default: de-CH

DateTime formatting: "2019-08-09T13:59:57.097+02:00"

Use Accept-Timezone header to specify request timezone. Supply a TimeZone id acquired from Infocenter /timezones route (Windows time zones) or use a IANA time-zome code in order to get data with desired time offset.

The default timezone is UTC

Number formatting: CH

B2B Marketplace data is not translated, it is stored in the current language of the request (Accept-Language header).

This current language is stored in the order and is used to generate E-Mails and tickets.


Last update: May 25, 2021 07:43:36