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