From 0749e927dc2a2ff246614306f4f3b58954699ffa Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 5 Mar 2026 10:09:44 +0100 Subject: [PATCH 01/10] OVPAY-2473 - Added existing trip endpoints. --- src/openapi/customers/customers-trips.yaml | 677 +++++++++++++++++++++ 1 file changed, 677 insertions(+) create mode 100644 src/openapi/customers/customers-trips.yaml diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml new file mode 100644 index 0000000..00726bb --- /dev/null +++ b/src/openapi/customers/customers-trips.yaml @@ -0,0 +1,677 @@ +openapi: 3.0.1 +info: + title: ABTCustomers + version: '1.0' +servers: + - url: https://services.acc.api.htm.nl/abt/abtcustomers/1.0 +security: + - default: [] +paths: + /customers/tokens/{ovpayTokenId}/trips: + get: + tags: + - Customer self-service trips + summary: Get trips for a token + description: >- + Get the most recent trips for a given token ID, as long as this token is + bound to the profile (as derived from sub in given JWT) + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + required: true + style: simple + explode: false + schema: + type: string + - name: ovpayTokenId + in: path + required: true + style: simple + explode: false + schema: + type: integer + - name: dateTimeFrom + in: query + required: false + style: form + explode: false + schema: + type: string + - name: dateTimeUntil + in: query + required: false + style: form + explode: false + schema: + type: string + - name: organisationId + in: query + required: false + style: form + explode: false + schema: + type: string + - name: transportType + in: query + required: false + style: form + explode: false + schema: + type: string + - name: lineId + in: query + required: false + style: form + explode: false + schema: + type: string + - name: paymentMethod + in: query + required: false + style: form + explode: false + schema: + type: string + - name: productTemplateId + in: query + required: false + style: form + explode: false + schema: + type: string + - name: category + in: query + required: false + style: form + explode: false + schema: + type: string + - name: tripStatus + in: query + required: false + style: form + explode: false + schema: + type: string + - name: tripId + in: query + required: false + style: form + explode: false + schema: + type: string + - name: showSuperseedingTrips + in: query + required: false + style: form + explode: false + schema: + type: string + - name: organisationName + in: query + required: false + style: form + explode: false + schema: + type: string + - name: limit + in: query + required: false + style: form + explode: false + schema: + type: integer + - name: offset + in: query + required: false + style: form + explode: false + schema: + type: integer + responses: + '200': + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/getTokenTrips' + '400': + description: '400' + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + '401': + description: '401' + content: + application/json: + schema: + $ref: '#/components/schemas/401Response' + '403': + description: '403' + content: + application/json: + schema: + $ref: '#/components/schemas/403Response' + '404': + description: '404' + content: + application/json: + schema: + $ref: '#/components/schemas/404Response' + '500': + description: '500' + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' + security: + - default: [] + - default: [] + x-auth-type: Application & Application User + x-throttling-tier: Unlimited + /customers/trips/{tripId}: + get: + tags: + - Customer self-service trips + summary: Get trips details for a trip and token + description: >- + Get the trip details for a given trip and token ID, as long as the trip + belongs to the token and this token is bound to the profile (as derived + from sub in given JWT) + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + required: true + style: simple + explode: false + schema: + type: string + - name: tripId + in: path + required: true + style: simple + explode: false + schema: + type: integer + - name: ovPayTokenId + in: query + required: true + style: form + explode: false + schema: + type: integer + responses: + '200': + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/getTrips' + '400': + description: '400' + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + '401': + description: '401' + content: + application/json: + schema: + $ref: '#/components/schemas/401Response' + '403': + description: '403' + content: + application/json: + schema: + $ref: '#/components/schemas/403Response' + '404': + description: '404' + content: + application/json: + schema: + $ref: '#/components/schemas/404Response' + '500': + description: '500' + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' + security: + - default: [] + - default: [] + x-auth-type: Application & Application User + x-throttling-tier: Unlimited +components: + schemas: + getTokenTrips: + type: array + items: + type: object + properties: + tripId: + type: number + tripVersion: + type: number + transportType: + type: string + lineId: + type: string + tripStatus: + type: string + fare: + type: number + currency: + type: string + lastUpdatedTripDateTime: + type: string + checkinTransactionTimestamp: + type: string + checkoutTransactionTimestamp: + type: string + checkinLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + checkoutLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + loyaltyOrDiscount: + type: boolean + _links: + type: object + properties: + tripDetails: + type: object + properties: + href: + type: string + method: + type: string + templated: + type: boolean + getTrips: + type: object + properties: + tripId: + type: number + tripVersion: + type: number + tripStatus: + type: string + organisationIcon: + type: string + organisationId: + type: string + organisationName: + type: string + supersededByTripIds: + type: array + items: + type: number + supersedesTripIds: + type: array + items: + type: object + tripStartTxnId: + type: number + tripEndTxnId: + type: number + numberOfSyntheticLegs: + type: number + numberofSyntheticTrips: + type: number + products: + type: array + items: + type: object + properties: + productTemplateId: + type: string + purchaseDateTime: + type: string + appliedValue: + type: number + xspit: + type: string + category: + type: string + typesOfFareProduct: + type: array + items: + type: object + properties: + privateCode: + type: string + checkinTransactionTimestamp: + type: string + checkoutTransactionTimestamp: + type: string + checkinTransactionReference: + type: string + checkoutTransactionReference: + type: string + checkinLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + checkoutLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + xbot: + type: string + tokenType: + type: string + transportType: + type: string + lineId: + type: string + networkId: + type: string + networkName: + type: string + currency: + type: string + transportIcon: + type: string + legs: + type: array + items: + type: object + properties: + legId: + type: number + checkinTransactionTimestamp: + type: string + checkoutTransactionTimestamp: + type: string + checkinLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + checkoutLocation: + type: object + properties: + stopId: + type: number + stopName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + stopDesc: + type: string + stopUrl: + type: string + locationType: + type: number + baseRate: + type: number + lineId: + type: string + networkId: + type: string + networkName: + type: string + fare: + type: number + fareState: + type: string + currency: + type: string + products: + type: array + items: + type: object + properties: + productTemplateId: + type: string + purchaseDateTime: + type: string + appliedValue: + type: number + xspit: + type: string + category: + type: string + typesOfFareProduct: + type: array + items: + type: object + properties: + privateCode: + type: string + appliedTimePeriods: + type: array + items: + type: object + tariffJourneyStart: + type: boolean + tariffDistance: + type: number + aggrGeoIntervalDistance: + type: number + topoDistance: + type: number + concessionId: + type: string + tripLegIdx: + type: number + appliedZones: + type: array + items: + type: object + properties: + zoneId: + type: string + zoneName: + type: object + properties: + items: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + lastUpdatedTripDateTime: + type: string + fare: + type: number + loyaltyOrDiscount: + type: boolean + supportCode: + type: string + checkinTransactionId: + type: string + checkoutTransactionId: + type: string + tariffVersionId: + type: string + correlationId: + type: string + createdAt: + type: string + 400Response: + type: object + properties: + code: + type: string + example: '400' + type: + type: string + message: + type: string + example: Bad Request + description: + type: string + example: >- + 'Bad Request: Input parameters missing! Please fill in at least 1 + valid input parameter. + 401Response: + type: object + properties: + code: + type: string + example: '900901' + type: + type: string + message: + type: string + example: Invalid Credentials + description: + type: string + example: >- + Invalid Credentials. Make sure you have provided the correct + security credentials. + 403Response: + type: object + properties: + code: + type: string + example: '900901' + type: + type: string + message: + type: string + example: Retailer not authorized + description: + type: string + example: >- + The retailer is not allowed to access resource for requested + touchpoint. + 404Response: + type: object + properties: + code: + type: string + example: '404' + type: + type: string + example: Status report + message: + type: string + example: Not Found + description: + type: string + example: The requested resource is not available. + 500Response: + type: object + properties: + code: + type: string + example: '500' + type: + type: string + message: + type: string + example: Internal Server Error + description: + type: string \ No newline at end of file -- 2.45.2 From 8c4542a151bc7bcf36f1becd08a8145305c78af8 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 5 Mar 2026 12:11:35 +0100 Subject: [PATCH 02/10] OVPAY-2473 - Added endpoint for getting stops. --- src/openapi/customers/customers-trips.yaml | 210 ++++++++++++++++++++- 1 file changed, 207 insertions(+), 3 deletions(-) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 00726bb..4f924ed 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -1,6 +1,6 @@ openapi: 3.0.1 info: - title: ABTCustomers + title: ABT Customer Self Service APIs version: '1.0' servers: - url: https://services.acc.api.htm.nl/abt/abtcustomers/1.0 @@ -10,7 +10,7 @@ paths: /customers/tokens/{ovpayTokenId}/trips: get: tags: - - Customer self-service trips + - Trips summary: Get trips for a token description: >- Get the most recent trips for a given token ID, as long as this token is @@ -173,7 +173,7 @@ paths: /customers/trips/{tripId}: get: tags: - - Customer self-service trips + - Trips summary: Get trips details for a trip and token description: >- Get the trip details for a given trip and token ID, as long as the trip @@ -243,6 +243,85 @@ paths: - default: [] x-auth-type: Application & Application User x-throttling-tier: Unlimited + /customers/tariff/stops: + get: + tags: + - Trips + summary: 9776 - Get Possible Stops With Details + operationId: API-9776v3_getPossibleStopsWithDetails + description: Get Possible Stops With Details + security: + - OAuthAuthorization: + - default + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + required: true + style: simple + explode: false + schema: + type: string + - name: xbot + description: >- + A xBOT IS AN unique identifier THAT is an external representation of + a backoffice Token for a particular Business Entity + in: query + required: true + schema: + type: string + format: uuid + - name: tripId + in: query + description: A tripId IS AN identifier THAT distinguishes a Trip from all other Trips + required: true + schema: + type: integer + format: int64 + - name: transactionId + in: query + description: >- + A transactionId IS A unique identifier THAT is generated by the GBO + and assigned to every Transaction that is received + required: true + schema: + type: string + responses: + '200': + description: Success with results + content: + application/json: + schema: + $ref: '#/components/schemas/MissingCkiCkoRequest' + '400': + description: '400' + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + '401': + description: '401' + content: + application/json: + schema: + $ref: '#/components/schemas/401Response' + '403': + description: '403' + content: + application/json: + schema: + $ref: '#/components/schemas/403Response' + '404': + description: '404' + content: + application/json: + schema: + $ref: '#/components/schemas/404Response' + '500': + description: '500' + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' components: schemas: getTokenTrips: @@ -599,6 +678,131 @@ components: type: string createdAt: type: string + MissingCkiCkoRequest: + type: object + properties: + xbot: + type: string + description: >- + A xBOT IS AN unique identifier THAT is an external representation of + a backoffice Token for a particular Business Entity + counterpartTransactionId: + type: string + description: >- + A counterpartTransactionId IS A unique identifier THAT assigned to + every Transaction that is received + counterpartEntryExitType: + type: string + description: >- + AN counterpartEntryExitType IS AN direction indicator THAT describes + a possible direction indicated by the callee that created the + Transaction + counterpartTimeStamp: + type: string + description: >- + A counterpartTimeStamp IS A date, time and time zone indication THAT + describes when the Transaction was created either by a Device or + callee + counterpartStop: + $ref: '#/components/schemas/ScheduledStopPointData' + deviceId: + type: string + description: >- + A deviceId IS AN unique identifier THAT distinguishes a Device from + all other Devices + deviceClassId: + type: string + description: >- + A deviceClassId IS AN enumerated identifier THAT describes the type + of Device responsible for creating the Transaction + scheduledStopPoints: + type: array + items: + $ref: '#/components/schemas/ScheduledStopPointData' + ScheduledStopPointData: + type: object + properties: + alternativeTexts: + type: array + items: + $ref: '#/components/schemas/AlternativeText' + name: + type: string + description: >- + A name IS A string THAT is used to described name of the + TariffLocation name + shortName: + type: string + description: >- + A shortName IS AN abbreviation THAT contains a shortened version of + the TariffLocation name + description: + type: string + description: >- + A description IS A string THAT is used as an additional label of the + TariffLocation as defined in the Tariff Fragment + location: + $ref: '#/components/schemas/Location' + stopId: + type: string + description: >- + A stopId IS A unique identifier THAT distinguishes a Tariff Location + from all other Tariff Locations + transportModes: + type: array + description: >- + A transportMode IS AN identifier THAT describes the mode of + transport + items: + type: string + AlternativeText: + type: object + description: >- + AN AlternativeText IS AN object THAT contains values to enable one or + more language translations + properties: + text: + type: object + description: >- + A text is AN wrapper THAT is used as an abstraction layer to contain + the properties of AlternativeText + properties: + lang: + type: string + description: >- + A lang IS AN enumerated identifier THAT describes the language + of the text within the AlternativeText object + example: en-US + textIdType: + type: string + description: A textIdType IS AN name THAT is used to categorize types of text + example: publicName + text: + type: string + description: >- + A text IS A name THAT has been translated to a particular + language + example: Default Travel Entitlement + Location: + type: object + properties: + longitude: + type: number + description: >- + A longitude IS A number THAT represents the geographic coordinate + that specifies the east-west position of a point on the surface of + the Earth + latitude: + type: number + description: >- + A latitude IS A number THAT represents the geographic coordinate + that specifies the north-south position of a point on the surface of + the Earth + altitude: + type: number + description: >- + AN altitude IS A number THAT represents the height of an object or + point in relation to sea level or ground level 400Response: type: object properties: -- 2.45.2 From 513045c1468dec23a20626c013d1f0306b0c8082 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 5 Mar 2026 12:19:24 +0100 Subject: [PATCH 03/10] OVPAY-2473 - Added endpoint for POSTing missing tap. --- src/openapi/customers/customers-trips.yaml | 170 +++++++++++++++++++++ 1 file changed, 170 insertions(+) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 4f924ed..36dfce5 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -322,6 +322,104 @@ paths: application/json: schema: $ref: '#/components/schemas/500Response' + /customers/id-media/missing-taps: + post: + tags: + - Trips + summary: 8255 - Manual Check-in or Check-out + description: >- + Creates manual Check-in or Check-out for transactions that are missing + their pair. Check-in or Check-out directions are defined using + **entryExitType** parameter in body respectivelly + operationId: API-8255v3_manualCheckInOrCheckOut + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + required: true + style: simple + explode: false + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ManualTap' + required: true + responses: + '200': + description: Operation successful + content: + application/json: + schema: + $ref: '#/components/schemas/GenericOkResponse' + example: + referenceId: BSS-1627294719604 + numberOfRemainingAttempts: 0 + timeOfNextAllowedAttempt: '2022-03-19T17:07:31Z' + '400': + description: |- + Bad request + List of possible error codes: + + * 402 - Unable to store message + * 403 - Unable to send message to NotificationProcessor + * 404 - Unable to parse message + * 405 - Unable to validate message + * 406 - Missing mandatory headers + * 407 - Counter Transaction not found + * 408 - Manual taps limit exceeded + * 409 - Unable to send message to Orchestrator + * 410 - Unable to construct message + * 411 - Unable to get data + * 412 - Unable to get bin + * 422 - Duplicate manual tap + + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + example: + errorMessage: + message: >- + Maximum limit 5 of manual taps reached for beId = 7 and role + = PTO within a period of 2592000 seconds for this token + referenceId: BSS-1627294719604 + businessExceptions: + - code: '408' + message: Manual taps limit exceeded + - code: BSS-timeOfNextAllowedAttempt + message: '2022-03-19T17:07:31Z' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' + example: + errorMessage: + message: The server responded with http status code 500 + referenceId: BSS-1627294719604 + businessExceptions: + - code: '5026' + message: Unable to send request to Orchestrator + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/503Response' + example: + errorMessage: + message: The server responded with http status code 503 + referenceId: BSS-1627294719604 + businessExceptions: + - code: '5026' + message: Unable to send request to Orchestrator + x-codegen-request-body-name: ManualTap + security: + - OAuthAuthorization: + - default components: schemas: getTokenTrips: @@ -803,6 +901,65 @@ components: description: >- AN altitude IS A number THAT represents the height of an object or point in relation to sea level or ground level + ManualTap: + required: + - xbot + - counterpartTransactionId + - deviceClassId + - deviceId + - stopId + type: object + properties: + counterpartTransactionId: + type: string + description: Id of the transaction that is missing its pair + example: '1236589547' + xbot: + type: string + description: Token identification code (external backoffice token) + example: '12272277752953521453' + stopId: + type: string + description: Id of the location of the tap + example: '123' + deviceId: + type: string + description: Id of the device + example: '5415236' + deviceClassId: + type: string + description: Class Id of the device + example: '54' + transactionTimestamp: + type: string + description: Timestamp of the transaction + format: date-time + example: '2019-11-25T17:39:45.000Z' + entryExitType: + type: string + description: 'Direction of the tap: in or out' + example: ENTRY + enum: + - UNKNOWN + - ENTRY + - EXIT + description: JSON schema for ManualTap message + GenericOkResponse: + required: + - referenceId + description: Ok response object + type: object + properties: + referenceId: + type: string + description: Reference identification code + numberOfRemainingAttempts: + type: integer + description: Number of remaining attempts + timeOfNextAllowedAttempt: + type: string + format: date-time + description: Time when next attempt is allowed 400Response: type: object properties: @@ -877,5 +1034,18 @@ components: message: type: string example: Internal Server Error + description: + type: string + 503Response: + type: object + properties: + code: + type: string + example: '503' + type: + type: string + message: + type: string + example: Service Unavailable description: type: string \ No newline at end of file -- 2.45.2 From a7e32f61222dc206d3503b4cd29b61e0ca803b0c Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 5 Mar 2026 12:37:04 +0100 Subject: [PATCH 04/10] OVPAY-2473 - Added examples for GET trip details. --- src/openapi/customers/customers-trips.yaml | 331 +++++++++++++++++++++ 1 file changed, 331 insertions(+) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 36dfce5..c94b264 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -208,6 +208,337 @@ paths: application/json: schema: $ref: '#/components/schemas/getTrips' + examples: + completedTripDetails: + summary: Example of a completed trip + value: + tripId: 66538 + tripVersion: 2 + tripStatus: COMPLETE + tripFareNature: FIXED + paymentMethodId: dba0b896-118d-4e9e-abf5-af264ced34c4 + paymentMethodMode: BAL + paymentMethodName: BAL + paymentProviderName: Account Balance + paymentProviderBusinessEntityId: "4" + paymentProviderCommercialName: VAD Flex + paymentProviderCommercialUrl: https://www.vad.nl/mijnvad + organisationIcon: /icons/organisations/4.svg + organisationId: "4" + organisationName: NS + supersededByTripIds: + - 66539 + - 66540 + supersedesTripIds: [] + tripStartTxnId: 1125977 + tripEndTxnId: 1125978 + numberOfSyntheticLegs: 3 + numberofSyntheticTrips: 2 + products: + - productTemplateId: "N/A" + purchaseDateTime: 2021-06-02T08:38:32Z + appliedValue: 2470 + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: SALES + typesOfFareProduct: + - privateCode: payg + fareAggregationCycle: 2 + - xpit: 72c11b8d-5a96-4cc2-9fc8-258a25b57f69 + productTemplateId: "1:2001" + productCommercialName: + items: + - key: nl-NL + value: Pay As You Go Program (NL) + - key: en-US + value: Pay As You Go Program + validFrom: 2021-06-02T08:38:32Z + validUntil: 2099-12-31T23:59:59Z + weight: 2470 + appliedMetric: FARE + appliedValue: 2470 + xprofit: 0eb178f7-c548-417e-a44f-7248a582ac9d + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: INTERNAL + typesOfFareProduct: + - privateCode: payg + checkinTransactionTimestamp: 2021-06-01T06:00:00Z + checkoutTransactionTimestamp: 2021-06-01T06:22:00Z + checkinTransactionReference: 001e8481;1151;gemaltoPure + checkoutTransactionReference: 001e8481;1152;gemaltoPure + checkinLocation: + stopId: 621 + stopName: + items: + - key: nl-NL + value: Utrecht Centraal + - key: en-US + value: Utrecht Centraal + stopDesc: Station Utrecht Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: + stopId: 253 + stopName: + items: + - key: nl-NL + value: Goes + - key: en-US + value: Goes + stopDesc: Station Goes + stopUrl: /icons/stops/stop.svg + locationType: 0 + xbot: 36637b86-7a31-4b77-99dd-2d39b9c1a9b6 + tokenType: GemaltoPure + transportType: RAIL + lineId: "10" + networkId: "1" + networkName: HRN + vehicleId: 123 + currency: EUR + transportIcon: /icons/transportTypes/rail.svg + legs: + - legId: 83387 + checkinTransactionTimestamp: 2021-06-01T06:00:00Z + checkoutTransactionTimestamp: 2021-06-01T06:22:00Z + checkinLocation: + stopId: 621 + stopName: + items: + - key: nl-NL + value: Utrecht Centraal + - key: en-US + value: Utrecht Centraal + stopDesc: Station Utrecht Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: + stopId: 253 + stopName: + items: + - key: nl-NL + value: Goes + - key: en-US + value: Goes + stopDesc: Station Goes + stopUrl: /icons/stops/stop.svg + locationType: 0 + baseRate: 2470 + lineId: "10" + networkId: "1" + networkName: HRN + fare: 2470 + fareState: CALCULATED + currency: EUR + products: + - productTemplateId: "N/A" + purchaseDateTime: 2021-06-02T08:38:32Z + appliedValue: 2470 + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: SALES + typesOfFareProduct: + - privateCode: payg + - xpit: 72c11b8d-5a96-4cc2-9fc8-258a25b57f69 + productTemplateId: "1:2001" + productCommercialName: + items: + - key: nl-NL + value: Pay As You Go Program (NL) + - key: en-US + value: Pay As You Go Program + validFrom: 2021-06-02T08:38:32Z + validUntil: 2099-12-31T23:59:59Z + weight: 2470 + appliedMetric: FARE + appliedValue: 2470 + xprofit: 0eb178f7-c548-417e-a44f-7248a582ac9d + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: INTERNAL + typesOfFareProduct: + - privateCode: payg + appliedTimePeriods: [] + tariffJourneyStart: true + tariffDistance: 9 + aggrGeoIntervalDistance: 9 + topoDistance: 0 + concessionId: "1" + tripLegIdx: 0 + appliedZones: + - zoneId: "73" + zoneName: + items: + - key: nl-NL + value: Enschede-Glanerburg + - key: en-US + value: Enschede-Glanerburg + lastUpdatedTripDateTime: 2021-06-01T06:22:00Z + fare: 2470 + loyaltyOrDiscount: false + supportCode: wYyM3nDb2Uy5ge + checkinTransactionId: 001e8481-1151-gemaltoPure-1622527200000 + checkoutTransactionId: 001e8481-1152-gemaltoPure-1622528520000 + tariffVersionId: NS:5 + correlationId: c3ae1ba3-780a-4416-8a38-3fd03a9005b7 + createdAt: 2021-06-02T15:03:46.813Z + missingCkoTripDetails: + summary: Example of a trip with missing check-out + value: + tripId: 66538 + tripVersion: 2 + tripStatus: MISSING_CKO + tripFareNature: FIXED + paymentMethodId: dba0b896-118d-4e9e-abf5-af264ced34c4 + paymentMethodMode: BAL + paymentMethodName: BAL + paymentProviderName: Account Balance + paymentProviderBusinessEntityId: "4" + paymentProviderCommercialName: VAD Flex + paymentProviderCommercialUrl: https://www.vad.nl/mijnvad + organisationIcon: /icons/organisations/4.svg + organisationId: "4" + organisationName: NS + supersededByTripIds: + - 66539 + - 66540 + supersedesTripIds: [] + tripStartTxnId: 1125977 + tripEndTxnId: 1125978 + numberOfSyntheticLegs: 3 + numberofSyntheticTrips: 2 + products: + - productTemplateId: "N/A" + purchaseDateTime: 2021-06-02T08:38:32Z + appliedValue: 2470 + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: SALES + typesOfFareProduct: + - privateCode: payg + fareAggregationCycle: 2 + - xpit: 72c11b8d-5a96-4cc2-9fc8-258a25b57f69 + productTemplateId: "1:2001" + productCommercialName: + items: + - key: nl-NL + value: Pay As You Go Program (NL) + - key: en-US + value: Pay As You Go Program + validFrom: 2021-06-02T08:38:32Z + validUntil: 2099-12-31T23:59:59Z + weight: 2470 + appliedMetric: FARE + appliedValue: 2470 + xprofit: 0eb178f7-c548-417e-a44f-7248a582ac9d + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: INTERNAL + typesOfFareProduct: + - privateCode: payg + checkinTransactionTimestamp: 2021-06-01T06:00:00Z + checkoutTransactionTimestamp: 2021-06-01T06:22:00Z + checkinTransactionReference: 001e8481;1151;gemaltoPure + checkoutTransactionReference: 001e8481;1152;gemaltoPure + checkinLocation: + stopId: 621 + stopName: + items: + - key: nl-NL + value: Utrecht Centraal + - key: en-US + value: Utrecht Centraal + stopDesc: Station Utrecht Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: + stopId: 253 + stopName: + items: + - key: nl-NL + value: Goes + - key: en-US + value: Goes + stopDesc: Station Goes + stopUrl: /icons/stops/stop.svg + locationType: 0 + xbot: 36637b86-7a31-4b77-99dd-2d39b9c1a9b6 + tokenType: GemaltoPure + transportType: RAIL + lineId: "10" + networkId: "1" + networkName: HRN + vehicleId: 123 + currency: EUR + transportIcon: /icons/transportTypes/rail.svg + legs: + - legId: 83387 + checkinTransactionTimestamp: 2021-06-01T06:00:00Z + checkoutTransactionTimestamp: null + checkinLocation: + stopId: 621 + stopName: + items: + - key: nl-NL + value: Utrecht Centraal + - key: en-US + value: Utrecht Centraal + stopDesc: Station Utrecht Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: null + baseRate: 400 + lineId: "10" + networkId: "1" + networkName: HRN + fare: 400 + fareState: CALCULATED + currency: EUR + products: + - productTemplateId: "N/A" + purchaseDateTime: 2021-06-02T08:38:32Z + appliedValue: 400 + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: SALES + typesOfFareProduct: + - privateCode: payg + - xpit: 72c11b8d-5a96-4cc2-9fc8-258a25b57f69 + productTemplateId: "1:2001" + productCommercialName: + items: + - key: nl-NL + value: Pay As You Go Program (NL) + - key: en-US + value: Pay As You Go Program + validFrom: 2021-06-02T08:38:32Z + validUntil: 2099-12-31T23:59:59Z + weight: 400 + appliedMetric: FARE + appliedValue: 400 + xprofit: 0eb178f7-c548-417e-a44f-7248a582ac9d + xspit: 39b9183d-767d-4364-9d1b-575613c12a96 + category: INTERNAL + typesOfFareProduct: + - privateCode: payg + appliedTimePeriods: [] + tariffJourneyStart: true + tariffDistance: 9 + aggrGeoIntervalDistance: 9 + topoDistance: 0 + concessionId: "1" + tripLegIdx: 0 + appliedZones: + - zoneId: "73" + zoneName: + items: + - key: nl-NL + value: Enschede-Glanerburg + - key: en-US + value: Enschede-Glanerburg + lastUpdatedTripDateTime: 2021-06-01T06:22:00Z + fare: 2470 + loyaltyOrDiscount: false + supportCode: wYyM3nDb2Uy5ge + checkinTransactionId: 001e8481-1151-gemaltoPure-1622527200000 + checkoutTransactionId: null + tariffVersionId: NS:5 + correlationId: c3ae1ba3-780a-4416-8a38-3fd03a9005b7 + createdAt: 2021-06-02T15:03:46.813Z '400': description: '400' content: -- 2.45.2 From 44dae159b8153fcc365857ff2c2a90cd4ab0e7f9 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 5 Mar 2026 13:10:48 +0100 Subject: [PATCH 05/10] OVPAY-2473 - Added HATEOAS for trip correction. --- src/openapi/customers/customers-trips.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index c94b264..e9c8516 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -379,6 +379,7 @@ paths: tariffVersionId: NS:5 correlationId: c3ae1ba3-780a-4416-8a38-3fd03a9005b7 createdAt: 2021-06-02T15:03:46.813Z + _links: null missingCkoTripDetails: summary: Example of a trip with missing check-out value: @@ -539,6 +540,11 @@ paths: tariffVersionId: NS:5 correlationId: c3ae1ba3-780a-4416-8a38-3fd03a9005b7 createdAt: 2021-06-02T15:03:46.813Z + _links: + getStopsForCorrection: + href: https://services.acc.api.htm.nl/abt/abtcustomers/1.0/customers/tariff/stops?xbot=36637b86-7a31-4b77-99dd-2d39b9c1a9b6&tripId=66538&transactionId=001e8481-1151-gemaltoPure-1622527200000 + method: GET + templated: false '400': description: '400' content: @@ -1107,6 +1113,18 @@ components: type: string createdAt: type: string + _links: + type: object + properties: + getStopsForCorrection: + type: object + properties: + href: + type: string + method: + type: string + templated: + type: boolean MissingCkiCkoRequest: type: object properties: -- 2.45.2 From b6586891fca4b3286ab73154d911f92b105bd792 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 16 Mar 2026 13:08:02 +0100 Subject: [PATCH 06/10] OVPAY-2473 - Fixed semantic errors. --- src/openapi/customers/customers-trips.yaml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index e9c8516..67059e4 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -167,7 +167,6 @@ paths: $ref: '#/components/schemas/500Response' security: - default: [] - - default: [] x-auth-type: Application & Application User x-throttling-tier: Unlimited /customers/trips/{tripId}: @@ -588,8 +587,7 @@ paths: operationId: API-9776v3_getPossibleStopsWithDetails description: Get Possible Stops With Details security: - - OAuthAuthorization: - - default + - default: [] parameters: - name: X-HTM-JWT-AUTH-HEADER in: header @@ -755,9 +753,15 @@ paths: message: Unable to send request to Orchestrator x-codegen-request-body-name: ManualTap security: - - OAuthAuthorization: - - default + - default: [] components: + securitySchemes: + default: + type: oauth2 + flows: + implicit: + authorizationUrl: https://services.acc.api.htm.nl/authorize + scopes: {} schemas: getTokenTrips: type: array -- 2.45.2 From 903adbe238b35334a0609c45578a3945da2b8ffe Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 16 Mar 2026 13:23:15 +0100 Subject: [PATCH 07/10] OVPAY-2473 - Added HATEOAS for trip correction in trips list. --- src/openapi/customers/customers-trips.yaml | 86 ++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 67059e4..9c2bb21 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -135,6 +135,83 @@ paths: application/json: schema: $ref: '#/components/schemas/getTokenTrips' + examples: + emptyResponse: + summary: No trips found for a token + value: [] + multipleTripsResponse: + summary: Multiple trips found for a token + value: + - tripId: 66538 + tripVersion: 2 + transportType: RAIL + lineId: "10" + tripStatus: COMPLETE + fare: 2470 + currency: EUR + lastUpdatedTripDateTime: 2021-06-01T06:22:00Z + checkinTransactionTimestamp: 2021-06-01T06:00:00Z + checkoutTransactionTimestamp: 2021-06-01T06:22:00Z + checkinLocation: + stopId: 621 + stopName: + items: + - key: nl-NL + value: Utrecht Centraal + - key: en-US + value: Utrecht Centraal + stopDesc: Station Utrecht Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: + stopId: 253 + stopName: + items: + - key: nl-NL + value: Goes + - key: en-US + value: Goes + stopDesc: Station Goes + stopUrl: /icons/stops/stop.svg + locationType: 0 + loyaltyOrDiscount: false + _links: + tripDetails: + href: https://services.acc.api.htm.nl/abt/abtcustomers/1.0/customers/tokens/123/trips/66538 + method: GET + templated: false + - tripId: 66539 + tripVersion: 1 + transportType: BUS + lineId: "20" + tripStatus: MISSING_CKO + fare: 1230 + currency: EUR + lastUpdatedTripDateTime: 2021-06-01T07:00:00Z + checkinTransactionTimestamp: 2021-06-01T06:30:00Z + checkoutTransactionTimestamp: null + checkinLocation: + stopId: 622 + stopName: + items: + - key: nl-NL + value: Amsterdam Centraal + - key: en-US + value: Amsterdam Centraal + stopDesc: Station Amsterdam Centraal + stopUrl: /icons/stops/stop.svg + locationType: 0 + checkoutLocation: null + loyaltyOrDiscount: true + _links: + getTripDetails: + href: https://services.acc.api.htm.nl/abt/abtcustomers/1.0/customers/tokens/123/trips/66539 + method: GET + templated: false + getStopsForCorrection: + href: https://services.acc.api.htm.nl/abt/abtcustomers/1.0/customers/tariff/stops?xbot=36637b86-7a31-4b77-99dd-2d39b9c1a9b6&tripId=66539&transactionId=001e8481-1151-gemaltoPure-1622527200000 + method: GET + templated: false '400': description: '400' content: @@ -848,6 +925,15 @@ components: type: string templated: type: boolean + getStopsForCorrection: + type: object + properties: + href: + type: string + method: + type: string + templated: + type: boolean getTrips: type: object properties: -- 2.45.2 From 1bf9fa2fd0ca379e3e57da6e6cfdfca9e1ca32c5 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 16 Mar 2026 13:34:42 +0100 Subject: [PATCH 08/10] OVPAY-2473 - Improved URIs. --- src/openapi/customers/customers-trips.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 9c2bb21..557ad7a 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -656,7 +656,7 @@ paths: - default: [] x-auth-type: Application & Application User x-throttling-tier: Unlimited - /customers/tariff/stops: + /customers/trips/stops: get: tags: - Trips @@ -734,7 +734,7 @@ paths: application/json: schema: $ref: '#/components/schemas/500Response' - /customers/id-media/missing-taps: + /customers/trips/missing-taps: post: tags: - Trips -- 2.45.2 From 9bb73202991b2d34096f0cd73d9bb5e264dfcfee Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 16 Mar 2026 14:35:59 +0100 Subject: [PATCH 09/10] OVPAY-2473 - Improved examples. --- src/openapi/customers/customers-trips.yaml | 91 ++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 557ad7a..5964d6b 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -704,6 +704,97 @@ paths: application/json: schema: $ref: '#/components/schemas/MissingCkiCkoRequest' + examples: + possibleStopsResponse: + summary: Possible stops for a trip with missing check-out + value: + xbot: 36637b86-7a31-4b77-99dd-2d39b9c1a9b6 + counterpartTransactionId: 001e8481-1151-gemaltoPure-1622527200000 + counterpartEntryExitType: ENTRY + counterpartTimeStamp: "2021-06-01T06:00:00Z" + counterpartStop: + alternativeTexts: + - text: + lang: nl-NL + textIdType: Utrecht Centraal + text: Utrecht Centraal + name: Utrecht Centraal + shortName: Utrecht Centraal + description: Station Utrecht Centraal + location: + longitude: 5.1099 + latitude: 52.0894 + altitude: 0 + stopId: 621 + transportModes: + - BUS + - RAIL + deviceId: 3212967 + deviceClassId: 9 + scheduledStopPoints: + - alternativeTexts: + - text: + lang: nl-NL + textIdType: publicName + text: Brouwersgracht + name: Brouwersgracht + shortName: Brouwersgracht + description: Brouwersgracht + location: + longitude: 4.3050492 + latitude: 52.0737538 + altitude: 0 + stopId: 42 + transportModes: + - RAIL + - alternativeTexts: + - text: + lang: nl-NL + textIdType: publicName + text: Grote Markt + name: Grote Markt + shortName: Grote Markt + description: Grote Markt + location: + longitude: 4.3092398 + latitude: 52.075929 + altitude: 0 + stopId: 42 + transportModes: + - RAIL + - BUS + - alternativeTexts: + - text: + lang: nl-NL + textIdType: publicName + text: Spui + name: Spui + shortName: Spui + description: Spui + location: + longitude: 4.3172 + latitude: 52.0764 + altitude: 0 + stopId: 42 + transportModes: + - RAIL + - BUS + - alternativeTexts: + - text: + lang: nl-NL + textIdType: publicName + text: Den Haag Centraal + name: Den Haag Centraal + shortName: Den Haag Centraal + description: Den Haag Centraal + location: + longitude: 4.32553 + latitude: 52.08176 + altitude: 0 + stopId: 42 + transportModes: + - RAIL + - BUS '400': description: '400' content: -- 2.45.2 From f237f677e34ce9369a108129985ed147aacc1264 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 16 Mar 2026 14:45:05 +0100 Subject: [PATCH 10/10] OVPAY-2473 - Improved examples part 2. --- src/openapi/customers/customers-trips.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/openapi/customers/customers-trips.yaml b/src/openapi/customers/customers-trips.yaml index 5964d6b..7fb5955 100644 --- a/src/openapi/customers/customers-trips.yaml +++ b/src/openapi/customers/customers-trips.yaml @@ -1443,32 +1443,32 @@ components: counterpartTransactionId: type: string description: Id of the transaction that is missing its pair - example: '1236589547' + example: 001e8481-1151-gemaltoPure-1622527200000 xbot: type: string description: Token identification code (external backoffice token) - example: '12272277752953521453' + example: 36637b86-7a31-4b77-99dd-2d39b9c1a9b6 stopId: type: string description: Id of the location of the tap - example: '123' + example: 42 deviceId: type: string description: Id of the device - example: '5415236' + example: 3212967 deviceClassId: type: string description: Class Id of the device - example: '54' + example: 9 transactionTimestamp: type: string description: Timestamp of the transaction format: date-time - example: '2019-11-25T17:39:45.000Z' + example: 2019-11-25T17:39:45.000Z entryExitType: type: string description: 'Direction of the tap: in or out' - example: ENTRY + example: EXIT enum: - UNKNOWN - ENTRY -- 2.45.2