features/OVPAY2475-AGO #66

Merged
MirjamHTM merged 11 commits from features/OVPAY2475-AGO into develop 2026-08-10 12:09:05 +00:00
8 changed files with 696 additions and 99 deletions

View File

@ -215,9 +215,14 @@ public class ABTProductsPUTGenerator {
}
case "paymentMoment" -> {
LOGGER.info("Rewriting paymentMoment to paymentMomentId...");
if (jsonField.getValue().get("paymentMomentId").isNull()) {
LOGGER.info("Rewriting null paymentMomentId...");
((ObjectNode)newJsonNode).putRawValue("paymentMomentId", null);
} else {
Long paymentMomentId = jsonField.getValue().get("paymentMomentId").asLong();
((ObjectNode)newJsonNode).put("paymentMomentId", paymentMomentId);
}
}
case "requiredCustomerLevel" -> {
LOGGER.info("Rewriting requiredCustomerLevel to requiredCustomerLevelId...");
Long requiredCustomerLevelId = jsonField.getValue().get("requiredCustomerLevelId").asLong();

View File

@ -45,12 +45,36 @@ paths:
"contractStatus":
{ "contractStatusId": 2, "name": "active" },
"productId": 1,
"productName": "HTM Maand 20% korting",
"termDuration": "P0Y1M0D",
"productName": "HTM Maand 20% korting doorlopend",
"termDuration": "P1M",
"billingDay": 15,
"highestInvoiceTerm": 1,
"created": "2024-08-01 15:01:00.000",
"created": "2024-08-01T15:01:00.000Z",
"ovPayTokenId": 1337,
"contractVersions": [
{
"contractVersionId": 1,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM Maand 20% korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9,
"termAmountInclTax": 400,
"start": "2024-08-01T15:01:00.000Z",
"end": "2025-01-01T03:00:00.000Z"
},
{
"contractVersionId": 2,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM Maand 20% korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9,
"termAmountInclTax": 500,
"start": "2025-01-01T03:00:00.000Z",
"end": null
}
],
"_links":
{
"get_token":
@ -68,14 +92,38 @@ paths:
"orderLineId": "42f68042-908f-41f4-9d9b-4cab843ff0e8",
"touchpointId": 2,
"contractStatus":
{ "contractStatusId": 1, "name": "new" },
{ "contractStatusId": 6, "name": "pending cancellation" },
"productId": 1,
"productName": "HTM Maand 20% korting",
"termDuration": "P0Y1M0D",
"productName": "HTM 20% Korting doorlopend",
"termDuration": "P1M",
"billingDay": 15,
"highestInvoiceTerm": 1,
"created": "2024-08-01 15:01:00.000",
"created": "2024-08-01T15:01:00.000Z",
"ovPayTokenId": 1338,
"contractVersions": [
{
"contractVersionId": 1,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM 20% Korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9,
"termAmountInclTax": 400,
"start": "2024-08-01T15:01:00.000Z",
"end": "2025-01-01T03:00:00.000Z"
},
{
"contractVersionId": 2,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM 20% Korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9,
"termAmountInclTax": 500,
"start": "2025-01-01T03:00:00.000Z",
"end": "2025-02-01T03:00:00.000Z"
}
],
"_links":
{
"get_token":
@ -154,8 +202,8 @@ paths:
"contractStatus":
{ "contractStatusId": 2, "name": "active" },
"productId": 1,
"productName": "HTM Maand 20% korting",
"termDuration": "P0Y1M0D",
"productName": "HTM 20% Korting doorlopend",
"termDuration": "P1M",
"billingDay": 15,
"highestInvoiceTerm": 1,
"ovPayTokenId": 1337,
@ -165,22 +213,22 @@ paths:
"contractVersionId": 1,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM Maand 20% korting",
"productName": "HTM 20% Korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9.0,
"termAmountInclTax": 400,
"start": "2024-07-04 15:01:00.000",
"end": "2024-12-31 15:01:00.000",
"start": "2024-08-01T15:01:00.000Z",
"end": "2025-01-01T03:00:00.000Z",
},
{
"contractVersionId": 2,
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
"productId": 1,
"productName": "HTM Maand 20% korting",
"productName": "HTM 20% Korting doorlopend",
"taxCode": "V9",
"taxPercentage": 9.0,
"termAmountInclTax": 400,
"start": "2025-01-01 15:01:00.000",
"start": "2025-01-01T03:00:00.000Z",
},
],
"contractActions":
@ -190,7 +238,7 @@ paths:
"actionType":
{ "actionTypeId": 1, "name": "create" },
"user": "subid123456",
"timestamp": "2024-07-02 15:01:00.000",
"timestamp": "2024-07-02T15:01:00.000Z",
"details": "Contract created",
"correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
},
@ -199,7 +247,7 @@ paths:
"actionType":
{ "actionTypeId": 2, "name": "change" },
"user": "subid123456",
"timestamp": "2024-07-03 15:01:00.000",
"timestamp": "2024-07-03T15:01:00.000Z",
"details": "Contract changed",
"correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
},
@ -211,8 +259,8 @@ paths:
"externalReference": "F2024-0001",
"term": 1,
"invoiceDate": "2024-07-02",
"created": "2024-07-02 15:01:00.000",
"updated": "2024-07-02 15:01:00.000",
"created": "2024-07-02T15:01:00.000Z",
"updated": "2024-07-02T15:01:00.000Z",
"state": "invoice_created",
"data": "{json}",
"isCredit": false,
@ -270,8 +318,8 @@ paths:
"externalReference": "F2024-0001",
"term": 1,
"invoiceDate": "2024-07-02",
"created": "2024-07-02 15:01:34.000",
"updated": "2024-07-04 00:04:56.000",
"created": "2024-07-02T15:01:34.000Z",
"updated": "2024-07-04T00:04:56.000Z",
"state": "invoice_created",
"public_link": "http://mijnfactuurinzien.nl/F2024-0001",
"isCredit": false,
@ -282,8 +330,8 @@ paths:
"externalReference": "F2024-0002",
"term": 2,
"invoiceDate": "2024-08-02",
"created": "2024-08-02 15:01:34.000",
"updated": "2024-08-04 00:04:56.000",
"created": "2024-08-02T15:01:34.000Z",
"updated": "2024-08-04T00:04:56.000Z",
"state": "invoice_created",
"public_link": "http://mijnfactuurinzien.nl/F2024-0002",
"isCredit": false,
@ -328,8 +376,8 @@ paths:
"cancellationMoment": "termBound",
"termDuration": "P1M",
"billingDay": 18,
"cancellationFrom": "2024-08-10T00:00:00",
"cancellationUntil": "2026-08-10T00:00:00",
"cancellationFrom": "2024-08-10T00:00:00Z",
"cancellationUntil": "2026-08-10T00:00:00Z",
}
/contracts/{contractId}/cancellationvalidation:
parameters:
@ -382,7 +430,7 @@ paths:
{
"validationResult": true,
"validationMessage": "",
"end": "2024-08-10T03:59:59",
"end": "2024-08-10T03:59:59Z",
"refundAmount": 2489,
"refundMethods": ["creditInvoice", "iDeal"],
}
@ -451,7 +499,7 @@ paths:
the refund amount and refund method.
value:
{
"end": "2024-08-10T03:59:59",
"end": "2024-08-10T03:59:59Z",
"refundAmount": 2489,
"refundMethod": "creditInvoice",
}
@ -516,8 +564,8 @@ paths:
"taxCode": "V9",
"taxPercentage": 9.0,
"termAmountInclTax": 400,
"start": "2024-07-04 15:01:00.000",
"end": "2024-12-31 15:01:00.000",
"start": "2024-07-04T15:01:00.000Z",
"end": "2024-12-31T15:01:00.000Z",
},
{
"contractVersionId": 2,
@ -527,7 +575,8 @@ paths:
"taxCode": "V9",
"taxPercentage": 9.0,
"termAmountInclTax": 400,
"start": "2025-01-01 15:01:00.000",
"start": "2025-01-01T15:01:00.000Z",
"end": null
},
],
"contractActions":
@ -537,7 +586,7 @@ paths:
"actionType":
{ "actionTypeId": 1, "name": "create" },
"user": "subid123456",
"timestamp": "2024-07-02 15:01:00.000",
"timestamp": "2024-07-02T15:01:00.000Z",
"details": "Contract created",
"correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
},
@ -546,7 +595,7 @@ paths:
"actionType":
{ "actionTypeId": 2, "name": "change" },
"user": "subid123456",
"timestamp": "2024-07-03 15:01:00.000",
"timestamp": "2024-07-03T15:01:00.000Z",
"details": "Contract changed",
"correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
},
@ -558,8 +607,8 @@ paths:
"externalReference": "F2024-0001",
"term": 1,
"invoiceDate": "2024-07-02",
"created": "2024-07-02 15:01:00.000",
"updated": "2024-07-02 15:01:00.000",
"created": "2024-07-02T15:01:00.000Z",
"updated": "2024-07-02T15:01:00.000Z",
"state": "invoice_created",
"data": "{json}",
"isCredit": false,
@ -682,7 +731,7 @@ paths:
"termDuration": "P0Y1M0D",
"billingDay": 15,
"highestInvoiceTerm": 1,
"created": "2024-08-01 15:01:00.000",
"created": "2024-08-01T15:01:00.000Z",
"ovPayTokenId": 1337,
"contractVersions":
[
@ -781,7 +830,7 @@ paths:
"termDuration": "P0Y1M0D",
"billingDay": 15,
"highestInvoiceTerm": 1,
"created": "2024-08-01 15:01:00.000",
"created": "2024-08-01T15:01:00.000Z",
"ovPayTokenId": 1337,
"contractVersions":
[

View File

@ -1170,7 +1170,7 @@ paths:
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": false,
"isAuthorized": null,
"isAuthorized": false,
},
"_links":
{
@ -1209,6 +1209,10 @@ paths:
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/51compare",
"method": "POST",
},
"secure": {
"href": "/tokens/securetoken",
"method": "POST"
}
},
},
],
@ -1597,6 +1601,22 @@ paths:
"birthdate": null,
"photo": null,
},
"tatSecurity": {
"isSecured": true,
"isAuthorized": false,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
"authorize":
{
"href": "/tokens/authorizetoken",
"method": "POST"
}
}
},
{
"customerProfileId": 1,
@ -1623,6 +1643,13 @@ paths:
"isSecured": true,
"isAuthorized": true,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
}
},
{
"customerProfileId": 18,
@ -1649,6 +1676,13 @@ paths:
"isSecured": true,
"isAuthorized": true,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
}
},
{
"customerProfileId": 132,
@ -1675,6 +1709,13 @@ paths:
"isSecured": true,
"isAuthorized": true,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
}
},
{
"customerProfileId": 166,
@ -1701,9 +1742,21 @@ paths:
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
"isSecured": false,
"isAuthorized": false,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
"secure":
{
"href": "/tokens/securetoken",
"method": "POST"
}
}
},
{
"customerProfileId": 166,
@ -1730,6 +1783,13 @@ paths:
"isSecured": true,
"isAuthorized": true,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
}
},
{
"customerProfileId": 1,
@ -1756,6 +1816,13 @@ paths:
"isSecured": true,
"isAuthorized": true,
},
"_links":{
"self":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=1",
"method": "GET",
},
}
},
],
_links:
@ -1940,7 +2007,7 @@ paths:
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
"isAuthorized": false,
},
"_links":
{
@ -1979,6 +2046,12 @@ paths:
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/1/compare",
"method": "POST",
},
"authorize":{
{
"href": "/tokens/authorizetoken",
"method": "POST"
}
}
},
},
"_links":
@ -2074,7 +2147,11 @@ paths:
"autoReloadRegistration": null,
"ePurse": null,
"personalAccountData":
{ "name": null, "birthdate": null, "photo": null },
{ "name": null, "birthdate": null, "photo": null },gi
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":

