Author SHA1 Message Date
MirjamHTM 42ff41baea fixed indentation and added customerProfileId in POST body 2026-06-25 10:54:24 +02:00
MirjamHTM 699c633a4e changed name to securityTokens 2026-06-24 14:07:21 +02:00
MirjamHTM 95bc19d7ff semantics 2026-06-24 12:08:29 +02:00
MirjamHTM 8e77863480 simplified endpoint 2026-06-24 11:40:19 +02:00
MirjamHTM 07e1dc91e3 added security to the container specs 2026-06-24 11:30:18 +02:00
MirjamHTM 75531b4fdc fixed indentation 2026-06-24 11:12:19 +02:00
MirjamHTM 00a98a6178 things 2026-06-24 11:07:34 +02:00
MirjamHTM 937a0323ed added endpoints for the token vault 2026-06-23 14:47:22 +02:00
MirjamHTM ebee1178ef added container endpoint for creating token in vault 2026-06-23 14:32:51 +02:00
MirjamHTM 6e37b7c4fe removed unused tags 2026-06-23 14:08:07 +02:00
MirjamHTM a0ebde6ae2 Added swagger for container notifications 2026-06-23 13:47:00 +02:00
MirjamHTM 1f8e8f1381 Merge pull request 'feature/OVPAY-2485' (#63) from feature/OVPAY-2485 into develop
Reviewed-on: #63
2026-06-22 14:45:48 +00:00
bboterm 1f0481119c OVPAY-2485 - Typo in url. 2026-06-18 16:04:41 +02:00
bboterm 3d2885f2b8 OVPAY-2485 - Added support for anonymous TAT security. 2026-06-18 14:43:08 +02:00
bboterm 280d3b1fcd OVPAY-2485 - Extended token details response bodies with security. 2026-06-18 11:58:34 +02:00
bboterm f28a797b6b OVPAY-2485 - Improved TP requests. 2026-06-18 11:17:04 +02:00
bboterm 87d8f7df58 OVPAY-2485 - Updated OTP response body for TP. 2026-06-18 10:25:06 +02:00
bboterm 30e8860a39 OVPAY-2485 - Added schemas. 2026-06-17 16:26:39 +02:00
bboterm d18afcae8c OVPAY-2485 - Minor additions. 2026-06-17 16:23:11 +02:00
bboterm eb03aa04e6 OVPAY-2485 - Added SE endpoint for AGO OTP verification. 2026-06-17 16:22:38 +02:00
bboterm aca160f65c OVPAY-2485 - Added SE endpoint for AGO activation. 2026-06-17 16:08:06 +02:00
MirjamHTM 3f090c76b6 Merge pull request 'added additional Query params for issuedVoucher CRUD' (#62) from OVPAY2738-adjustment-CRUD-PP into develop
Reviewed-on: #62
2026-06-16 10:38:31 +00:00
MirjamHTM 25788e0976 added additional Query params for issuedVoucher CRUD 2026-06-16 12:01:37 +02:00
Max Martens 90bb7c11b5 Change mandatoryItem 6 (phone) to voucher 2026-06-11 12:19:15 +02:00
Max Martens 0c23571085 Remove whitespace 2026-06-11 12:12:11 +02:00
Max Martens f1a0850871 Now also for TP/SE endpoints 2026-06-11 12:11:05 +02:00
Max Martens cc8881b9d5 Add onlyVouchers queryParam and needsVoucher product attribute 2026-06-11 12:06:47 +02:00
Max Martens d484acbc69 Add required attributes that should always be present in every (valid) voucher definition 2026-06-11 11:14:10 +02:00
maxmartens e5a0b52d1b Merge pull request 'Updated OpenAPI spec for voucher supplier, with examples more relevant to the first usecase (ooievaarspas AOW) - this YAML is also shared with PASS devs' (#60) from feature/OVPAY-2545-vouchers into develop
Reviewed-on: #60
2026-06-08 08:45:46 +00:00
maxmartens 89833680db Merge branch 'develop' into feature/OVPAY-2545-vouchers 2026-06-08 08:44:17 +00:00
Max Martens ff225ea00c Merge branch 'feature/OVPAY-2545-vouchers' of https://git.integratielaag.nl/HTM/ovpay into feature/OVPAY-2545-vouchers 2026-06-03 19:06:25 +02:00
Max Martens bd870d0fa8 Added JSON schema and updated examples and error specs for supplier - tweaked OAS for TP 2026-06-03 19:06:17 +02:00
maxmartens 531eaa2ff6 Update src/openapi/products/SE-vouchers-TP.yaml
Fix some typos

Signed-off-by: Max Martens <m.martens@htm.nl>
2026-06-02 15:21:03 +00:00
Max Martens 7173bd3727 Finished JSON schema and all 3 relevant examples for TP vouchers OpenAPI spec (will also update vouchers supplier OpenAPI spec soon) 2026-06-01 11:17:22 +02:00
Max Martens a09ad1ad08 Process PR feedback, first version of issuedVoucher JSON schema 2026-06-01 10:40:28 +02:00
Max Martens f198c1633b Default false for isEmailVerified 2026-05-19 17:29:40 +02:00
maxmartens 5f7893b057 Merge pull request 'Reverted some links to the old/"standard" href structure, becasuse the links are buggy and not worth the effort to fix. Exception is GET /devices, that one is working' (#61) from feature/DHIL-5732-links into develop
Reviewed-on: #61
2026-05-12 14:56:25 +00:00
Max Martens 383d43122b Reverted some links to the old/"standard" href structure, becasuse the links are buggy and not worth the effort to fix. Exception is GET /devices, that one is working 2026-05-12 16:29:51 +02:00
Max Martens f8010560cc Tweak query param 2026-05-07 09:52:29 +02:00
Max Martens 69908f58b0 Finished updating, will be shared with pass devs in this state - I tweaked some stuff, needs to be discussed if this is final desired spec, but good enough to give pass devs a general idea 2026-05-06 22:44:55 +02:00
Max Martens 9fb20a491f WIP update spec with examples for Ooievaarspas-AOW (still need to finish POST/PATCH) 2026-05-06 08:28:21 +02:00
Max Martens 2fca37628e Only return deviceId in PATCH response to prevent extra internal GET call in PATCH logic 2026-05-05 15:12:20 +02:00
13 changed files with 3873 additions and 512 deletions

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -0,0 +1,403 @@
openapi: 3.0.3
info:
title: Integration layer APIs for token storage for ABT
description: >-
APIs that give business processes access to the security and authorization state of a token within the scope of HTM. In the backend this is connected to a container which handles the accessToken en refreshToken management for an OVpas as given by GBO.
version: "1.0"
servers:
- url: https://services.acc.api.htm.nl/abt/containertokens/1.0
security:
- oAuthSample: [profile]
tags:
- name: securitytokens
paths:
/securitytokens:
post:
tags:
- securitytokens
summary: Create a new security token entry in the vault
description: Create a new security token entry in the vault, if the customerProfileId has been supplied create in the customerToken DB otherwise in the AnonymousToken DB
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSecurityTokenBody"
examples:
token details:
value:
{
"xTat": "cf694905-7f76-4799-b0bc-490716921323",
"otpKey": "123456789123456789123456789abcde",
"customerProfileId": 12314
}
responses:
"201":
description: Created
"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
"409":
description: Conflict
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
TAT already exists:
value:
status: 409
title: Conflict
detail: Security Token already exists
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
Internal Server Error:
value:
status: 500
title: Internal Server Error
detail: An unknown error has occurred
/securitytokens/{xTat}/status:
parameters:
- name: xTat
in: path
schema:
type: string
example: 85dbeacc-b9aa-4d5b-bdec-9319010c597f
required: true
description: The xTat of the OVpastoken for which the status needs to be checked
- name: customerProfileId
in: query
schema:
type: integer
example: 323
required: false
description: The id of the customer Profile for which the request is being done, if customer has identified themselves
get:
tags:
- securitytokens
summary: Request the security and authorization status of an OV pas token
description: Request the security and authorization status of an OV pas token, if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SecurityTokenStatusResponse"
examples:
Not secured and not authorized :
summary: Not secured, not authorized
value:
{
"isAuthorized": false,
"isSecured": false
}
Secured and not authorized :
summary: Secured, not authorized
value:
{
"isAuthorized": false,
"isSecured": true
}
Secured and authorized :
summary: Secured and authorized
value:
{
"isAuthorized": true,
"isSecured": true
}
"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"
examples:
Internal Server Error:
value:
status: 500
title: Internal Server Error
detail: An unknown error has occurred
/securitytokens/{xTat}:
parameters:
- name: xTat
in: path
schema:
type: string
example: uuid
required: true
description: The xTat of the ovPastoken for which the status needs to be checked
- name: customerProfileId
in: query
schema:
type: integer
example: 323
required: false
description: The id of the customer Profile for which the request is being done, if customer has identified themselves
patch:
tags:
- securitytokens
summary: Validate the supplied OTP and secure and/or authorize the token
description: Validate the supplied OTP and secure and/or authorize the token if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SecurityValidateTokenBody"
examples:
token:
value:
{
"otp": "123456"
}
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SecurityTokenStatusResponse"
examples:
Not secured and not authorized :
summary: Not secured, not authorized
value:
{
"isAuthorized": false,
"isSecured": false
}
Secured and not authorized :
summary: Secured, not authorized
value:
{
"isAuthorized": false,
"isSecured": true
}
Secured and authorized :
summary: Secured and authorized
value:
{
"isAuthorized": true,
"isSecured": true
}
"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.
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
Validation failed:
value:
status: 422
title: OTP validation failed
detail: The supplied OTP could not be validated
"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"
examples:
Internal Server Error:
value:
status: 500
title: Internal Server Error
detail: An unknown error has occurred
components:
securitySchemes:
oAuthSample:
type: oauth2
description: This API uses OAuth 2 with the clientCredentials flow. [More info](https://api.example.com/docs/auth)
flows:
clientCredentials: # <---- OAuth flow( clientCredentials)
tokenUrl: https://identity.{env}.api.htm.nl/oauth2/token
scopes:
profile: "Access user profile"
schemas:
ErrorResponse:
description: Default response when an invalid request has been sent
type: object
properties:
status:
type: integer
description: >-
A status IS An integer that represents the HTTP status code of the
response.
example: 400
title:
type: string
description: A title IS A string that provides a brief summary of the error.
detail:
type: string
description: A detail IS A string that provides more details about the error.
CreateSecurityTokenBody:
description: Body for when the a new security token entry is created
type: object
required:
- xTat
- otpKey
properties:
xTat:
type : string
description: >-
Unique identifier for the GBO transit account
example: 03071794-482a-4168-b60f-84669a9e6a76
otpKey:
type : string
description: >-
Key used to validate the OTP at GBO
example: 123456789123456789123456789abcde
customerProfileId:
type : integer
description: >-
CustomerProfileId of the account requesting security or giving authorization
example: 123456
SecurityTokenStatusResponse:
description: Response for when the status of a token is requested
type: object
properties:
isSecured:
type: boolean
description: >-
Is the OVpas secured according to the GBO
example: false
isAuthorized:
type: boolean
description: >-
Does HTM have the authorization to access the secured the data of the OVpas
example: false
SecurityValidateTokenBody:
description: Body for when the a token entry is validated
type: object
required:
- otp
properties:
otp:
type : string
description: >-
OTP to be used to secure the token and retrieve the JWT at GBO
example: 123456
+145 -87
View File
@@ -380,7 +380,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
requestBody:
content:
application/json:
@@ -415,7 +415,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -429,7 +429,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
requestBody:
content:
application/json:
@@ -464,7 +464,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -478,7 +478,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
- name: customerPreferenceId
in: path
required: true
@@ -519,7 +519,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -533,8 +533,8 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
requestBody:
content:
application/json:
@@ -575,7 +575,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -589,7 +589,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
- name: addressId
in: path
required: true
@@ -634,7 +634,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -648,7 +648,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
- name: addressId
in: path
required: true
@@ -669,14 +669,14 @@ paths:
summary: Add a customer phone
description: >-
parameters:
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
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:
@@ -690,7 +690,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
requestBody:
content:
application/json:
@@ -728,7 +728,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -742,7 +742,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
- name: phoneId
in: path
required: true
@@ -754,7 +754,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/phoneEntity"
examples:
examples:
updateFullPhoneEntity:
value:
phone:
@@ -789,7 +789,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -803,7 +803,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
- name: phoneId
in: path
required: true
@@ -816,7 +816,7 @@ paths:
content:
application/json: {}
x-auth-type: Application & Application User
x-throttling-tier: Unlimited
x-throttling-tier: Unlimited
/customers/billinginformations:
get:
tags:
@@ -831,7 +831,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -845,7 +845,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
responses:
200:
description: OK
@@ -866,7 +866,7 @@ paths:
"billingInformationId": 1,
"iban": "NL••••••••••••1234",
"ascription": "J. Doe",
"alias": null,
"alias": null,
"created": "2024-10-20T17:05:52.000",
},
],
@@ -875,7 +875,7 @@ paths:
get:
tags:
- Customers
summary: Find direct debit mandates for a customer.
summary: Find direct debit mandates for a customer.
description: Find direct debit mandates for a customer.
parameters:
- name: X-HTM-JWT-AUTH-HEADER
@@ -884,7 +884,7 @@ paths:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
required: false
description: The JWT of a customer in case of touchpoint were customer logs in themselves
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:
@@ -898,7 +898,7 @@ paths:
type: string
example: Customer
required: false
description: The role of the HTM employee in the case of the SMP
description: The role of the HTM employee in the case of the SMP
responses:
200:
description: OK
@@ -914,12 +914,12 @@ paths:
[
{
"directDebitMandateId": 71,
"billingInformationId":
"billingInformationId":
{
"billingInformationId": 15,
"iban": "NL••••••••••••1234",
"ascription": "J. Doe",
"alias": null,
"alias": null,
"created": "2024-10-20T17:05:52.000",
},
"directDebitMandateType":
@@ -1081,6 +1081,10 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -1130,9 +1134,9 @@ paths:
},
},
}
OV pas without PAD:
summary: OV pas without PAD
description: OV pas without PAD
OV pas without PAD, without AGO:
summary: OV pas without PAD, without AGO
description: OV pas without PAD, without AGO
value:
{
"ovPayTokens":
@@ -1142,7 +1146,7 @@ paths:
"ovPayTokenId": 1,
"xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
"alias": "MyToken",
"tokenStatus":
@@ -1164,6 +1168,10 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": false,
"isAuthorized": null,
},
"_links":
{
"self":
@@ -1213,9 +1221,9 @@ paths:
},
},
}
OV pas with PAD and autoReload:
summary: OV pas with PAD and autoReload
description: OV pas with PAD and autoReload
OV pas with PAD, with autoReload, with AGO:
summary: OV pas with PAD, with autoReload, with AGO
description: OV pas with PAD, with autoReload, with AGO
value:
{
"ovPayTokens":
@@ -1225,7 +1233,7 @@ paths:
"ovPayTokenId": 1,
"xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
"alias": "MyToken",
"tokenStatus":
@@ -1287,6 +1295,10 @@ paths:
"ageFromInclusive": 4,
"ageToInclusive": 11,
},
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -1348,8 +1360,8 @@ paths:
"ovPayTokenId": 1,
"xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
"alias": "MyToken",
"tokenStatus":
{ "tokenStatusId": 2, "name": "Active" },
@@ -1385,6 +1397,10 @@ paths:
"ageFromInclusive": 4,
"ageToInclusive": 11,
},
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -1446,7 +1462,7 @@ paths:
"ovPayTokenId": 1,
"xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
"alias": "MyToken",
"tokenStatus":
@@ -1501,6 +1517,10 @@ paths:
"ageFromInclusive": 4,
"ageToInclusive": 11,
},
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -1562,7 +1582,7 @@ paths:
"ovPayTokenId": 1,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34567",
"alias": "MyToken",
"tokenStatus":
@@ -1583,7 +1603,7 @@ paths:
"ovPayTokenId": 6,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV54567",
"alias": "MyToken",
"tokenStatus":
@@ -1599,13 +1619,17 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
{
"customerProfileId": 18,
"ovPayTokenId": 13,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34547",
"alias": "MyToken",
"tokenStatus":
@@ -1621,13 +1645,17 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
{
"customerProfileId": 132,
"ovPayTokenId": 21,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34831",
"alias": "Mijn OV Pas",
"tokenStatus":
@@ -1643,13 +1671,17 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
{
"customerProfileId": 166,
"ovPayTokenId": 28,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV34984",
"alias": "Mijn OV Pas",
"tokenStatus":
@@ -1668,13 +1700,17 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
{
"customerProfileId": 166,
"ovPayTokenId": 115,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV54368",
"alias": "My retired token",
"tokenStatus":
@@ -1690,13 +1726,17 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
{
"customerProfileId": 1,
"ovPayTokenId": 118,
"xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
"tokenType":
{ "tokenTypeId": 2, "name": "OV-pas physical" },
{ "tokenTypeId": 2, "name": "OV-pas physical" },
"ovpasNumber": "OV98263",
"alias": "My found token",
"tokenStatus":
@@ -1712,6 +1752,10 @@ paths:
"photo": null,
},
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
},
],
_links:
@@ -1812,6 +1856,10 @@ paths:
"personalAccountData":
{ "name": null, "birthdate": null, "photo": null },
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -1890,6 +1938,10 @@ paths:
"personalAccountData":
{ "name": null, "birthdate": null, "photo": null },
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -2086,6 +2138,10 @@ paths:
"personalAccountData":
{ "name": null, "birthdate": null, "photo": null },
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -2149,6 +2205,10 @@ paths:
"personalAccountData":
{ "name": null, "birthdate": null, "photo": null },
"gboAgeProfile": null,
"tatSecurity": {
"isSecured": true,
"isAuthorized": true,
},
"_links":
{
"self":
@@ -2905,9 +2965,9 @@ paths:
summary: "**INTEGRATIELAAG** Transfer old OVpay token to new OVpay token."
description: |-
**Note that this directly calls the integratielaag and not the Service Engine!**
First transfers all personal account data (if present), then all products, of an existing OVpay token
First transfers all personal account data (if present), then all products, of an existing OVpay token
to a new OVpay token. The new token will also be persisted in the profile as a replacement
of the old token. This call is asynchronous, and progress can be monitored using the
of the old token. This call is asynchronous, and progress can be monitored using the
`/customers/tokens/transfer/responsestatus/*` endpoint.
tags:
- Token Replace v2
@@ -2920,9 +2980,9 @@ paths:
Transfer from a token without PAD to a new token:
summary: Transfer from a token without PAD to a new token
description: |
Transfer of a token without PAD to a new OVpay token. Note the new token in the request is always
identified by xTAT, regardless if the new token already exists in the customer profile. If the new
token does not exist in the customer profile, the user needs to provide an alias for the new token,
Transfer of a token without PAD to a new OVpay token. Note the new token in the request is always
identified by xTAT, regardless if the new token already exists in the customer profile. If the new
token does not exist in the customer profile, the user needs to provide an alias for the new token,
and it will be created in the customer profile.
value:
{
@@ -2936,11 +2996,11 @@ paths:
Transfer from a token with PAD to a new token without existing PAD:
summary: Transfer from a token with PAD to a new token without existing PAD
description: |
Transfer of a token with PAD to a new token by xTAT without existing PAD. Note how this request is
different, since it has an e-mail address on which the new PAD should be created. This request may
Transfer of a token with PAD to a new token by xTAT without existing PAD. Note how this request is
different, since it has an e-mail address on which the new PAD should be created. This request may
optionally provide an OTP for verification of th provided email address.
Also note the new token in the request is always identified by xTAT, regardless if the new token
already exists in the customer profile. If the new token does not exist in the customer profile, the
Also note the new token in the request is always identified by xTAT, regardless if the new token
already exists in the customer profile. If the new token does not exist in the customer profile, the
user needs to provide an alias for the new token, and it will be created in the customer profile.
value:
{
@@ -2957,8 +3017,8 @@ paths:
summary: Transfer from a token with PAD to a new token with existing PAD
description: |
Transfer of a token with PAD to a new token by xTAT with existing PAD.
Note that the new token in the request is always identified by xTAT, regardless if the new token
already exists in the customer profile. If the new token does not exist in the customer profile, the
Note that the new token in the request is always identified by xTAT, regardless if the new token
already exists in the customer profile. If the new token does not exist in the customer profile, the
user needs to provide an alias for the new token, and it will be created in the customer profile.
value:
{
@@ -2996,7 +3056,7 @@ paths:
Transfer of token started:
description: |
The transfer of the token was started successfully. The data of the token will be transferred
asynchronously. In the response body the consumer will find information on how to retrieve the
asynchronously. In the response body the consumer will find information on how to retrieve the
processing status.
value:
{
@@ -3038,7 +3098,7 @@ paths:
- Token Replace v2
summary: "**INTEGRATIELAAG** Get the status of the initiated token transfer process."
description: |
**Note that this directly calls the integratielaag and not the Service Engine!** Get the status of the
**Note that this directly calls the integratielaag and not the Service Engine!** Get the status of the
asynchronous token transfer processing.
responses:
"200":
@@ -3166,7 +3226,7 @@ paths:
examples:
Token transfer in progress:
description: |
The transfer of the token is still in progress. The response body shows the details of the
The transfer of the token is still in progress. The response body shows the details of the
processing status.
value:
{
@@ -3347,7 +3407,7 @@ paths:
in: query
description: External id of the device you want to get the purchased HTM products for.
schema:
type: string
type: string
- name: ovpayTokenId
in: query
description: Id of the OVpay-token you want to get the purchased HTM products for.
@@ -3380,9 +3440,9 @@ paths:
}
getTwoBarcodePurchasedProductsForDevice:
summary: Two BarcodeTicket purchased products, one PendingActivation and one Active
description: |-
The first ticket (PendingActivation) shows the 30-day range in which the ticket can be activated
(using the PATCH endpoint) in the validityStart and validityEnd fields. The second ticket (Active)
description: |-
The first ticket (PendingActivation) shows the 30-day range in which the ticket can be activated
(using the PATCH endpoint) in the validityStart and validityEnd fields. The second ticket (Active)
shows the actual validity period of the ticket after activation.
value:
{
@@ -3401,14 +3461,14 @@ paths:
"name": "Barcode",
},
"orderId": "501B17EF-36C4-4039-B92C-6517969B464E",
"orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
"orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
"ticketReference": "KJj43nejhbTxhrfef287",
"serviceId": "HTM-4321-7654-7659",
"issuedAt": "2026-03-21T09:01:35+01:00",
"activatedAt": null,
"blocked": false,
"cancelledAt": null,
"activateBefore": "2026-03-30",
"cancelledAt": null,
"activateBefore": "2026-03-30",
"validityStart": null,
"validityEnd": null,
"barcode": null,
@@ -3436,14 +3496,14 @@ paths:
"name": "Barcode",
},
"orderId": "501B17EF-36C4-4039-B92C-6517969B464E",
"orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
"orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
"ticketReference": "KJj43nejhbTxhr897287",
"serviceId": "HTM-1234-7654-8945",
"issuedAt": "2026-03-21T10:01:12+01:00",
"activatedAt": "2026-03-21T12:45:01+01:00",
"blocked": false,
"cancelledAt": null,
"activateBefore": null,
"cancelledAt": null,
"activateBefore": null,
"validityStart": "2026-03-21T12:45:01+01:00",
"validityEnd": "2026-03-21T14:45:01+01:00",
"barcode": "iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcAQAAAACsbTuBAAAFDElEQVR4Xu2bQa6rOhBEGzHwMEtgKewMyM5YCkvIkAGif50yyc/Tl770piZW9HSNywzqVlW3nXcjc83cusxnvsbMjBieuelf/bzGYz1jWCKmeGS+4g5grSwlz/IaI+JgEfzcvzQZo2yhxQgW7wDutLJrvVLzEInbVHLpM/tK5T7kHmNdbxssgqSipQj/0KLA24yqNvEWWRclpJKpefNgE7YZr/lj1eZ55wMYIWkUbZb7Xj/wH+BezvPkFJhQetmD+7AI2VuSEQMevANYESzqZh49VlEXIKOT7SDtseqnpz0Iyc2DJZezkEB5aaVKSvuF5FMwaIdB7wCGOgb5fFgus2wlKhPDpUiTlogr1tsHG7lfzcqYLlVnDHq6ylYn1OE54qd5cNC6aQxL0UQRy2YJJxCS8N4m273Gm4BJFAhzlytb5T4A0QrCYmUTrxd1bYNVgGqqPndH7vHwYqHLHf9cpO1pHJxU3Nq6vUbAVhXaocnTKO5cpK+4AViLitRwf8IQdYFwBkkKW7FzZxNh/AN/g5NHqXyed5MOz45kjkvKofpLYNwBrNBR/Dz9SKpTDkGd8CApZYonT24B7un56XKnoMeXkOBNHqTDk/NOmrrwyfIWYHe51O4kn4FBnfYbnHjqKuw3AGMreKOvC07DCAebHS5lAXWq5eKVA0HjYA2xM0MYCSMnqTqpx48ZVSmPTd15tT03AF+LVBuOgJoMqc2HL6Gy8nr1/K2DU+YpmKerd45fQ2ypzSFyq8coUM2D1yBksNWqOTWnjqvLpVYPvrt17f6BP+AaQk85zR4MarfHbAlSu/XhgGCJNg6mQNmASXnGhpZY+tKp93lywaY+SjcPhroCWx1BHFAnVemR81mdjEikWlllzYNrCM27bKVt7nInLplEnef6SfPFhb19MDmCbewcjtL/d7FwAzCqmShYzMd/qaPnp0AxV+SOpq5xMCnLZJOhZCNCZuIR4BWwL6un4luF5sE9N7CKXIJ2Zecncnt3vZ0it+hN7wNC6+DU/Ene1gj+lOOr4BDGilyT3D74NZ4OlYm2Xmx9t2rJN+kb7P3A/wUzV6lSQaonIoR3DUdy7vR1WQt782CrzrbbvTOdxwu2ZKy4MZXXflPzYJoVLg6GpbIVtLSb2JxduzEg+6Mm+R3AXECaHYRjG4nH2UIak7jSm9zXNQ9OLha2yhbUCT/vOA1VHUAGXpVuhpsHE7H7O0d6d2+i7rxeI2EVVMTm4wZg5vZUV2/nBUmoG5befZ0XERKkNg9O8zR9Rexls+WgldPRmTYHp90BrAIkqqYYnkmNGfvEY1E2Ijeu/3SQLKar1Q/8AX88eDqCRe3wZKJ89sVCRdaTZfvg/u8uFhoH14J0apHvil2rFwrUNtuDcXLOruNdvRoGB9ezgJXP2OrwN+mz8jl9lPab3Ob0NwDbVteFpEuX+7ylbHGdo5Oeny8y4vJgy2DniHhzQQp3c4yCkLwZvPbXk+INwKeqj6grVB/ha+dC88LVfec3zR/q2gYnlyO5GD+Kvfp03unruKCUygJb1e8HmwdbPp2pg8fgr3XYnE6YQGUWUp20Dz6hSgReznmXY3hLJ5A2ozJT9wN/gfVIEbzBsxvdYSneL571OV279S+/jubBiuCzAL5qt5xHPNHMcHgciSuD15rXbYMtJFbE1piEkEi0fPp6AoLX5Lvjt+paBvOIRQjSEEHaCX5BSP4DBSalHh4bB/8DVeIFt2RfPhQAAAAASUVORK5CYII=",
@@ -3499,7 +3559,7 @@ paths:
"barcodeTickets":[],
"vouchers":[]
}
}
}
getSingleVoucherPurchasedProductForCustomer:
summary: One voucher purchased product
value:
@@ -3523,7 +3583,7 @@ paths:
"voucherStatus": {
"voucherStatusId": 2,
"name": "issued"
},
},
"mandatoryCustomerDataItems":
[
{
@@ -3538,7 +3598,7 @@ paths:
}
]
}
}
}
/purchasedproducts/{purchasedProductId}:
parameters:
- name: X-HTM-JWT-AUTH-HEADER
@@ -3586,7 +3646,7 @@ paths:
value:
{
"status": "Active"
}
}
responses:
"200":
description: OK
@@ -3636,7 +3696,6 @@ paths:
"vouchers": []
}
}
/customers/devices:
post:
summary: Add a new device to a customer profile.
@@ -3813,7 +3872,7 @@ components:
customerProfileId:
type: integer
example: 1
customerPreference:
customerPreference:
$ref: "#/components/schemas/getCustomerPreference"
customerNumber:
type: integer
@@ -4014,12 +4073,12 @@ components:
customerPreferenceId:
type: integer
languageId:
type: integer
type: integer
customerStatusEntity:
type: object
properties:
customerStatusId:
type: integer
type: integer
OvPayTokensResponse:
type: object
required:
@@ -4298,7 +4357,7 @@ components:
items:
type: object
required:
- purchasedProductId
- purchasedProductId
- productId
- name
- status
@@ -4421,13 +4480,13 @@ components:
type: string
example: HTM 2 uurskaart
description: |-
The name of the originating HTM product definition.
The name of the originating HTM product definition.
Will be returned in the language as specified in the Accept-Language header or the customer profile. Otherwise defaults to NL.
description:
type: string
example: "Met deze kaart reis je 2 uur lang onbeperkt met de bussen en trams van HTM. Overstappen is natuurlijk toegestaan!"
description: |-
The description of the originating HTM product definition.
The description of the originating HTM product definition.
Will be returned in the language as specified in the Accept-Language header or the customer profile. Otherwise defaults to NL.
status:
type: string
@@ -4486,15 +4545,15 @@ components:
example: "2024-11-30"
description: Only present for barcode tickets that are not yet activated. Tickets can only be activated BEFORE this date.
validityStart:
description: |-
Only present for barcode tickets that have been activated. The date-time at which the ticket will become valid for traveling.
description: |-
Only present for barcode tickets that have been activated. The date-time at which the ticket will become valid for traveling.
The ticket will not be valid before this date/time.
type: string
format: date-time-offset
example: "2024-11-25T13:25:00+01:00"
validityEnd:
description: |-
Only present for barcode tickets that have been activated. The date-time at which the ticket will become invalid for traveling.
description: |-
Only present for barcode tickets that have been activated. The date-time at which the ticket will become invalid for traveling.
The ticket will not be valid after this date/time.
type: string
format: date-time-offset
@@ -4603,4 +4662,3 @@ components:
customerDataItem:
type: string
example: emailAddress
+341
View File
@@ -0,0 +1,341 @@
openapi: 3.0.1
info:
title: Service Engine APIs for TAT security
description: >-
Service Engine APIs for TAT security. These are NOT the raw GBO APIs to access TAT security at GBO directly.
To be used by touch points to get secure a TAT.
version: "2.0"
servers:
- url: https://services.acc.api.htm.nl/abt/touchpoint/2.0
tags:
- name: TAT Security
paths:
/tokens/securetoken:
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 Security
summary: Request additional OV-pas security for a token either in profile or anonymous.
description: Request additional OV-pas security for a token either in profile or anonymous
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SecureTokenRequest"
examples:
With customer account:
value:
ovPayTokenId: 42
emailAddress: stasjo@htm.nl
Without customer account:
value:
xtat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
emailAddress: stasjo@htm.nl
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/EmailNotPreApprovedResponse"
example:
uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
recipient: xxxxxx.user@gmail.com
key: 123456789123456789123456789abcde
description: OTP Sent
"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
"409":
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
TAT Already Secured:
value:
status: 409
title: Conflict
detail: TAT Already Secured
"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
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 Security
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
result of an AGO authorization flow. Since the backoffice behaves slightly different depending
on which use case is executed, the calling TP needs to provide an `action` in the request body.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/VerifyOtpRequest"
examples:
OTP verification for TAT security activation for token in customer account:
value:
ovPayTokenId: 42
otp: 123456
action: secure
OTP verification for TAT security authorization for anonymous token:
value:
xtat: 0f0defe8-828c-48e5-97e5-26d1d0179ef0
otp: 123456
action: authorize
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyOtpResponse'
examples:
Tat Secured:
value:
status: Success
description: TAT Secured
Tat Unsecured:
value:
status: Success
description: TAT Unsecured
Tat Authorized:
value:
status: Success
description: TAT Authorized
"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
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
error: An unknown error has occurred
components:
schemas:
unavailable:
type: object
GenerateTatOutput:
type: object
properties:
uid:
type: string
description: >-
An uid IS A unique identifier THAT is associated with the
user.
recipient:
type: string
description: >-
A recipient IS A unique identifier THAT is associated with the
TAT owner.
key:
type: string
description: >-
A key IS a 32 character string THAT uniquely identifies the
OTP session.
EmailNotPreApprovedResponse:
type: object
description: >-
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: >-
A description IS A string THAT describes the reason why the email is
not pre-approved.
example: OTP Sent
SecureTokenRequest:
type: object
properties:
ovPayTokenId:
type: integer
example: 42
xtat:
type: string
format: uuid
example: 6134db53-9ae5-41d1-a343-36656b60b510
emailAddress:
type: string
format: email
example: stasjo@htm.nl
required:
- ovPayTokenId
VerifyOtpRequest:
type: object
properties:
ovPayTokenId:
type: integer
example: 42
xtat:
type: string
format: uuid
example: f3474452-e1d4-428c-b366-e5ad5965eb8c
otp:
type: string
example: 123456
action:
type: string
example: secure
required:
- otp
- action
VerifyOtpResponse:
type: object
properties:
status:
type: string
example: Success
description:
type: string
example: TAT Secured
ErrorResponse:
description: Default response when an invalid request has been sent
type: object
properties:
status:
type: integer
description: >-
A status IS An integer that represents the HTTP status code of the
response.
example: 400
title:
type: string
description: A title IS A string that provides a brief summary of the error.
detail:
type: string
description: A detail IS A string that provides more details about the error.
+24 -153
View File
@@ -243,7 +243,7 @@ paths:
suffix: PhD
dateOfBirth: "2002-10-29"
emailAddresses: TEST@HTM.NL
isEmailVerified: True
isEmailVerified: false
addresses:
- addressId: 1
street: mystreet
@@ -332,14 +332,6 @@ paths:
user: user
timestamp: "2023-10-20T17:05:52.000+02:00"
correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
"method": "GET",
},
}
- customerProfileId: 12
customerNumber: 1000002
debtorNumber: DB100121
@@ -377,7 +369,7 @@ paths:
suffix: PhD
dateOfBirth: "2002-10-29"
emailAddresses: TEST@HTM.NL
isEmailVerified: False
isEmailVerified: false
address:
- addressId: 1
street: mystreet
@@ -467,32 +459,7 @@ paths:
user: user
timestamp: "2023-10-20T17:05:52.000+02:00"
correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=12",
"method": "GET",
},
}
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20",
"method": "GET",
},
"prev":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
"method": "GET",
},
"next":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=40",
"method": "GET",
},
}
href: "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20"
getCustomerActive:
summary: getCustomerActive
description: >-
@@ -526,7 +493,7 @@ paths:
suffix: PhD
dateOfBirth: "2002-10-29"
emailAddresses: TEST@HTM.NL
isEmailVerified: False
isEmailVerified: false
addresses:
- addressId: 1
street: mystreet
@@ -615,22 +582,7 @@ paths:
user: user
timestamp: "2023-10-20T17:05:52.000+02:00"
correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
"method": "GET",
},
}
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
"method": "GET",
},
}
href: https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20
getCustomerBlocked:
summary: getCustomerBlocked
description: >-
@@ -669,7 +621,7 @@ paths:
suffix: PhD
dateOfBirth: "2002-10-29"
emailAddresses: TEST@HTM.NL
isEmailVerified: True
isEmailVerified: false
addresses:
- addressId: 1
street: mystreet
@@ -758,22 +710,7 @@ paths:
user: user
timestamp: "2023-10-20T17:05:52.000+02:00"
correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
"method": "GET",
},
}
_links:
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
"method": "GET",
},
}
href: https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20
400:
description: Bad Request
content:
@@ -835,7 +772,7 @@ paths:
suffix: jr
dateOfBirth: "1970-01-01"
emailAddress: j.jansen@hatseflats.nl
isEmailVerified: False
isEmailVerified: false
addresses:
- street: Laan van Meerdervoort
houseNumber: 5
@@ -934,7 +871,7 @@ paths:
suffix: "jr",
dateOfBirth: "1970-01-01",
emailAddress: "TEST@TEST1.NL",
isEmailVerified: False
isEmailVerified: false
}
updateCompleteEntity:
value:
@@ -946,7 +883,7 @@ paths:
suffix: "jr",
dateOfBirth: "1970-01-01",
emailAddress: "TEST@TEST1.NL",
isEmailVerified: True
isEmailVerified: false
}
required: true
responses:
@@ -1438,13 +1375,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/getDevices"
examples:
updateDeviceResponse:
value:
deviceId: "5bedce29-af0c-4f3c-b182-2caa8a1f9377"
externalDeviceId: "7122a988-a00a-417d-a5b4-da2d91354976"
alias: "iPhone zakelijk"
$ref: "#/components/schemas/patchDeviceResponse"
security:
- default: []
@@ -1607,24 +1538,7 @@ paths:
"replacedByTokenId": 12,
},
],
"_links":
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=20",
"method": "GET",
},
"prev":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens",
"method": "GET",
},
"next":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=40",
"method": "GET",
},
},
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=20&limit=20"
}
/customers/{customerProfileId}/ovpaytokens:
post:
@@ -1943,9 +1857,10 @@ paths:
"created": "2024-10-20T17:05:52.000",
},
],
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/billingInformations?offset=20&limit=20"
}
getBillingInformationSingleSpecificCustomer:
summary: Get singel billing information entity for a specific customers
summary: Get single billing information entity for a specific customers
description: >-
Found one billing information matching the search parameters
value:
@@ -2135,59 +2050,7 @@ paths:
"updateTimestamp": "2024-03-22T08:55:00",
},
],
"_links":
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates",
"method": "GET",
},
"next":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20",
"method": "GET",
},
},
}
getDirectDebitMandateWithNextPageandPreviousPage:
value:
{
"directDebitMandates":
[
{
"directDebitMandateId": 71,
"customerProfileId": 12,
"billingInformationId": 51,
"directDebitMandateType":
{
"directDebitMandateTypeId": 1,
"name": "import",
"description": "import",
},
"created": "2024-03-22T08:55:00",
"mandateReference": "CORE01",
"mandateState": "SIGNED",
"updateTimestamp": "2024-03-22T08:55:00",
},
],
"_links":
{
"self":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20",
"method": "GET",
},
"prev":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates",
"method": "GET",
},
"next":
{
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=40",
"method": "GET",
},
},
"href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20&limit=20"
}
/billingInformation/{billingInformationId}/directdebitmandates:
post:
@@ -2843,7 +2706,7 @@ components:
emailAddress:
type: string
isEmailVerified:
type: string
type: boolean
postOvPayTokenResponse:
type: object
properties:
@@ -2857,6 +2720,14 @@ components:
type: array
items:
$ref: "#/components/schemas/getDeviceEntity"
patchDeviceResponse:
type: object
properties:
deviceId:
type: string
format: uuid
example: "b2c8a8c6-3d1c-4b6b-8f8d-3a6a1b6a1b6a"
getDeviceEntity:
type: object
properties:
+15
View File
@@ -313,6 +313,7 @@ paths:
{
"productId": 24,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30901",
@@ -429,6 +430,7 @@ paths:
{
"productId": 126,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -537,6 +539,7 @@ paths:
{
"productId": 119,
"parentProductId": 126,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30001",
@@ -652,6 +655,7 @@ paths:
{
"productId": 120,
"parentProductId": 126,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30001",
@@ -779,6 +783,7 @@ paths:
{
"productId": 49,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 2,
"choiceKey": "regio",
@@ -926,6 +931,7 @@ paths:
{
"productId": 109,
"parentProductId": 49,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 3,
"choiceKey": "allowedGboAgeProfiles",
@@ -1076,6 +1082,7 @@ paths:
{
"productId": 114,
"parentProductId": 109,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -1226,6 +1233,7 @@ paths:
{
"productId": 115,
"parentProductId": 109,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -1377,6 +1385,7 @@ paths:
{
"productId": 116,
"parentProductId": 115,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "33615",
@@ -1526,6 +1535,7 @@ paths:
{
"productId": 117,
"parentProductId": 115,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "33615",
@@ -1679,6 +1689,7 @@ paths:
{
"productId": 112,
"parentProductId": 49,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 3,
"choiceKey": "allowedGboAgeProfiles",
@@ -2150,6 +2161,10 @@ components:
parentProductId:
type: integer
example: 1
needsVoucher:
type: boolean
description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
example: false
layerInfo:
$ref: '#/components/schemas/LayerInfoResponse'
fikoArticleNumber:
+15
View File
@@ -313,6 +313,7 @@ paths:
{
"productId": 24,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30901",
@@ -429,6 +430,7 @@ paths:
{
"productId": 126,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -537,6 +539,7 @@ paths:
{
"productId": 119,
"parentProductId": 126,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30001",
@@ -652,6 +655,7 @@ paths:
{
"productId": 120,
"parentProductId": 126,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "30001",
@@ -779,6 +783,7 @@ paths:
{
"productId": 49,
"parentProductId": null,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 2,
"choiceKey": "regio",
@@ -926,6 +931,7 @@ paths:
{
"productId": 109,
"parentProductId": 49,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 3,
"choiceKey": "allowedGboAgeProfiles",
@@ -1076,6 +1082,7 @@ paths:
{
"productId": 114,
"parentProductId": 109,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -1226,6 +1233,7 @@ paths:
{
"productId": 115,
"parentProductId": 109,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 1,
"choiceKey": "isRenewable",
@@ -1377,6 +1385,7 @@ paths:
{
"productId": 116,
"parentProductId": 115,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "33615",
@@ -1526,6 +1535,7 @@ paths:
{
"productId": 117,
"parentProductId": 115,
"needsVoucher": false,
"layerInfo": null,
"fikoArticleNumber": "1234",
"gboPackageTemplateId": "33615",
@@ -1679,6 +1689,7 @@ paths:
{
"productId": 112,
"parentProductId": 49,
"needsVoucher": false,
"layerInfo": {
"layerInfoId": 3,
"choiceKey": "allowedGboAgeProfiles",
@@ -2150,6 +2161,10 @@ components:
parentProductId:
type: integer
example: 1
needsVoucher:
type: boolean
description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
example: false
layerInfo:
$ref: '#/components/schemas/LayerInfoResponse'
fikoArticleNumber:
+264 -70
View File
@@ -1,17 +1,17 @@
openapi: 3.0.1
info:
title: Service Engine APIs for HTM voucher for sales Touchpint
description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the api's for sales touchpoints.
title: Service Engine APIs for HTM voucher for sales Touchpoint
description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the APIs for sales touchpoints.
version: "1.0"
servers:
- url: https://services.acc.api.htm.nl/abt/abtvouchersTouchpoint/1.0
paths:
/issuedvouchers/{voucherCode}:
get:
summary: Get details of a voucher, that was issued for a specific touch point
summary: Get details of a voucher, that was issued for a specific touchpoint
description:
Get details of an issued voucher for a specific touch point. This means that only products that the calling touch point is allowed to see or sell
(i.e. has active sellingPeriods for touchPointId of the calling touch point) are returned.
Get details of an issued voucher for a specific touchpoint. This means that only products that the calling touchpoint is allowed to see or sell
(i.e. has active sellingPeriods for touchPointId of the calling touchpoint) are returned.
parameters:
- name: voucherCode
in: path
@@ -28,98 +28,132 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/unavailable"
$ref: "#/components/schemas/salesTouchpointIssuedVoucherResponse"
examples:
Voucher for a product with required attributes:
summary: Voucher for a single product with required attributes
Voucher that grants a voucher-only product for free:
summary: Voucher that grants a voucher-only product for free
description: |-
Voucher that grants a product (that can only be acquired via a voucher) for free.
In this case, the voucher has an amountInclTax of 0. If the requiredProduct has a
non-zero sellingPrice (amountInclTax), the difference between sellingPrice and
voucher amountInclTax represents the granted discount. If the requiredProduct has
a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax.
value:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "VOUCHER123",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 1, "name": "New" },
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
"product":
{
"productId": 263,
"productName": "HTM-80001",
"productDescription": "10 euro korting op Regiovrij maand.",
"productCategory":
{
"productCategoryId": 9,
"isTravelProduct": false,
"name": "Voucher",
},
"amountInclTax": -1000,
"productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "Voucher voor AOW-ers in Den Haag met een Ooievaarspas, die ingewisseld kan worden voor het product \"Ooievaarspas voor AOW-ers in Den Haag\"",
"amountInclTax": 0,
"requiredProducts":
[
{
"productId": 126,
"productName": "HTM-30001",
"productDescription": "Regiovrij maand.",
"productId": 982,
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
"productCategory":
{
"productCategoryId": 2,
"isTravelProduct": true,
"name": "Afgekocht reisrecht",
},
"amountInclTax": 0,
"_links":
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126",
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/982",
"method": "GET",
},
},
},
],
"_links":
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
"method": "GET",
},
},
]
},
"mandatoryCustomerDataItems":
[
{
"mandatoryCustomerDataItemId": 8,
"customerDataItem": "padBirthDate",
},
{
"mandatoryCustomerDataItemId": 4,
"customerDataItem": "emailAddress",
},
],
"customerDataItem": "padBirthDate"
}
]
}
Voucher for a whole order:
summary: Voucher for a whole order
Voucher that grants a hybrid product for a reduced price:
summary: Voucher that grants a hybrid product for a reduced price
description: |-
Voucher that grants a hybrid product (that can be acquired via voucher or via ordinary order flow)
for a reduced price. In this case, the voucher has an amountInclTax > 0, which dictates the (modified)
total amount that needs to be paid for said product. If the requiredProduct has a
non-zero sellingPrice (amountInclTax), the difference between sellingPrice and
voucher amountInclTax represents the granted discount. If the requiredProduct has
a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax./
Specifically, in this example, the product "HTM 20% Korting" can be purchased for 1 euro instead of 5 euro.
value:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "VOUCHER123",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 1, "name": "New" },
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
"product":
{
"productId": 263,
"productName": "HTM-80002",
"productDescription": "10 euro korting op je gehele winkelmand.",
"productCategory":
{
"productCategoryId": 9,
"isTravelProduct": false,
"name": "Voucher",
},
"amountInclTax": -1000,
"requiredProducts": [],
"_links":
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
"method": "GET",
},
},
"productId": 264,
"productName": "Kortingsvoucher HTM 20% Korting ",
"productDescription": "Voucher waarmee het product \"HTM 20% Korting\" voor een lagere prijs kan worden aangeschaft.",
"amountInclTax": 100,
"requiredProducts":
[
{
"productId": 984,
"productName": "HTM 20% Korting",
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
"productCategory":
{
"productCategoryId": 1,
"isTravelProduct": true,
"name": "Kortingsabonnement",
},
"amountInclTax": 500,
"_links":
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/984",
"method": "GET",
},
},
},
]
},
"mandatoryCustomerDataItems": [],
"mandatoryCustomerDataItems": []
}
Voucher that grants a discount for a whole order:
summary: Voucher that grants a discount for a whole order
description: |-
Voucher that grants a discount for a whole order. In this case, no requiredProduct is specified, and
the voucher has an amountInclTax < 0. The (negative) amountInclTax dictates the value of the voucher,
that is subtracted from the total order value as a discount (with a minimum order total of 0).
value:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
"product":
{
"productId": 265,
"productName": "Voucher 10 euro korting",
"productDescription": "Voucher die 10 euro korting geeft op je gehele winkelmand.",
"amountInclTax": -1000,
"requiredProducts": []
},
"mandatoryCustomerDataItems": []
}
"403":
description: Forbidden
@@ -137,20 +171,20 @@ paths:
"detail": "You do not have permission to access this resource.",
"instance": "/issuedvouchers",
}
"404":
description: Not found
"400":
description: Bad request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/rfc9457"
examples:
Voucher not found:
summary: Voucher not found
Invalid voucher code:
summary: Invalid voucher code
value:
{
"type": "https://example.com/probs/not-found",
"title": "Voucher not found",
"detail": "The voucher with code VOUCHER123 does not exist.",
"type": "https://example.com/probs/bad-request",
"title": "Invalid voucher code",
"detail": "No valid voucher found for code VOUCHER123.",
"instance": "/issuedvouchers",
}
"500":
@@ -176,6 +210,166 @@ components:
scheme: bearer
bearerFormat: JWT
schemas:
salesTouchpointIssuedVoucherResponse:
type: object
required:
- issuedVoucherId
- voucherCode
- fromInclusive
- untilInclusive
- voucherStatus
- product
- mandatoryCustomerDataItems
properties:
issuedVoucherId:
type: string
description: The unique (technical) identifier of the issued voucher instance.
example: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
voucherCode:
type: string
description: The voucher code that is shared with the customer and uniquely identifies this voucher.
example: "HTM-A7J-128-PYT"
fromInclusive:
type: string
format: date-time-offset
description: |-
The date and time the voucher becomes valid for redemption. This has nothing to do with
the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
example: "2024-10-04T00:00:00.000+02:00"
untilInclusive:
type: string
format: date-time-offset
description: |-
The date and time the voucher becomes invalid for redemption. This has nothing to do with
the maximum allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
example: "2024-11-04T00:00:00.000+01:00"
voucherStatus:
type: object
required:
- voucherStatusId
- name
description: |-
The current status of the voucher. Can be any of the following:
- 1 = new
- 2 = issued
- 3 = redeemed
- 4 = revoked
- 5 = expired
- 6 = pendingRedemption
properties:
voucherStatusId:
type: integer
example: 2
name:
type: string
example: "issued"
product:
type: object
description: The "product" referencing the voucher definition that this voucher instance is based on
required:
- productId
- productName
- productDescription
- amountInclTax
properties:
productId:
type: integer
example: 263
productName:
type: string
example: Voucher Ooievaarspas-product AOW
productDescription:
type: string
example: |-
Voucher voor AOW-ers in Den Haag met een Ooievaarspas, die ingewisseld kan worden
voor het product "Ooievaarspas voor AOW-ers in Den Haag".
amountInclTax:
type: integer
description: |-
When combined with a requiredProduct, the (positive or zero) amountInclTax dictates
the (modified) total amount that needs to be paid for said product. When the requiredProduct
has a sellingPrice > 0, the difference between sellingPrice and voucher amountInclTax
represents the granted discount.
When not combined with a required product, the (negative) amountInclTax dictates
the value of the voucher, that is subtracted from the total order value as a discount
(with a minimum order total of 0).
example: 0
requiredProducts:
type: array
description: |-
Currently, only one requiredProduct is supported and thus, this array can contain at
most one element.
items:
type: object
required:
- productId
properties:
productId:
type: integer
example: 892
productName:
type: string
example: "Ooievaarspas voor AOW-ers in Den Haag"
productDescription:
type: string
example: "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
productCategory:
type: object
required:
- productCategoryId
- isTravelProduct
- name
properties:
productCategoryId:
type: integer
example: 2
isTravelProduct:
type: boolean
example: true
name:
type: string
example: "Afgekocht reisrecht"
amountInclTax:
type: integer
description: |-
Selling price of the product in cents (including tax, if applicable) that is
currently active for the calling touchpoint. When 0, the product is free of charge.
example: 0
imageReference:
type: string
description: Can be a URL or a base64 encoded image
example: https://www.htm.nl/nog-onbekende-productafbeelding
_links:
type: object
properties:
get_details:
type: object
description: Link to get more details for the product that this voucher instance applies to
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/touchpoint/1.0/products/982
method:
type: string
example: GET
mandatoryCustomerDataItems:
type: array
description: |-
List of mandatory customer data items that are required to redeem this voucher.\
The values provided for these data items may be checked against allowed values as provided by the voucher issuer.
items:
type: object
required:
- mandatoryCustomerDataItemId
- customerDataItem
properties:
mandatoryCustomerDataItemId:
type: integer
example: 8
customerDataItem:
type: string
example: padBirthdate
unavailable:
type: object
rfc9457:
File diff suppressed because it is too large. Load diff
@@ -1553,6 +1553,9 @@ components:
- productCategoryId: 8
name: Saldo
isTravelProduct: true
- productCategoryId: 9
name: Voucher
isTravelProduct: false
type: array
items:
$ref: '#/components/schemas/productCategoryGetEntity'
@@ -1811,7 +1814,7 @@ components:
- mandatoryCustomerDataItemId: 5
customerDataItem: address
- mandatoryCustomerDataItemId: 6
customerDataItem: phone
customerDataItem: voucher
- mandatoryCustomerDataItemId: 7
customerDataItem: ovPayToken
- mandatoryCustomerDataItemId: 8
+28
View File
@@ -46,6 +46,13 @@ paths:
when false, return only non-archived products (isArchived = false).
schema:
type: boolean
- name: onlyVouchers
in: query
required: false
description: |-
When omitted, defaults to false (i.e. return all normal products that are NOT voucher definitions); when true, return only voucher definitions
schema:
type: boolean
responses:
'200':
description: OK
@@ -387,6 +394,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "30901",
"productName": "HTM pilot 90% korting",
"productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -474,6 +482,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "30901",
"productName": "HTM pilot 90% korting",
"productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -560,6 +569,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "30901",
"productName": "HTM pilot 90% korting",
"productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -680,6 +690,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "33610",
"productName": "HTM Regio Vrij DH73",
"productDescription": "Voor een vast bedrag onbeperkt reizen met EBS, HTM en RET in het gekozen gebied in de regio Rotterdam Den Haag.",
@@ -866,6 +877,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "30901",
"tapConnectProductCode": null,
"productName": "HTM pilot 90% korting",
@@ -1028,6 +1040,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "30901",
"tapConnectProductCode": null,
"productName": "HTM pilot 90% korting",
@@ -1270,6 +1283,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": "33610",
"tapConnectProductCode": null,
"productName": "HTM Regio Vrij DH73",
@@ -1475,6 +1489,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": null,
"tapConnectProductCode": null,
"productName": "IBAN wijzigen functioneel product",
@@ -1672,6 +1687,7 @@ paths:
"fikoArticleNumber": "1234",
"isValid": true,
"isArchived": false,
"needsVoucher": false,
"gboPackageTemplateId": null,
"tapConnectProductCode": null,
"productName": "OV-pas saldo (1 eurocent)",
@@ -2775,6 +2791,10 @@ components:
type: boolean
description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
example: false
needsVoucher:
type: boolean
description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
example: false
gboPackageTemplateId:
type: string
example: '30901'
@@ -3132,6 +3152,10 @@ components:
type: boolean
description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
example: false
needsVoucher:
type: boolean
description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
example: false
gboPackageTemplateId:
type: string
description: >-
@@ -3503,6 +3527,10 @@ components:
type: boolean
description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
example: false
needsVoucher:
type: boolean
description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
example: false
gboPackageTemplateId:
type: string
description: >-
@@ -1102,6 +1102,12 @@ paths:
format: uuid
example: 058a1af7-897f-45d5-b691-9cc9161e387f
description: The id of the purchased product.
- in: query
name: productId
schema:
type: integer
example: 1
description: The id of the product and the issuedVouchers related to it
- in: query
name: voucherCode
schema:
@@ -1117,6 +1123,14 @@ paths:
explode: false
required: false
description: The moest recent status id of the voucher.
- in: query
name: orderBy
schema:
type: string
enum: [PurchasedProductCreatedOn, PurchasedProductLastUpdatedOn]
explode: false
required: false
description: The ordering of the issuedVouchers in the list
responses:
"200":
description: OK
View File
Whitespace-only changes.