HTM/ovpay
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases 1 Wiki Activity

WIP update spec with examples for Ooievaarspas-AOW (still need to finish POST/PATCH)

Browse Source
This commit is contained in:
Max Martens 2026-05-06 08:28:21 +02:00
parent 8a10320c26
commit 9fb20a491f
1 changed files with 70 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
src/openapi/products/SE-vouchers-supplier.yaml
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 vouchers 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 api's for sales touchpoints.
version: "1.0"
servers:
- url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0
@ -10,32 +10,39 @@ paths:
get:
tags:
- Vouchers
summary: Get a list of all voucher definitions that a touch point is allowed to issue
summary: Get a list of all voucher definitions that a touchpoint is allowed to issue
description: |-
Get a list of all voucher definitions that the calling touch point is allowed to issue.
Essentially, this means that only products that have active sellingPeriods for touch points within the same
retailer as the calling touch point are returned.
Get a list of all voucher definitions that the calling touchpoint is allowed to issue.\
Essentially, this means that only voucher definitions that have active sellingPeriods for touchpoints within the same
retailer as the calling touchpoint are returned.
Voucher definitions are modeled using the same model as HTM products. This means that voucher definitions look like "products" (have a productId, mostly the same attributes as HTM products, etc.) but most attributes need to be interpreted differently.\
For vouchers:
- productCategory should always be "voucher"
- requiredProduct contains the productId of the product that is acquired when redeeming the voucher
- sellingPeriods denote which touchpoints are allowed to issue vouchers from a given definition and what their issuance limits are
- MandatoryCustomerDataItems denote the "voucher claims" which are checked against known values that should match the customer input, to be allowed to redeem the voucher
- Most other attributes are also prerequisites for redeeming the voucher, but they will likely match the attributes of the product that is acquired when redeeming the voucher (voucher requires PAD attributes if the product requires PAD attributes, etc.)
parameters:
- name: touchpointId
in: query
required: false
description: |
Filter the voucher definitions on a specific touch point id. This means that only voucher definitions with active selling periods for the specified touch point are returned.
This query parameter is only intended for administrative purposes, since the touch point 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 touch points within the same retailer, for example to retrieve voucher definitions for a specific sales touch point that is different from the calling touch point.
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: 1001
example: 8
- name: productId
in: query
required: false
description: Filter the voucher definitions on a specific product id.
description: Return a specific voucher definition by it's productId.
schema:
type: integer
example: 263
example: 321
- name: requiredProductId
in: query
required: false
description: Filter the voucher definitions on a specific required product id. This means that only voucher definitions that have the specified product id in their requiredProducts list are returned.
description: Filter the voucher definitions on a specific requiredProductId (denoting the product that is acquired when redeeming the voucher). This means that only voucher definitions that have the specified productId in their requiredProducts array are returned.
schema:
type: integer
example: 126
@ -58,22 +65,24 @@ paths:
summary: No products / Empty list
description: No products
value: { "voucherDefinitions": [] }
List containing one voucher definition (called by touchpointId 1001):
summary: List containing one voucher definition (called by touchpointId 10010011)
description: TODO
List containing one voucher definition (called by touchpointId 8):
summary: List containing one voucher definition (called by touchpointId 8)
description: |-
List containing one voucher definition for a voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag".\
To redeem it, the customer must provide a valid PAD birth date (that is checked against the PAD of the actual OVpay-token and against the voucherClaim provided by the voucher issuer).
value:
{
"voucherDefinitions":
[
{
"productId": 1002,
"productName": "Korting Ooievaarspas",
"productDescription": "Kortingsvoucher voor houders van een Ooievaarspas",
"productId": 321,
"productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "Voucher voor AOW-ers in Den Haag met een Ooievaarspas, dat recht geeft op het product \"Ooievaarspas voor AOW-ers in Den Haag\"",
"validityPeriod":
{
"validityPeriodId": 144,
"fromInclusive": "2023-12-31T23:00:00.000+00:00",
"toInclusive": "2028-11-25T04:00:00.000+00:00",
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
},
"productCategory":
{
@ -85,8 +94,8 @@ paths:
[
{
"productId": 126,
"productName": "HTM-30001",
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
},
],
"mandatoryCustomerDataItems":
@ -94,11 +103,7 @@ paths:
{
"mandatoryCustomerDataItemId": 8,
"customerDataItem": "padBirthDate",
},
{
"mandatoryCustomerDataItemId": 4,
"customerDataItem": "emailAddress",
},
}
],
"imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg",
"productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina",
@ -106,11 +111,11 @@ paths:
[
{
"sellingPeriodId": 78,
"fromInclusive": "2024-09-30T23:00:00.000+00:00",
"toInclusive": "2028-11-17T23:00:00.000+00:00",
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
"salesTouchpoint":
{
"salesTouchpointId": 1001,
"salesTouchpointId": 8,
"name": "Gemeente Den Haag",
"isActive": true,
"retailer":
@ -133,11 +138,10 @@ paths:
"sellingPrices":
[
{
"sellingPriceId": 78,
"amountExclTax": null,
"amountInclTax": -100,
"fromInclusive": "2024-09-30T23:00:00.000+00:00",
"toInclusive": "2028-11-17T23:00:00.000+00:00",
"sellingPriceId": 91,
"amountInclTax": 0,
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
"internalPrice": 0.0000,
"taxCode": "V09",
"taxPercentage": 9.0000,
@ -200,18 +204,17 @@ paths:
get:
summary: Get a list of issued vouchers that were issued for a specific touch point
description:
Retrieve all issued vouchers for a specific touch point. This means that only products that have active sellingPeriods for touch points within the same
retailer as the calling touch point are returned.
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 touch point id. This means that only issued vouchers for products with active selling periods for the specified touch point are returned.
This query parameter is only intended for administrative purposes, since the touch point 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 touch points within the same retailer, for example to retrieve issued vouchers for a specific sales touch point that is different from the calling touch point.
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: 1001
example: 8
- name: issuedVoucherId
in: query
required: false
@ -223,14 +226,14 @@ paths:
- name: voucherCode
in: query
required: false
description: The unique code of the issued voucher to retrieve.
description: The unique code (that the customer uses for redeeming the voucher) of the issued voucher to retrieve.
schema:
type: string
example: VOUCHER123
example: HTM-A7J-128-PYT
- name: productId
in: query
required: false
description: The unique identifier of the product for which to retrieve all issued vouchers.
description: Return only vouchers that were issued for the given voucher definition (by it's productId).
schema:
type: integer
example: 263
@ -245,6 +248,7 @@ paths:
- 3 = redeemed
- 4 = revoked
- 5 = expired
- 6 = pendingRedemption
schema:
type: array
items:
@ -260,37 +264,45 @@ paths:
schema:
$ref: "#/components/schemas/unavailable"
examples:
Voucher for a product with required attributes:
summary: Voucher for a single product with required attributes
List containing one issued voucher:
summary: List containing one issued voucher
description: |-
List containing one issued voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag".\
To redeem it, the customer must provide a valid PAD birth date (that is checked against the PAD of the actual OVpay-token and against the voucherClaim provided by the voucher issuer). The birthdate value that is checked against, can be found in the "claims" array of the issued voucher.
value:
{
"issuedVouchers":
[
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "VOUCHER123",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01:00:00.000+00:00",
"untilInclusive": "2030-12-31T023:59:59.000+00:00",
"voucherStatus":
{ "voucherStatusId": 1, "name": "New" },
"product":
{
"productId": 263,
"productName": "HTM-80001",
"productDescription": "10 euro korting op Regiovrij maand.",
"productId": 321,
"productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "Voucher voor AOW-ers in Den Haag met een Ooievaarspas, dat recht geeft op het product \"Ooievaarspas voor AOW-ers in Den Haag\"",
"validityPeriod":
{
"validityPeriodId": 144,
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
},
"productCategory":
{
"productCategoryId": 9,
"isTravelProduct": false,
"name": "Voucher",
},
"amountInclTax": -1000,
"requiredProducts":
[
{
"productId": 126,
"productName": "HTM-30001",
"productDescription": "Regiovrij maand.",
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
"_links":
{
"get_details":
@ -298,14 +310,14 @@ paths:
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126",
"method": "GET",
},
},
},
}
}
],
"_links":
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/321",
"method": "GET",
},
},
@ -319,58 +331,11 @@ paths:
"customerDataItem": "padBirthDate",
},
"value": "1980-06-31",
},
{
"mandatoryCustomerDataItem":
{
"mandatoryCustomerDataItemId": 4,
"customerDataItem": "emailAddress",
},
"value": "harry@griffindor.co.uk",
},
}
],
},
],
}
Voucher for a whole order:
summary: Voucher for a whole order
value:
{
"issuedVouchers":
[
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "VOUCHER123",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus":
{ "voucherStatusId": 1, "name": "New" },
"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",
},
},
},
},
"claims": [],
],
}
"403":
description: Forbidden
content: