openapi: 3.0.1
info:
  title: TapConnect
  description: >-
    Welcome to the TapConnect Issuing API documentation. These pages describe the endpoints available within TapConnect. Please note that for historical reasons, Date/times are always in the "Europe/Amsterdam" timezone. The endpoints in this document are grouped as follows:
      
      - **Export endpoints**: Export related endpoints return information about events related to tickets that have been issued. This can be used for Business Intelligence purposes or for financial record keeping.
      - **Product endpoints**: Product related endpoints return information about products that are available to you as a sales partner and the details of each of these products.
      - **Ticket endpoints**: Ticket related endpoints allow you to manage tickets throughout their lifecycle. This includes ticket creation, retrieving ticket information, or retrieving the barcode for a ticket.
      - **Journey endpoints**: Used to calculate the price of a journey and to issue a ticket for that journey using the external fare calculation engine.

    For more information on TapConnect please visit [https://tapconnect.io](https://tapconnect.io) or [https://documentation.tapconnect.io](https://documentation.tapconnect.io).
  version: '1.0'
servers:
  - url: https://services.acc.api.htm.nl/tapconnect/1.0
tags:
  - name: Export
    description: >-
      Export data that can be used to generate reports about issued tickets
      and related information
paths:
  /v5/ticket-events-export:
    get:
      summary: Elastic Search ticket events export
      description: "Exports ticket events data from Elastic Search.\n\nBoth parameters\
        \ are a string, and they have to represent a date. Consider the list of valid\
        \ formats below:\n1. 2021 - searches for all events in a year\n2. 2021-02\
        \ - searches for all events in a month\n3. 2021-02-02 - searches for all events\
        \ in a day\n4. 2021-02-02T12 - searches for all events in a specific hour\n\
        5. 2021-02-02T12:00 - searches for all events in a specific minute\n6. 2021-02-02T12:00:00\
        \ - searches for all events in a specific second\n\nIf an error occur, the\
        \ last element returned will be a message with \"An error occurred on Elasticsearch\"\
        \ and it \nmeans that not all the results are returned.\n_Keep in mind that\
        \ the above timestamps would also be accepted as Zulu: 2021-02-02T11:00:00Z\
        \ (winter time)_\n"
      parameters:
      - explode: true
        in: query
        name: start
        required: true
        description: The date to be considered as the interval starting date
        schema:
          example: 2021-02-01T00:00:00
          type: string      
        style: form
      - explode: true
        in: query
        name: end
        required: true
        description: The date to be considered as the interval ending date
        schema:
          example: 2021-02-02T00:00:00
          type: string
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v5_ticket_events_export_response'
          description: Returns a JSON chunked array of ticket events exported from elastic search.
        "400":
          description: |
            The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.
        "401":
          description: |
            Unauthorized call, you are not authorized to call this endpoint with the api key provided in the Authorization header. Please verify that your api key is correct and/or if you are authorized to call this endpoint.
        "403":
          description: |
            Unauthorized call, you are not authorized to call this endpoint with the api key provided in the Authorization header. Please verify that your api key is correct and/or if you are authorized to call this endpoint.
        "404":
          description: |
            The requested URL does not exist, or the requested object was not found.
        "406":
          description: |
            The request was not accepted by the server. The body of the response will contain information about the problem.
      tags:
      - Export
components:
  schemas:
    v5_ticket_events_export_response:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/ActivateTicketEvent'
        - $ref: '#/components/schemas/CreateBarcodeEvent'
        - $ref: '#/components/schemas/CreateTicketEvent'
        - $ref: '#/components/schemas/TapEvent'
        - $ref: '#/components/schemas/InspectTicketEvent'
        - $ref: '#/components/schemas/NotifyEvent'
    ActivateTicketEvent:
      properties:
        eventId:
          example: 1
          type: number
        eventType:
          example: ACTIVATE_TICKET
          type: string
        occurredAt:
          example: 2021-06-07T08:42:00.791992000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:00.791992000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        ticketId:
          example: hkbu3415fbidswd803nfdg7
          type: string
        validityStart:
          example: 2021-06-06T22:00:00.000000000Z
          type: string
        validityEnd:
          example: 2021-06-07T23:40:00.000000000Z
          type: string
        validityType:
          example: FIXED
          type: string
    CreateBarcodeEvent:
      properties:
        eventId:
          example: 2
          type: number
        eventType:
          example: CREATE_BARCODE
          type: string
        occurredAt:
          example: 2021-06-07T08:42:01.629279000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:01.629279000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        ticketId:
          example: 2huCpR99LHjGfiq8ZJoF
          type: string
        barcodeSignatureKeyId:
          example: TCT07
          type: string
        barcodeValidityStart:
          example: 2021-06-06T22:00:00.000000000Z
          type: string
        barcodeValidityEnd:
          example: 2021-06-07T23:40:00.000000000Z
          type: string
    CreateTicketEvent:
      properties:
        eventId:
          example: 0
          type: number
        eventType:
          example: CREATE_TICKET
          type: string
        occurredAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        reportedAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        ticketId:
          example: 344BEuHcFkEChOPm06sY
          type: string
        serviceId:
          example: HTM-0987-7477-0993
          type: string
        productName:
          example: HTM Kinder Dagkaart
          type: string
        productCode:
          example: "303"
          type: string
        productValidityPeriodUnit:
          example: "DAYS"
          type: string
        productValidityPeriod:
          example: 1
          type: number
        lifespanStart:
          example: 2021-06-07
          type: string
        lifespanEnd:
          example: 2021-06-08
          type: string
        language:
          example: NL
          type: string
        salesChannelId:
          example: "9999"
          type: string
        salesChannelName:
          example: HTM App
          type: string
        startStation:
          example: Haarlem
          type: string
        endStation:
          example: Leiden Centraal
          type: string
        barcodeType:
          example: UIC
          type: string
        validityType:
          example: FIXED
          type: string
        refundable:
          example: true
          type: boolean
        priceInCents:
          example: 150,
          type: number
        numberOfAdults:
          example: 1
          type: number
        numberOfChildren:
          example: 0
          type: number
        roundToBusinessDay:
          example: true
          type: boolean
        modalities:
          example: ["BUS", "TRAM"]
          type: array
          items:
            example: BUS
            type: string
    TapEvent:
      properties:
        eventId:
          example: 5
          type: number
        eventType:
          example: TAP
          type: string
        occurredAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        validationAction:
          example: CHECK_OUT
          type: string
        validationResult:
          example: Approved
          type: string
        tapId:
          example: a9aea0ae-52de-42cd-a2f1-93b80d9af389
          type: string
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        ticketId:
          example: hkbu3415fbidswd803nfdg7
          type: string
        modality:
          example: BUS
          type: string
        line:
          example: "25"
          type: string
        trip:
          example: "240"
          type: string
        vehicle:
          example: "1512"
          type: string
        deviceId:
          example: "13513A"
          type: string
        deviceType:
          example: VBS
          type: string
        lastStopId:
          example: "3409"
          type: string
        lastStopName:
          example: Gramsbergenlaan
          type: string
        nextStopId:
          example: "3409"
          type: string
        nextStopName:
          example: Gramsbergenlaan
          type: string
        location:
          type: object
          properties:
            lat:
              example: 52.00089453333333
              type: number
            lon:
              example: 4.004570666666667
              type: number
    InspectTicketEvent:
      properties:
        eventId:
          example: 3
          type: number
        eventType:
          example: INSPECT_TICKET
          type: string
        occurredAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        ticketId:
          example: uv1hzvrRd7Xd1Fs9vTxi
          type: string
        modality:
          example: BUS
          type: string
        deviceId:
          example: 6959bd00eaec8e68
          type: string
        deviceType:
          example: IBS
          type: string
        validationResult:
          example: Approved
          type: string
    NotifyEvent:
      properties:
        eventId:
          example: 1185
          type: number
        eventType:
          example: NOTIFY
          type: string
        occurredAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        receivedAt:
          example: 2021-06-07T08:42:00.790992000Z
          type: string
        timeToDie:
          example: 2445836980
          type: number
        tapId:
          example: a9aea0ae-52de-42cd-a2f1-93b80d9af389
          type: string
        sequence:
          example: 2
          type: number
        tapResponseTimeMillis:
          example: 402
          type: number
        validationAction:
          example: CHECK_OUT
          type: string
        validationMethod:
          example: ONLINE
          type: string
        validationResult:
          example: Approved
          type: string
        operators:
          items:
            example: HTM
            type: string
          type: array
        createdBy:
          example: HTM
          type: string
        definedBy:
          example: HTM
          type: string
        modality:
          example: TRAM
          type: string
        line:
          example: "3"
          type: string
        trip:
          example: "692"
          type: string
        vehicle:
          example: "4058"
          type: string
        deviceId:
          example: "13A886"
          type: string
        deviceType:
          example: VBS
          type: string
        lastStopId:
          example: "2005"
          type: string
        lastStopName:
          example: Fahrenheitstraat
          type: string
        nextStopId:
          example: "2011"
          type: string
        nextStopName:
          example: Valkenbosplein
          type: string
        ticketId:
          example: hkbu3415fbidswd803nfdg7
          type: string
        location:
          type: object
          properties:
            lat:
              example: 52.001300283333336
              type: number
            lon:
              example: 4.004586633333333
              type: number