openapi: 3.2.0
info:
  title: Publiq Kiosk devices 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 Kiosk devices 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: Kiosk devices
paths:
  /kiosk-devices/setup:
    parameters: []
    put:
      summary: Setup new kiosk device
      operationId: put-kiosks-setup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskDevice'
              examples:
                Example:
                  value:
                    id: db385941-ece7-493d-8c4b-4320c4849646
                    name: CID-PPT-001
                    deviceId: ebee0a27-2dba-4231-aaae-15077884fa75
                    organizers:
                    - id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
                      name: CC De Schakel
                    cardSystem:
                      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
                    releaseTrack: stable
        '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/kiosk-not-found

            * https://api.publiq.be/probs/uitpas/kiosk-already-configured

            * https://api.publiq.be/probs/uitpas/kiosk-device-already-in-use'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: 'Configure new kiosk device by looking it up by name and storing the provided device id. After this endpoint has been invoked, the other kiosk APIs can be used with the newly configured device id as `x-custom-token`.


        In case no kiosk is found or the kiosk was already setup an error is returned:


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

        * https://api.publiq.be/probs/uitpas/kiosk-already-configured


        The **configuration code** of the device must be specicied in the `x-custom-token` header. This endpoint is rate limited to prevent abuse.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      security:
      - CUSTOM_TOKEN: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KioskDeviceSetup'
            examples:
              Example:
                value:
                  name: CID-PPT-001
                  deviceId: ebee0a27-2dba-4231-aaae-15077884fa75
        description: Kiosk Setup
      tags:
      - Kiosk devices
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /kiosk-devices:
    parameters: []
    get:
      summary: Retrieve kiosk
      tags:
      - Kiosk devices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskDevice'
              examples:
                Example:
                  value:
                    id: db385941-ece7-493d-8c4b-4320c4849646
                    name: CID-PPT-001
                    deviceId: ebee0a27-2dba-4231-aaae-15077884fa75
                    organizers:
                    - id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
                      name: CC De Schakel
                    cardSystem:
                      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
                    releaseTrack: stable
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-kiosk-devices
      description: 'Retrieve current kiosk.


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      security:
      - CUSTOM_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /kiosk-devices/events:
    parameters: []
    get:
      summary: Retrieve configured event
      tags:
      - Kiosk devices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskDeviceEvent'
              examples:
                Example:
                  value:
                    checkinPoints: 1
                    event:
                      id: c7cf303a-8d92-4427-84e3-0cb508f7e4b6
                      title: Jeugdcentrum De Kouter
                    checkinCode: LGIWNWB
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-kiosks-event
      description: 'Retrieve the configured event of the kiosk.


        This is a configuration endpoint, if you need to retrieve the **current** event, please use `GET /kiosk-devices/checkins`


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      security:
      - CUSTOM_TOKEN: []
    put:
      summary: Configure event
      operationId: put-kiosks-events
      responses:
        '204':
          description: Updated. No Content
        '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/event-not-found

            * https://api.publiq.be/probs/uitpas/event-not-acceptable'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: 'Update the current event of the kiosk.


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      tags:
      - Kiosk devices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KioskDeviceEventRequest'
            examples:
              Example:
                value:
                  id: c7cf303a-8d92-4427-84e3-0cb508f7e4b6
        description: Event
      security:
      - CUSTOM_TOKEN: []
    delete:
      summary: Delete configured event
      operationId: delete-kiosks-events
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: 'Delete configured event


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      tags:
      - Kiosk devices
      security:
      - CUSTOM_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /kiosk-devices/checkins:
    parameters: []
    post:
      summary: Checkin passholder via kiosk
      operationId: post-kiosks-checkin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskDeviceCheckinResponse'
              examples:
                Example:
                  value:
                    newPoints: 1
                    totalPoints: 23
        '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/card-blocked

            * https://api.publiq.be/probs/uitpas/checkin-not-allowed

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

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

            * https://api.publiq.be/probs/uitpas/maximum-reached'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Kiosk devices
      description: 'Checkin a passholder with the given NFC chipnumber at the kiosk.


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      security:
      - CUSTOM_TOKEN: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KioskDeviceCheckinRequest'
            examples:
              Example:
                value:
                  chipNumber: 042F51B2712380
        description: Kiosk checkin request
    get:
      summary: Retrieve the current checkin event
      operationId: get-kiosks-checkins
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskDeviceEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Retrieve the current event of the kiosk. When returned, checkin on this kiosk and event is allowed.


        The following logic is being used to determine the current checkin event:

        * is the event configured and is checkin currently allowed for that event? then use this event.

        * otherwise, the most suitable event is autodetected based on the organizers and locations of the kiosk.


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      tags:
      - Kiosk devices
      security:
      - CUSTOM_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /kiosk-devices/chip-numbers/{chipNumber}:
    parameters:
    - schema:
        type: string
      name: chipNumber
      in: path
      required: true
      description: Hexadecimal notation of the chip number of an individual UiTPAS card.
    get:
      summary: Retrieve total points of a passholder by chip number
      operationId: get-kiosks-chip-numbers-chipNumber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KioskPass'
              examples:
                Example 1:
                  value:
                    totalPoints: 20
        '400':
          description: 'Bad request. Possible error types:


            * https://api.publiq.be/probs/uitpas/card-blocked

            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Retrieve total points of a passholder by chip number.


        The device id of the kiosk must be specicied in the `x-custom-token` header.


        > **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.'
      tags:
      - Kiosk devices
      security:
      - 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:
    KioskDevice:
      title: KioskDevice
      x-stoplight:
        id: hh3kfd7lxxds9
      type: object
      description: Representation of the kiosk entity
      x-examples:
        Example:
          id: db385941-ece7-493d-8c4b-4320c4849646
          name: CID-PPT-001
          deviceId: ebee0a27-2dba-4231-aaae-15077884fa75
          organizers:
          - id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
            name: CC De Schakel
          cardSystem:
            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
          releaseTrack: stable
      properties:
        id:
          type: string
          description: ID of the kiosk. This field is always available in responses.
          readOnly: true
        name:
          type: string
          x-stoplight:
            id: g2vr54zw4cq7o
          description: Name of the kiosk. This field is always available in responses.
          readOnly: true
        organizers:
          type: array
          description: Organizers linked to this kiosk
          items:
            $ref: '#/components/schemas/Organizer'
        locations:
          type: array
          x-stoplight:
            id: m988ozti2dcka
          description: Locations linked to this kiosk
          items:
            $ref: '#/components/schemas/Location'
        deviceId:
          type: string
          x-stoplight:
            id: 7q3dpudb6iaay
          description: Device ID linked to this kiosk.
        cardSystem:
          $ref: '#/components/schemas/CardSystem'
        releaseTrack:
          type: string
          x-stoplight:
            id: af2qu41h1ry0m
          description: Release track of this kiosk
          enum:
          - beta
          - stable
      required:
      - id
      - name
      - deviceId
      - cardSystem
      - releaseTrack
    Error:
      $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json
    KioskDeviceEventRequest:
      title: KioskDeviceEventRequest
      x-stoplight:
        id: 2bfdjhsqwwxj1
      type: object
      description: Model to configure the kiosk event
      properties:
        id:
          type: string
          description: ID of the event
      required:
      - id
    KioskDeviceSetup:
      title: KioskDeviceSetup
      x-stoplight:
        id: ylj4q1p2eeisl
      type: object
      properties:
        name:
          type: string
          x-stoplight:
            id: xs87oo7o9eqfy
          description: Name of the KIOSK
        deviceId:
          type: string
          x-stoplight:
            id: phadvfcafaeuc
          description: Device ID of the kiosk
      required:
      - name
      - deviceId
    KioskDeviceCheckinResponse:
      title: KioskDeviceCheckinResponse
      x-stoplight:
        id: a0b3354689f18
      type: object
      description: Checkin via kiosk response
      properties:
        newPoints:
          type: integer
          description: New points as a result of this checkin
          x-stoplight:
            id: 9xh8ib4eacnsd
        totalPoints:
          type: integer
          description: Total points of the passholder after this checkin
      required:
      - newPoints
      - totalPoints
    KioskDeviceCheckinRequest:
      title: KioskDeviceCheckinRequest
      x-stoplight:
        id: p017ejlluigiv
      type: object
      properties:
        chipNumber:
          type: string
          x-stoplight:
            id: upndvphy3uppq
          description: Chipnumber of the passholder to checkin
      required:
      - chipNumber
    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
    KioskPass:
      title: KioskPass
      x-stoplight:
        id: pia2mamgrb6kc
      type: object
      description: Pass information
      properties:
        totalPoints:
          type: integer
          x-stoplight:
            id: g914t3kiofl8f
          description: Total points of the passholder
      required:
      - totalPoints
    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
    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
    Location:
      title: Location
      x-stoplight:
        id: jsek0i5fkc5ai
      type: object
      description: Location model
      properties:
        id:
          type: string
          description: ID of the location
        name:
          type: string
          x-stoplight:
            id: xqbdyntqozql8
          description: Name of the location
      required:
      - id
      - name
    KioskDeviceEvent:
      title: KioskDeviceEvent
      x-stoplight:
        id: y5atjfuzrvep1
      type: object
      description: Event model used in Kiosk APIs
      properties:
        checkinPoints:
          type: integer
          x-stoplight:
            id: b416vifd5i684
          description: Points earned when passholds checks in
        event:
          type: object
          x-stoplight:
            id: 345z9zuzxe547
          description: Current event of the kiosk.
          required:
          - id
          - title
          properties:
            id:
              type: string
              x-stoplight:
                id: 6b10ruuepsrjo
              description: ID of the event
            title:
              type: string
              x-stoplight:
                id: dxavbqgc8aysl
              description: Title of the event
        checkinCode:
          type: string
          x-stoplight:
            id: orc9gdhisu1ya
          description: Checkin code for the event
      required:
      - checkinPoints
      - event
      - checkinCode
    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