View File

@ -10,6 +10,148 @@ servers:
tags:
- name: TAT Security
paths:
/tokens/status:
parameters:
- name: X-HTM-JWT-AUTH-HEADER
in: header
schema:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
- name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
in: header
schema:
type: integer
example: 323
required: false
description: The id of the customer Profile
- name: X-HTM-ROLE-HEADER
in: header
schema:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
- name: xTat
in: query
schema:
type: string
format : uuid
example: 5c4cba83-1ecd-46a4-b712-a8de0dcb7bbf
required: false
description: The xtat of the customerToken
- name: ovPayTokenId
in: query
schema:
type: integer
example: 1
required: false
description: The ovpay token id of a specific customer token
- name: serviceReferenceId
in: query
schema:
type: string
example: NLOV1234567ABCDEFG
required: false
description: The serviceReferencId found on the bankstatement for a given trip with a bankcard, required for an unknown EMV card
- name: amount
in: query
schema:
type: integer
example: 0
required: false
description: The amount of the value of the bankstatement in cents, required for an unknown EMV card
- name: ovpasNumber
in: query
schema:
type: string
example: OV34567
required: false
description: The number of the ovpas, required for an unknown Ovpas card
- name: verificationCode
in: query
schema:
type: string
example: HL78
required: false
description: The 4 digit verificationCode found on the backside of the Ovpas, required for an unknown Ovpas card
get:
tags:
- TAT Security
summary: Check the status of the security and authorization status of the given token
description: Check the status of the security and authorization status of the given token, check anonymous tokenDB if no customer headers are supplied otherwise check customer tokenDB
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TokenStatusResponse"
examples:
isSecuredandnotAuthorized:
summary: Token is secured but HTM is not authorized
description: Token is secured but HTM is not authorized
value:
isSecured: true
isAuthorized: false
xTat: 12da8f2a-6390-408a-94eb-a6701b5daf27
_links: {
"authorize": {
"href": "/tokens/authorizetoken",
"method": "POST"
}
}
notSecuredandnotAuthorized:
summary: Token is not secured but HTM is not authorized
description: Token is not secured but HTM is not authorized
value:
isSecured: false
isAuthorized: false
xTat: 12da8f2a-6390-408a-94eb-a6701b5daf27
_links: {
"secure": {
"href": "/tokens/securetoken",
"method": "POST"
}
}
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
Missing Parameters:
value:
status: 400
title: Missing Mandatory Parameter
detail: Required parameter {0} is missing.
Invalid Parameters:
value:
status: 400
title: Invalid Parameter
detail: Required parameter {0} is invalid.
"404":
description: Not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
TAT not found:
value:
status: 404
title: Not Found
detail: XTAT Account Not Found
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
error: An unknown error has occurred
/tokens/securetoken:
parameters:
- name: X-HTM-JWT-AUTH-HEADER
@ -50,7 +192,7 @@ paths:
emailAddress: stasjo@htm.nl
Without customer account:
value:
xtat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
xTat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
emailAddress: stasjo@htm.nl
responses:
"200":
@ -60,10 +202,14 @@ paths:
schema:
$ref: "#/components/schemas/EmailNotPreApprovedResponse"
example:
uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
recipient: xxxxxx.user@gmail.com
key: 123456789123456789123456789abcde
description: OTP Sent
_links: {
"verifyotp": {
"href": "/tokens/verifyotp",
"method": "POST"
}
}
"400":
description: Bad Request
content:
@ -125,6 +271,111 @@ paths:
$ref: "#/components/schemas/ErrorResponse"
example:
error: An unknown error has occurred
/tokens/authorizetoken:
parameters:
- name: X-HTM-JWT-AUTH-HEADER
in: header
schema:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
- name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
in: header
schema:
type: integer
example: 323
required: false
description: The id of the customer Profile
- name: X-HTM-ROLE-HEADER
in: header
schema:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
post:
tags:
- TAT Authorization
summary: Request authorization for HTM to access the data secured by additional OV-pas security for a token either in profile or anonymous.
description: Request authorization for HTM to access the data secured by additional OV-pas security for a token either in profile or anonymous.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/AuthorizeTokenRequest"
examples:
With customer account:
value:
ovPayTokenId: 42
Without customer account:
value:
xTat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/EmailNotPreApprovedResponse"
example:
recipient: xxxxxx.user@gmail.com
description: OTP Sent
_links: {
"verifyotp": {
"href": "/tokens/verifyotp",
"method": "POST"
}
}
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
Missing Parameters:
value:
status: 400
title: Missing Mandatory Parameter
detail: Required parameter {0} is missing.
Invalid Parameters:
value:
status: 400
title: Invalid Parameter
detail: Required parameter {0} is invalid.
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
Unauthorized:
value:
status: 401
title: Unauthorized
detail: Invalid Access Token
"404":
description: Not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
TAT not found:
value:
status: 404
title: Not Found
detail: TAT Account Not Found
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
error: An unknown error has occurred
/tokens/verifyotp:
parameters:
- name: X-HTM-JWT-AUTH-HEADER
@ -150,7 +401,7 @@ paths:
description: The role of the HTM employee in the case of the SMP
post:
tags:
- TAT Security
- TAT Verification
summary: Submit an OTP for a triggered OTP flow.
description: |
Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or
@ -169,7 +420,7 @@ paths:
action: secure
OTP verification for TAT security authorization for anonymous token:
value:
xtat: 0f0defe8-828c-48e5-97e5-26d1d0179ef0
xTat: 0f0defe8-828c-48e5-97e5-26d1d0179ef0
otp: 123456
action: authorize
responses:
@ -257,22 +508,12 @@ components:
EmailNotPreApprovedResponse IS AN object THAT represents the response of
email pre-approval check.
properties:
uid:
type: string
description: A uid IS A unique identifier THAT is associated with the user.
example: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
recipient:
type: string
description: >-
A recipient IS A unique identifier THAT is associated with the TAT
owner.
example: xxxxxx.user@gmail.com
key:
type: string
description: >-
A key IS a 32 character string THAT uniquely identifies the OTP
session.
example: 123456789123456789123456789abcde
description:
type: string
description: >-
@ -285,7 +526,7 @@ components:
ovPayTokenId:
type: integer
example: 42
xtat:
xTat:
type: string
format: uuid
example: 6134db53-9ae5-41d1-a343-36656b60b510
@ -294,14 +535,24 @@ components:
format: email
example: stasjo@htm.nl
required:
- ovPayTokenId
- emailAddress
AuthorizeTokenRequest:
type: object
properties:
ovPayTokenId:
type: integer
example: 42
xTat:
type: string
format: uuid
example: 6134db53-9ae5-41d1-a343-36656b60b510
VerifyOtpRequest:
type: object
properties:
ovPayTokenId:
type: integer
example: 42
xtat:
xTat:
type: string
format: uuid
example: f3474452-e1d4-428c-b366-e5ad5965eb8c
@ -339,3 +590,28 @@ components:
detail:
type: string
description: A detail IS A string that provides more details about the error.
TokenStatusResponse:
type: object
description: >-
TokenStatusResponse IS AN object THAT represents the current state of the token in relation to the AGO security and authorization status of HTM.
required:
- isSecured
- isAuthorized
properties:
isSecured:
type: boolean
description: >-
Is the token secured in the national database (GBO)
example: false
isAuthorized:
type: boolean
description: >-
Does HTM have the authorization to access the secured data for this token, only applicable when isSecured equals True.
example: false
xTat:
type: string
format: uuid
description: >-
The xtat of the customerToken given when token is unknown for the customer
example: 883674e5-54c7-47d6-a3e3-8781f0d3ffea

