openapi: 3.2.0
info:
  title: Publiq External cards API
  version: '1.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 External cards across 2 of this provider''s published API definitions: museumpassmusees-partner-api.json, publiq-museumpassmusees-partner-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://partner-api-test.museumpassmusees.be
  description: Testing
- url: https://partner-api.museumpassmusees.be
  description: Production
tags:
- name: External cards
paths:
  /external-cards/{type}/{identification}:
    parameters:
    - schema:
        type: string
        enum:
        - uitpas
        - akaart
        - article27
      name: type
      in: path
      required: true
      description: The type of external card
    - schema:
        type: string
      name: identification
      in: path
      required: true
      description: The identification (e.g. card number) of the external card
    get:
      summary: Look up external card
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  visit:
                    type: object
                    description: Visit information for the external card.
                    required:
                    - allowed
                    properties:
                      allowed:
                        type: boolean
                        description: Indicates whether a visit with the external card is allowed or not.
                required:
                - visit
              examples: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


            * https://api.publiq.be/probs/url/not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'Service Unavailable.


            The `Retry-After` HTTP Header might include a hint when a retry of this request can be attempted.


            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-external-cards-type-identification
      description: 'Retrieve visit allowed information related to an external card.


        ## Permissions


        The caller of this request must have the `visit registrar` role.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      parameters: []
      tags:
      - External cards
    servers:
    - url: https://partner-api-test.museumpassmusees.be
      description: Testing
    - url: https://partner-api.museumpassmusees.be
      description: Production
  /external-cards/{type}/{identification}/visits:
    parameters:
    - schema:
        type: string
        enum:
        - uitpas
        - akaart
        - article27
      name: type
      in: path
      required: true
      description: The type of external card
    - schema:
        type: string
      name: identification
      in: path
      required: true
      description: The identification (e.g. card number) of the external card
    post:
      summary: Register a museum visit for an external card
      operationId: post-external-cards-type-identification-visits
      responses:
        '201':
          description: External card visit registered.
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/museumpass/museum-not-active'
          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/url/not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'Service Unavailable.


            The `Retry-After` HTTP Header might include a hint when a retry of this request can be attempted.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Registers a visit of an axternal card at your museum (determined by the client access token used).


        To check if this card is allowed to visit, look up their information using `GET /external-cards/{type}/{identification}`. The response to that request will indicate if the passholder may visit your museum.


        If the external card may not visit your museum and you still try to register a visit for them, the server will return a `403 Forbidden` error response.


        **Note**: A POST body is not required for this endpoint. All information is derived from the path.


        ## Permissions


        The caller of this request must have the `visit registrar` role.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      tags:
      - External cards
    servers:
    - url: https://partner-api-test.museumpassmusees.be
      description: Testing
    - url: https://partner-api.museumpassmusees.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'
          examples:
            Example:
              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'
          examples:
            Example:
              value:
                type: https://api.publiq.be/probs/auth/forbidden
                title: Forbidden
                status: 403
                detail: user must be admin of organizer abcd1234
  schemas:
    Error:
      $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json
      x-internal: true
    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: true
  securitySchemes:
    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.
x-refined-from:
- museumpassmusees-partner-api.json
- publiq-museumpassmusees-partner-openapi.yml