Merge pull request 'TapConnect V5 ticket events export schema reverse-engineered from real data' (#43) from feature/OVPAY-2345-TapConnect-Elastic into develop

Reviewed-on: #43

src/openapi/tapconnect/tapconnect.yaml

@@ -0,0 +1,477 @@
+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