View File

@ -6878,7 +6878,6 @@ components:
example: 11
PostOrder:
type: object
required:
properties:
externalOrderId:
type: string
@ -6919,7 +6918,8 @@ components:
Amount of the products to be delivered, in case of saldo quantity is used to define the amount of saldo to be charged in eurocents. If multiple GBO products are added, the same amount of customerTokens will be required.
example: 1
createdOn:
type: datetime
type: string
format: date-time
description: |-
Current datetime, moment client added orderLine to the order
example: "2024-03-22T09:00:00"
@ -6929,12 +6929,14 @@ components:
The orderLineId as known in an external sales system, used for reconcilliation
example: "MyOrderLine123"
validFrom:
type: datetime
type: string
format: date-time
description: |-
The moment the chosen product should be activated
example: "2024-03-30T09:00:00"
validUntil:
type: datetime
type: string
format: date-time
description: |-
Only required when a product does not have a fixed duration, otherwise it is calculated by the back end system
example: null
@ -6946,7 +6948,6 @@ components:
$ref: "#/components/schemas/PostVoucher"
PatchOrderLine:
type: object
required:
properties:
productId:
type: integer
@ -6955,10 +6956,12 @@ components:
type: integer
example: 1
validFrom:
type: datetime
type: string
format: date-time
example: "2024-03-30T09:00:00"
validUntil:
type: datetime
type: string
format: date-time
example: null
PostVoucher:
type: object

