publiq Card Systems API

openapi: 3.2.0
info:
  title: Publiq Card Systems 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 Card Systems 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: Card Systems
paths:
  /card-systems:
    get:
      x-internal: false
      summary: Search card systems
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardSystemsPaginatedCollection'
              examples:
                Example:
                  value:
                    totalItems: 0
                    member:
                    - 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
                      cardlessRegistrationType: ALL
        '400':
          description: 'Bad Request. Error type:


            https://api.publiq.be/probs/uitpas/postal-code-required

            https://api.publiq.be/probs/uitpas/invalid-postal-code

            * https://api.publiq.be/probs/url/query-limit-exceeded'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Error type:


            https://api.publiq.be/probs/url/not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-card-systems
      description: 'Search card systems.


        This caller of this method, identified by client identification, client access token or user access token, does not require any permissions.'
      parameters:
      - schema:
          type: boolean
          default: true
        in: query
        name: permanent
        description: Include only permanent (`true`) card systems or temporary (`false`) card systems.
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      - schema:
          type: array
          items:
            type: string
        in: query
        name: city
        description: Search card systems by city name. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city
        style: form
        explode: true
      - schema:
          type: array
          items:
            type: string
        in: query
        name: postalCode
        description: Search card systems by postal code. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city
        style: form
        explode: true
      - schema:
          type: string
        in: query
        name: sort
        description: 'Sorts the cardsystems in a specific order. Possible values are: `name`, `postalCode`. By default the sort uses ascending order. Descending order can be specified by including a `-` sign before the field that needs to be ordered descending. e.g. use `-name` to sort on name descending. `postalCode` sort will geographically sort based on the query param `postalCodeSort`.'
      - schema:
          type: string
        in: query
        name: postalCodeSort
        description: The postalCode that will be used by `sort=postalCode` as its geographic center. If `sort` is not `postalCode` this parameter is ignored. If `sort` is `postalCode`, this parameter is mandatory.
      tags:
      - Card Systems
      security:
      - CLIENT_IDENTIFICATION: []
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /card-systems/{cardSystemId}:
    parameters:
    - schema:
        type: integer
      name: cardSystemId
      in: path
      required: true
      description: The ID of the requested card system
    get:
      x-internal: false
      summary: Retrieve card system
      responses:
        '200':
          description: Details of the requested card system.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardSystem'
              examples:
                Example:
                  value:
                    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
                    cardlessRegistrationType: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


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


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-cardsystems-cardsystemid
      security:
      - CLIENT_IDENTIFICATION: []
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      description: 'Retrieve card system by ID.


        This caller of this method, identified by client identification, client access token or user access token, does not require any permissions.'
      tags:
      - Card Systems
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /card-systems/{cardSystemId}/social-tariff-settings:
    parameters:
    - schema:
        type: integer
      name: cardSystemId
      in: path
      required: true
      description: The ID of the requested card system
    get:
      x-internal: false
      summary: Retrieve social tariff settings for card system
      responses:
        '200':
          description: Social tariff settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardSystemSocialTariffSettings'
              examples:
                Example:
                  value:
                    postalCode: '9000'
                    allowsCardlessRegistration: true
        '400':
          description: 'Bad Request. Possible error types:


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

            * https://api.publiq.be/probs/uitpas/postal-code-not-in-card-system'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


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


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-cardsystems-cardsystemid-social-tariff-settings
      security:
      - CLIENT_IDENTIFICATION: []
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      description: '> **Deprecated:** use GET /cardsystems/{cardSystemId}/city-settings instead.


        Retrieve social tariff settings specific for this card system and the given postal code.


        This caller of this method, identified by client identification, client access token or user access token, does not require any permissions.'
      tags:
      - Card Systems
      parameters:
      - schema:
          type: string
        in: query
        name: postalCode
        description: Postal code of the passholder who is being registered. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city
        required: true
      deprecated: true
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /card-systems/{cardSystemId}/city-settings:
    parameters:
    - schema:
        type: integer
      name: cardSystemId
      in: path
      required: true
      description: The ID of the requested card system
    get:
      x-internal: false
      summary: Retrieve city settings for card system
      responses:
        '200':
          description: City specific settings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CardSystemCitySettings'
              examples:
                Example:
                  value:
                  - city: GENT
                    allowsCardlessRegistration: true
                    contactEmail: uitpas-gent@example.com
                  - city: MERELBEKE-MELLE
                    allowsCardlessRegistration: true
                    contactEmail: uitpas-merelbeke-melle@example.com
        '400':
          description: 'Bad Request. Possible error types:


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

            * https://api.publiq.be/probs/uitpas/postal-code-not-in-card-system'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


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


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-cardsystems-cardsystemid-city-settings
      security:
      - CLIENT_IDENTIFICATION: []
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      description: 'Retrieve city specific settings for this card system.


        This caller of this method, identified by client identification, client access token or user access token, does not require any permissions.'
      tags:
      - Card Systems
      parameters:
      - schema:
          type: array
          items:
            type: string
        in: query
        name: postalCode
        description: Filter city setting to the city of this postal code. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /card-systems/{cardSystemId}/membership-prices:
    parameters:
    - schema:
        type: integer
      name: cardSystemId
      in: path
      required: true
      description: The ID of the card system
    get:
      summary: Retrieve membership prices for a card system
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MembershipPrice'
              examples:
                Example:
                  value:
                  - price: 3
                    label: UiTPAS inwoners +18 jaar
                    description: Volwassenen die binnen de regio wonen, betalen 3 euro voor hun UiTPAS
                  - price: 0
                    label: UiTPAS inwoners -18 jaar
                    description: Kinderen die binnen de regio wonen krijgen een gratis UiTPAS
                  - price: 5
                    label: UiTPAS niet-inwoners +18 jaar
                    description: Volwassenen die buiten de regio wonen, betalen 5 euro voor hun UiTPAS
                  - price: 2
                    label: UiTPAS niet-inwoners -18 jaar
                    description: Kinderen die buiten de regio wonen, betalen 2 euro voor hun UiTPAS
                  - price: 1
                    label: UiTPAS Kansenpas
                    description: Kansenpashouders betalen 1 euro voor hun UiTPAS
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


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


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-card-systems-cardsystemid-membership-prices
      description: 'Retrieve all membership prices by card type for a card system. The result will contain all prices for the cardsystem, which is primarily useful to display to a an anonymous user. To retrieve the price for an individual passholder, you can use GET /passholders/membership-prices/{cardSystemId} (more details like social tariff, date of birth and residence are required) or GET /passholders/{passholderId}/membership-prices/{cardSystemId} (if the passholder already exists).


        This caller of this method, identified by client identification, client access token or user access token, does not require any permissions.'
      parameters:
      - schema:
          type: string
          enum:
          - DIGITAL
          - NFC_CARD
        in: query
        name: cardType
        description: Type of the card
        required: true
      security:
      - CLIENT_IDENTIFICATION: []
      - USER_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      tags:
      - Card Systems
    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
    MembershipPrice:
      type: object
      title: MembershipPrice
      description: 'The MembershipPrice describes the price an UiTPAS membership in a specific cardsystem for a new or existing passholder.  '
      x-internal: false
      example:
        price: 5
        label: UiTPAS +18 jaar
        description: Volwassenen die binnen de regio wonen, betalen 5 euro voor hun UiTPAS
      x-tags:
      - Models
      properties:
        price:
          description: Price for the card system membership, in euro.
          type: number
        label:
          type: string
          x-stoplight:
            id: pw5cjsq3l7ory
          description: Label of the price that can be displayed to the end-user.
        description:
          type: string
          x-stoplight:
            id: 10d0zi5ldphwj
          description: Description of the price that can be displayed to the end-user.
      required:
      - price
      - label
      - description
    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
    CardSystemsPaginatedCollection:
      title: CardSystemsPaginatedCollection
      type: object
      x-tags:
      - Models
      description: Paginated response object for card systems
      properties:
        totalItems:
          type: integer
          description: Total number of card system results (can be more than the amount of results in the response).
        member:
          type: array
          description: List of card system results for this specific (paginated) request.
          items:
            $ref: '#/components/schemas/CardSystem'
    CardSystemSocialTariffSettings:
      title: CardSystemSocialTariffSettings
      x-stoplight:
        id: gr3fmeyv787ao
      type: object
      description: CardSystemSocialTariffSettings
      properties:
        postalCode:
          type: string
          x-stoplight:
            id: 0xm0rbvq3kdcb
          description: Postal code
        allowsCardlessRegistration:
          type: boolean
          x-stoplight:
            id: 9q12nus6hxclk
          description: true if social tariff registration is allowed for passholder with `postalCode`.
      required:
      - postalCode
      - allowsCardlessRegistration
    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
    CardSystemCitySettings:
      title: CardSystemCitySettings
      x-stoplight:
        id: opeie5n4zc8p3
      type: object
      description: CardSystemCitySettings
      properties:
        city:
          type: string
          x-stoplight:
            id: 0xm0rbvq3kdcb
          description: These settings apply to this city.
        allowsCardlessRegistration:
          type: boolean
          x-stoplight:
            id: 9q12nus6hxclk
          description: true if social tariff registration is allowed for passholder with `postalCode`.
        contactEmail:
          type: string
          x-stoplight:
            id: jhikn8amk44e6
          description: Contact email of this card system in the given city.
      required:
      - city
      - allowsCardlessRegistration
      - contactEmail
    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
  parameters:
    start:
      schema:
        type: integer
        minimum: 0
        default: 0
      in: query
      name: start
      description: Position to start returning results from. When set to `0` the results starting from the very first position will be returned. When set to for example `10` the results 0-9 will be skipped and the ones starting from position 10 will be returned. Can be used in combination with `limit` for pagination.
    limit:
      schema:
        type: integer
        default: 20
        minimum: 0
      in: query
      name: limit
      description: 'Maximum amount of results to return. Can be used in combination with `start` for pagination. **Important**: the maximum value for `limit` is `500`. Exceeding this value will result in an error.'
  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