publiq Orders API

openapi: 3.2.0
info:
  title: Publiq Orders API
  version: '4.0'
  contact:
    name: publiq helpdesk
    email: technical-support@publiq.be
    url: https://docs.publiq.be
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Orders across 2 of this provider''s published API definitions: uitpas-uitpas.json, publiq-uitpas-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-test.uitpas.be
  description: Testing
- url: https://api.uitpas.be
  description: Production
tags:
- name: Orders
paths:
  /orders:
    post:
      summary: Create online order
      operationId: post-orders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                Example pending payment:
                  value:
                    id: '123456789'
                    status: PENDING_PAYMENT
                    paymentUrl: https://payment-url.com
                    email: example@example.org
                    totalPrice: 10
                    customToken: U742hZr^FkBQfxqQtz7Y%tt@q%SpoEkR52Q$2heET#G*S&N88CM64&E&H$%Sonop%adVxybPziNYm$NL%%fkKhQwQKpkoSmb8vWVmZ58VPd@87Xa@@a%hPQP&8
                    mainPassholderRegistration:
                      name: Peeters
                      firstName: Marc
                      inszNumber: 00000009007
                      email: marc.peeters@example.com
                      dateOfBirth: '2000-01-01'
                      registrationOrganizer:
                        id: abc12345
                      address:
                        street: Grote markt 12
                        postalCode: '9300'
                        city: Aalst
                        country: be
                      optInPreferences:
                        serviceMails: true
                        infoMails: true
                        milestoneMails: true
                        sms: false
                        post: true
                      nationality: Belg
                      legalTermsPaper: false
                      legalTermsDigital: true
                      parentalConsent: false
                      registrationCardSystemId: 1
                Example pending uitid connect:
                  value:
                    id: '123456789'
                    status: PENDING_UITID_CONNECT
                    uitidAuthUrl: https://uitid.be/auth
                    email: example@example.org
                    totalPrice: 10
                    registrationToken: '123456789'
                    mainPassholderRegistration:
                      name: Peeters
                      firstName: Marc
                      inszNumber: 00000009007
                      email: marc.peeters@example.com
                      dateOfBirth: '2000-01-01'
                      registrationOrganizer:
                        id: abc12345
                      address:
                        street: Grote markt 12
                        postalCode: '9300'
                        city: Aalst
                        country: be
                      optInPreferences:
                        serviceMails: true
                        infoMails: true
                        milestoneMails: true
                        sms: false
                        post: true
                      nationality: Belg
                      legalTermsPaper: false
                      legalTermsDigital: true
                      parentalConsent: false
                      registrationCardSystemId: 1
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/body/missing

            * https://api.publiq.be/probs/body/invalid-syntax

            * https://api.publiq.be/probs/body/invalid-data

            * https://api.publiq.be/probs/uitpas/organizer-not-found

            * https://api.publiq.be/probs/uitpas/cardsystem-not-found

            * https://api.publiq.be/probs/uitpas/invalid-city

            * https://api.publiq.be/probs/uitpas/invalid-insz-number

            * https://api.publiq.be/probs/uitpas/email-already-used

            * https://api.publiq.be/probs/uitpas/invalid-social-tariff-validation-token


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      - CLIENT_IDENTIFICATION: []
      description: 'Create an online order for one or more passholders.


        This caller of this method, identified by client identification, client access token or user access token, must have ORDERS_CREATE permission.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Example:
                value:
                  mainPassholderRegistration:
                    name: Peeters
                    firstName: Marc
                    inszNumber: 00000009007
                    email: marc.peeters@example.com
                    dateOfBirth: '2000-01-01'
                    registrationOrganizer:
                      id: abc12345
                    address:
                      street: Grote markt 12
                      postalCode: '9300'
                      city: Aalst
                      country: be
                    optInPreferences:
                      serviceMails: true
                      infoMails: true
                      milestoneMails: true
                      sms: false
                      post: true
                    nationality: Belg
                    legalTermsPaper: false
                    legalTermsDigital: true
                    parentalConsent: false
                    registrationCardSystemId: 1
        description: Details of the new order to create.
      tags:
      - Orders
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /orders/{orderId}:
    parameters:
    - schema:
        type: string
      name: orderId
      in: path
      required: true
      description: ID of the order
    get:
      summary: Retrieve order
      operationId: get-orders-orderid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too Many Requests


            Possible error types:


            * https://api.publiq.be/probs/uitpas/rate-limited'
      description: 'Retrieve order by ID.


        The caller of this method, identified by client identification, client access token or user access token, must have ORDERS_READ permission.


        In case this order is retrieved using client identification, `mainPassholder` and `extraPassholders` are left out of the response.


        This endpoint is rate limited.'
      tags:
      - Orders
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      - CUSTOM_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Your request is missing the required credentials to authenticate. See the Authentication documentation for more info.


        * type: https://api.publiq.be/probs/auth/unauthorized

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Unauthorized:
              value:
                type: https://api.publiq.be/probs/auth/unauthorized
                title: Unauthorized
                status: 401
    Forbidden:
      description: 'Forbidden. Your request was successfully authenticated but you do not have permission to perform this particular request.


        * type: https://api.publiq.be/probs/auth/forbidden

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Forbidden:
              value:
                type: https://api.publiq.be/probs/auth/forbidden
                title: Forbidden
                status: 403
                detail: user must be admin of organiser abcd1234
  schemas:
    Error:
      $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json
    Order:
      type: object
      title: Order
      description: Order object
      properties:
        id:
          type: string
          x-stoplight:
            id: n9hihx4x3wa17
          description: ID of the order. This property is always present in responses.
          readOnly: true
        status:
          type: string
          x-stoplight:
            id: 6t5j0p21gcxwj
          enum:
          - PENDING_PAYMENT
          - PENDING_UITID_CONNECT
          - COMPLETED
          - CANCELLED
          description: Status of the order. This property is always present in responses.
          readOnly: true
        paymentUrl:
          type: string
          x-stoplight:
            id: bmo5ep7z3wbn2
          description: Payment URL (only when status is `PENDING_PAYMENT`)
          readOnly: true
        email:
          type: string
          x-stoplight:
            id: 9heoomg0mq75m
          description: Email of the orderer. This property is always present in responses.
          readOnly: true
        totalPrice:
          type: number
          x-stoplight:
            id: f198xd50mpxmg
          description: Total price of the order. This property is always present in responses.
          readOnly: true
        registrationToken:
          type: string
          x-stoplight:
            id: q1oexa53dyky7
          description: Optional registration token. If this order is `PENDING_UITID_CONNECT` this field is present to allow for easy UiTiD account linking.
          readOnly: true
        customToken:
          type: string
          description: Custom token that can be used for a limited number of time to request this order using `GET /orders/id` without any further authentication.
          readOnly: true
        mainPassholderRegistration:
          $ref: '#/components/schemas/PassholderRegistration'
        extraPassholderRegistrations:
          type: array
          description: Optional list of extra passholders in the order
          items:
            $ref: '#/components/schemas/PassholderRegistration'
        redirectUrlAfterPayment:
          type: string
          description: Where to redirect after payment. Extra query params `orderId` and `customToken` are added to this URL when used to redirect the user, so the receiving client can `GET` the latest status of the order.
          writeOnly: true
        redirectUrlAfterCancelPayment:
          type: string
          description: Where to redirect after payment is cancelled. Extra query params `orderId` and `customToken` are added to this URL when used to redirect the user, so the receiving client can `GET` the latest status of the order.
          writeOnly: true
      required:
      - mainPassholderRegistration
    City:
      title: City
      type: object
      x-tags:
      - Models
      example:
        postalCode: '9300'
        name: Aalst
      properties:
        postalCode:
          type: string
          description: Postalcode of the city
        name:
          type: string
          description: Name of the city
      required:
      - postalCode
      - name
    PassholderRegistration:
      title: PassholderRegistration
      type: object
      x-tags:
      - Models
      description: 'Registration request of a passholder, mainly used in the online order flow.


        A `PassholderRegistration` is not yet `Passholder` but one can be created (e.g. when the order is paid) using the information from the `PassholderRegistration`.'
      x-examples: {}
      properties:
        id:
          type: string
          description: ID of the PassholderRegistation. **Note:** This is not same as the later `Passholder` id. This field is always available in responses.
          readOnly: true
        name:
          type: string
          description: Last name of the passholder to register.
        firstName:
          type: string
          description: First name of the passholder to register.
        inszNumber:
          type: string
          description: Unique national (Belgian) INSZ number of an individual passholder.
        email:
          type: string
          description: Contact email address of the passholder to register
        creationDate:
          type: string
          format: date-time
          description: This field is always available in responses.
          readOnly: true
        dateOfBirth:
          type: string
          format: date
          description: Date that the passholder to register was born.
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
          - X
          description: Gender of the passholder to register.
        registrationOrganizer:
          $ref: '#/components/schemas/Organizer'
        address:
          type: object
          description: Address that the passholder to register lives at. Always present in responses. Passholders living outside of Belgium (usually near the border) will only have a `postalCode` and `city` in their address.
          required:
          - postalCode
          - city
          properties:
            street:
              type: string
              description: Street name, number and optional box number of the address.
            number:
              type: string
              description: House number. This field is deprecated and will be empty. The house number is part of the `street` property.
              deprecated: true
            box:
              type: string
              description: Postal box number. This field is deprecated and will be empty. The box number is part of the `street` property.
              deprecated: true
            postalCode:
              type: string
              description: Postal code of the municipality.
            city:
              type: string
              description: Human-readable name of the municipality.
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code.
        phoneNumber:
          type: string
          description: Phone number of the passholder to register, for example for SMS alerts.
        optInPreferences:
          type: object
          description: Permissions that the passholder has given to be contacted.
          properties:
            serviceMails:
              type: boolean
              description: Important information about the functionality of UiTPAS.
            milestoneMails:
              type: boolean
              description: Notification when you reach an important UiTPAS milestone, for example a specific amount of points or an exclusive reward becomes available to you.
            infoMails:
              type: boolean
              description: Rewards, actions and events selected specifically for the passholder based on their UiTPAS history.
            sms:
              type: boolean
              description: Free (sporadic) SMS messages with rewards, actions and events selected specifically for the passholder based on their UiTPAS history.
            post:
              type: boolean
              description: Sporadic post mail with information about UiTPAS. Will be sent to the passholder's postal address.
          required:
          - serviceMails
          - milestoneMails
          - infoMails
          - sms
          - post
        parentalConsent:
          type: boolean
          description: Set to true for under-aged passholder that have parental consent.
        legalTermsPaper:
          type: boolean
          description: Set to true for passholders that received legal terms on paper.
        legalTermsDigital:
          type: boolean
          description: Set to true for passholders that received legal terms digitally.
        registrationCardSystemId:
          type: integer
          description: Set to the id of the card system of which the passholder has to become a member.
        registrationVoucher:
          type: string
          description: Price reduction voucher.
        registrationSocialTariff:
          type: object
          description: Optional request for social tariff
          properties:
            requested:
              type: boolean
              description: '`true` if social tariff is requested for this registration. Always available in responses if `registrationSocialTariff` exists.'
              readOnly: true
            idToken:
              type: string
              description: The Social Tariff Validation ID token of the user. Use the [social tariff validation flow](/reference/uitpas.json/paths/~1social-tariff-validation~1start/get) to obtain such ID tokens. If specified, this token must be valid, contain `hasSocialTariff:true` and the identity fields must match the fields in this registration. In all other cases an error is returned.
              writeOnly: true
      required:
      - name
      - firstName
      - dateOfBirth
      - registrationOrganizer
      - address
    Organizer:
      title: Organizer
      type: object
      description: An organisation that partners with UiTPAS to provide discounts and/or rewards, and/or allows points to be collected at their events.
      x-tags:
      - Models
      properties:
        id:
          type: string
          description: Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)
        name:
          type: string
          description: Human-readable name of an UiTPAS organizer.
        cardSystems:
          type: array
          description: Card systems linked to this organizer
          items:
            $ref: '#/components/schemas/CardSystem'
        linkedLocationId:
          type: string
          description: ID of the location linked to this organizer.
          readOnly: true
        address:
          type: object
          description: Address of this organizer. This property is alway available in responses.
          required:
          - city
          properties:
            street:
              type: string
              description: Street address of this organizer
            postalCode:
              type: string
              description: Postal code of this organizer
            city:
              type: string
              description: City of this organizer
          readOnly: true
      required:
      - id
    CardSystem:
      title: CardSystem
      description: A region, usually one or multiple municipalities in Belgium, that uses UiTPAS and provides discounts and/or rewards. For example "Paspartoe" (Brussels), UiTPAS Leuven, UiTPAS Hasselt, UiTPAS Gent, and so on.
      type: object
      x-tags:
      - Models
      example:
        id: 1
        name: UiTPAS Dender
        branding:
          logo: https://www.uitpas.be/_nuxt/img/1351557.svg
          primaryColor: rgba(0,0,0,1.0)
          secondaryColor: rgba(97,166,14,1.0)
        links:
          website: https://www.uitpas.be
        cities:
        - postalCode: '9300'
          name: Aalst
        - postalCode: '9400'
          name: Ninove
        permanent: true
      properties:
        id:
          type: integer
          description: ID of the card system
        name:
          type: string
          description: Name of the card system. This field is always available in responses.
        branding:
          type: object
          description: Branding information of the card system
          properties:
            logo:
              type: string
              description: URL to the logo of the card system
            primaryColor:
              type: string
              description: Color code of the primary branding color.
            secondaryColor:
              type: string
              description: Color code of the secondary branding color.
        links:
          type: object
          description: Links of the card system
          properties:
            website:
              type: string
              description: URL of the website of the card system
        cities:
          type: array
          description: List of cities that are part of this card system
          items:
            $ref: '#/components/schemas/City'
        permanent:
          type: boolean
          description: Indicates whether this is a permanent card system
        allowsCardlessRegistration:
          type: boolean
          description: Indicates if cardless registration is enabled
        cardlessRegistrationType:
          type: string
          description: Indicates the types of online cardless registrations this cardsystem supports.
          enum:
          - ALL
          - REGULAR
          - SOCIALTARIFF
          - NONE
        socialTariffInfo:
          type: string
          description: Optional information about social tariff entitlement in this card system.
      required:
      - id
    Error_2:
      title: Error
      type: object
      description: RFC7807 error model for all publiq APIs.
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. Can be used to recognize specific errors in your application code by comparing the complete URI.
        title:
          type: string
          description: A short, human-readable summary of the problem type (for developers).
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: 'A human-readable explanation specific to this occurrence of the problem (for developers). '
        endUserMessage:
          type: object
          description: A human-readable explanation of the problem, specifically for end-users, in one or more languages. Typically available for domain errors, but not for errors caused by a technical issue in the integration (for example invalid JSON syntax in a request body). An `nl` value is always provided, other languages may be provided depending on the API and its intended audience. When this property is included, it is strongly encouraged to show this to the end-user.
          properties:
            nl:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in Dutch.
            fr:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in French.
            de:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in German.
            en:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in English.
          required:
          - nl
        schemaErrors:
          type: array
          description: A list of one or more schema validation errors (usually used for error type https://api.publiq.be/probs/body/invalid-data).
          items:
            type: object
            properties:
              jsonPointer:
                type: string
                format: json-pointer
                description: RFC6901 compliant pointer that indicates what property/value was invalid.
              error:
                type: string
                description: A human-readable (but often technical) reason why the property was invalid.
            required:
            - jsonPointer
            - error
      required:
      - type
      - title
      - status
      x-internal: false
  securitySchemes:
    USER_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A user access token, obtained by redirecting the end user to publiq's authorization server to login using the **Authorization Code OAuth Flow**. See the [authentication docs about user access tokens](https://docs.publiq.be/docs/authentication/methods/user-access-token) for more info.
    CLIENT_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A client access token, obtained by exchanging your client id and client secret for a token via an HTTP request to publiq's authorization server using the **Client Credentials OAuth Flow**. See the [authentication docs about client access tokens](https://docs.publiq.be/docs/authentication/methods/client-access-token) for more info.
    CLIENT_IDENTIFICATION:
      name: x-client-id
      type: apiKey
      in: header
    CUSTOM_TOKEN:
      name: x-custom-token
      type: apiKey
      in: header
x-refined-from:
- uitpas-uitpas.json
- publiq-uitpas-openapi.yml