View File

@ -1,7 +1,7 @@
openapi: 3.0.1
info:
title: Service Engine APIs for HTM voucher suppliers
description: Service Engine APIs for HTM voucher suppliers, this means all instances responsible for supplying vouchers. These are NOT the CRUD APIs to the data hub. These are ALSO NOT the api's for sales touchpoints.
description: Service Engine APIs for HTM voucher suppliers, this means all instances responsible for supplying vouchers. These are NOT the CRUD APIs to the data hub. These are ALSO NOT the APIs for sales touchpoints.
version: "1.0"
servers:
- url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0
@ -24,15 +24,6 @@ paths:
When a requiredProduct is configured, all attributes of the requiredProduct are also prerequisites for redeeming the voucher; thus they do not need to also be configured for the voucher definition. The requiredProduct itself is the single source of truth for this; and voucher definitions do not need to be updated if the requirements of the requiredProduct change. For example, if the requiredProduct requires an OVpay token, an OVpay token is automatically required to redeem issued vouchers.
parameters:
- name: touchpointId
in: query
required: false
description: |
Filter the voucher definitions on a specific touchpointId. This means that only voucher definitions with active selling periods for the specified touchpoint are returned.
This query parameter is only intended for administrative purposes, since the touchpoint associated with the access token used in the request is used to determine which voucher definitions are returned. This query parameter can be used to retrieve voucher definitions for other touchpoints within the same retailer, for example to retrieve voucher definitions for a specific sales touchpoint that is different from the calling touchpoint.
schema:
type: integer
example: 12
- name: productId
in: query
required: false
@ -206,18 +197,15 @@ paths:
/issuedvouchers:
get:
summary: Get a list of issued vouchers that were issued for a specific touch point
description:
Retrieve all issued vouchers for a specific touchpoint. This means that only vouchers that were issued by a touchpoint within the same retailer as the calling touchpoint are returned.
parameters:
- name: touchpointId
in: query
required: false
description: |-
Filter the issued vouchers on a specific touchpointId. This means that only vouchers that were issued by the specified touchpoint are returned.
This query parameter is only intended for administrative purposes, since the touchpoint associated with the access token used in the request is used to determine which issued vouchers are returned. This query parameter can be used to retrieve issued vouchers for other touchpoints within the same retailer, for example to retrieve issued vouchers for a specific sales touchpoint that is different from the calling touchpoint.
schema:
type: integer
example: 12
Retrieve all issued vouchers that match the given query parameters. \
At least on of the following query parameters should be provided:
- `issuedVoucherId` (internal and globally unique ID);
- `voucherCode` (code that the customer uses for redeeming the voucher, can be reissued as long as only one instance is active at the same time);
- `productId` (the productId of the voucher definition).
When a voucher code has been issued multiple times, all issuedvouchers with the same voucher code will be returned, together with their statuses.
parameters:
- name: issuedVoucherId
in: query
required: false
@ -416,6 +404,22 @@ paths:
}
]
}
"400":
description: Bad request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/rfc9457"
examples:
Missing required query parameters:
summary: Missing required query parameters
value:
{
"type": "https://example.com/probs/bad-request",
"title": "Missing required query parameters",
"detail": "At least one of the following query parameters should be provided: issuedVoucherId, voucherCode, or productId.",
"instance": "/issuedvouchers"
}
"403":
description: Forbidden
content:
@ -466,10 +470,20 @@ paths:
}
post:
summary: Issue a voucher for a specific voucher definition
description: |
Issue a voucher for a specific voucher definition. Vouchers can only be issued on a one-by-one basis, so that it is always clear what voucher code has been issued for specific voucher claims (which by itself my not uniquely identify the voucher; however the voucher code is guaranteed to be unique). The voucher can only be issued if the calling touchpoint (recognized by the access token) has an active selling period for the voucher definition (recognized by the productId).\
The \"fromInclusive\" and \"untilInclusive\" fields specify the date-time range in which the voucher can be redeemed by the customer. This has nothing to do with the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).\
description: |-
Issue a voucher for a specific voucher definition. Vouchers can only be issued on a one-by-one basis, so that it is always clear what voucher code has been issued for specific voucher claims (which by itself may not uniquely identify the voucher; however the voucher code is guaranteed to be unique).\
The voucher can only be issued if the calling touchpoint (recognized by the access token) has an active selling period for the voucher definition (recognized by the productId).
When providing a voucher code, the supplier is allowed to re-use a voucher code that has already been issued, but only if the previously issued voucher is not active anymore.\
This means that a voucher code can only be re-used once the previous instance has a `voucherStatus` of "revoked" or "expired".\
Redeemed is NOT a valid end-state, as this voucher might still refer to an active travel product (which can be revoked by revoking the voucher).
The `fromInclusive` and `untilInclusive` fields specify the date-time range in which the voucher can be redeemed by the customer.\
This has nothing to do with the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
If the voucher definition contains mandatoryCustomerDataItems, a value (to be checked against customer input when redeeming the voucher) has to be provided for each of these items.
A newly issued voucher will always receive the status "new". Vouchers can only be redeemed after they have been explicitly set to the status "issued" (via `PATCH /issuedvouchers/{issuedVoucherId}`), for example when the customer receives the actual voucher code.
tags:
- Vouchers
requestBody:
@ -481,7 +495,9 @@ paths:
examples:
Issue a voucher and supply own voucher code:
summary: Issue a voucher and supply own voucher code
description: This allows the voucher supplier to supply its own voucher code, which can be useful if the supplier already has its own (internal or external) source for voucher codes. The supplied voucher code must be unique - if this code is already in use, the request will fail.
description: |-
This allows the voucher supplier to supply its own voucher code, which can be useful if the supplier already has its own (internal or external) source for voucher codes.\
The supplied voucher code must be unique (or a previous instance must be revoked/expired, see main endpoint description).
value:
{
"voucherCode": "HTM-A7J-128-PYT",
@ -498,12 +514,21 @@ paths:
}
Issue a voucher and receive a voucher code (generated by ABT backend) in response:
summary: Issue a voucher and receive a voucher code (generated by ABT backend) in response
description: If the supplier is not able to generate its own unique voucher codes, it can issue a voucher without supplying any voucher code - the ABT backend will then receive a unique voucher code and return it in response.
description: |-
If the supplier is not able to generate its own unique voucher codes, it can issue a voucher without supplying any voucher code.\
The ABT backend will then generate a unique voucher code and return it in response.
value:
{
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 264
"productId": 264,
"voucherClaims":
[
{
"mandatoryCustomerDataItemId": 8,
"value": "1980-06-31",
}
],
}
responses:
"201":
@ -521,7 +546,7 @@ paths:
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
"voucherStatus": { "voucherStatusId": 1, "name": "new" },
"product":
{
"productId": 263,
@ -573,12 +598,12 @@ paths:
$ref: "#/components/schemas/rfc9457"
examples:
Voucher code already in use:
summary: Voucher code already in use
summary: Another active voucher instance already exists for this voucher code
value:
{
"type": "https://example.com/probs/bad-request",
"title": "Invalid voucher code",
"detail": "This voucher code is already in use.",
"detail": "Another active voucher instance already exists for this voucher code.",
"instance": "/issuedvouchers"
}
Missing mandatory voucher claims:
@ -614,6 +639,9 @@ paths:
summary: Update the status of an issued voucher
description: |-
Update the status of an issued voucher. Not every state change is allowed; an error will be returned if an invalid state change is attempted.\
If a redeemed voucher is revoked using this endpoint, it may also impact any active travel products that have been acquired using this voucher.\
This depends on specific business rules that are agreed upon with HTM.
Possible voucher statuses are:
- 1 = new
- 2 = issued
@ -630,8 +658,16 @@ paths:
schema:
$ref: "#/components/schemas/supplierTouchpointUpdateIssuedVoucherRequest"
examples:
Mark a voucher as issued:
summary: Mark a voucher as issued
description: Mark a voucher as issued. Only vouchers with a status of "issued" can actually be redeemed.
value:
{
"voucherStatusId": 2
}
Mark a voucher as revoked:
summary: Mark a voucher as revoked
description: Mark a voucher as revoked. This may also impact any active travel products that have been acquired using this voucher. This depends on specific business rules that are agreed upon with HTM.
value:
{
"voucherStatusId": 4

151
trip2.json Normal file
View File

@ -0,0 +1,151 @@
{ "tripId": 796727186, "tripVersion": 1, "tripStatus": "COMPLETE", "organisationIcon": "/icons/organisations/3.svg", "organisationId": "3", "organisationName": "HTM", "supersededByTripIds": [], "supersedesTripIds": [], "products": [ {
"productTemplateId": "30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" }
]
},
"productIcon": "001.jpg", "purchaseDateTime": "2026-04-02T12:38:28+02:00", "organisationName": "ProductRetailer HTM", "appliedValue": -125, "organisationId": "3", "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1" },
{
"productTemplateId": "N/A", "purchaseDateTime": "2025-07-09T12:39:27+02:00", "appliedValue": 139, "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8" },
{
"productTemplateId": "1:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 116, "appliedMetric": "FARE", "appliedValue": 116, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "2:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 23, "appliedMetric": "FARE", "appliedValue": 23, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "3:30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" },
{
"key": "nl-NL", "value": "Reis je regelmatig met HTM? Activeer dan HTM 90% Korting op je betaalpas of credit card en reis een week lang met korting!" },
{
"key": "en-US", "value": "Are you a regular traveler? Activate HTM 90% discount on your EMV card!" }
]
},
"validFrom": "2026-04-03T04:00:00+02:00", "validUntil": "2031-04-03T04:00:00+02:00", "organisationName": "Product Owner HTM", "weight": -125, "appliedMetric": "DISCOUNT", "appliedValue": -125, "organisationId": "3", "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"productCatalogVersionId": "PC-HTM:70", "xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1", "xpit": "1848597c-5ba9-4dab-8d9f-3948948706a1" }
],
"checkinTransactionTimestamp": "2026-04-20T16:59:48+02:00", "checkoutTransactionTimestamp": "2026-04-20T17:04:50+02:00", "checkinTransactionReference": "00310F92;29023;emvClt", "checkoutTransactionReference": "0030DBC1;30528;emvClt", "checkinLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"checkoutLocation": { "stopId": 2862, "stopName": { "items": [ {
"key": "nl-NL", "value": "Kalvermarkt-Stadhuis" },
{
"key": "en-US", "value": "Kalvermarkt-Stadhuis" }
]
},
"stopDesc": "Stop point2862", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"tokenType": "EMV-CLT", "transportType": "TRAM", "lineId": "17", "lineName": "Tram17", "networkId": "1", "networkName": "HTM netwerk", "currency": "EUR", "transportIcon": "/icons/transportTypes/tram.svg", "legs": [ {
"legId": 1614950977, "checkinTransactionTimestamp": "2026-04-20T16:59:48+02:00", "checkoutTransactionTimestamp": "2026-04-20T17:04:50+02:00", "checkinLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"checkoutLocation": { "stopId": 2862, "stopName": { "items": [ {
"key": "nl-NL", "value": "Kalvermarkt-Stadhuis" },
{
"key": "en-US", "value": "Kalvermarkt-Stadhuis" }
]
},
"stopDesc": "Stop point2862", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"baseRate": 139, "lineId": "17", "lineName": "Tram17", "networkId": "1", "networkName": "HTM netwerk", "fare": 14, "fareState": "CALCULATED", "currency": "EUR", "products": [ {
"productTemplateId": "30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" }
]
},
"productIcon": "001.jpg", "purchaseDateTime": "2026-04-02T12:38:28+02:00", "organisationName": "ProductRetailer HTM", "appliedValue": -125, "organisationId": "3", "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1" },
{
"productTemplateId": "N/A", "purchaseDateTime": "2025-07-09T12:39:27+02:00", "appliedValue": 139, "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8" },
{
"productTemplateId": "1:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 116, "appliedMetric": "FARE", "appliedValue": 116, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "2:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 23, "appliedMetric": "FARE", "appliedValue": 23, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "3:30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" },
{
"key": "nl-NL", "value": "Reis je regelmatig met HTM? Activeer dan HTM 90% Korting op je betaalpas of credit card en reis een week lang met korting!" },
{
"key": "en-US", "value": "Are you a regular traveler? Activate HTM 90% discount on your EMV card!" }
]
},
"validFrom": "2026-04-03T04:00:00+02:00", "validUntil": "2031-04-03T04:00:00+02:00", "organisationName": "Product Owner HTM", "weight": -125, "appliedMetric": "DISCOUNT", "appliedValue": -125, "organisationId": "3", "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"discountPercentage": 90, "productCatalogVersionId": "PC-HTM:70", "xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1", "xpit": "1848597c-5ba9-4dab-8d9f-3948948706a1" }
],
"appliedTimePeriods": [], "tariffJourneyStart": true, "topoDistance": 1161, "concessionId": "1", "appliedZones": [] }
],
"lastUpdatedTripDateTime": "2026-04-20T17:04:50+02:00", "fare": 14, "loyaltyOrDiscount": true, "supportCode": "pWM8Km6J8aHg5n", "tripVersionReason": "STRUCTURE", "checkinTransactionId": "00310F92-29023-emvClt-1776697188000", "checkoutTransactionId": "0030DBC1-30528-emvClt-1776697490000", "tariffVersionId": "HTM-CF1:278", "correlationId": "4bc7a040-71bf-4084-a61e-b2dd72092079", "createdAt": "2026-04-20T17:05:01.473+02:00", "entryTariffLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"traveledLines": [ {
"lineId": "17", "lineName": "Tram17" }
],
"tripFareNature": "FIXED", "paymentMethodId": "229a01ff-7bd9-4740-9b19-00637146a6ca", "paymentMethodMode": "PREPAID", "paymentMethodName": "EPURSE", "paymentProviderName": "TPURSE", "paymentProviderBusinessEntityId": "600027", "registryFragmentVersionId": "REG:27", "vehicleId": 5063, "xbot": "c85e34d6-f9c1-49c2-8574-59b37e0f3b8e" }