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

167
src/openapi/products/SE-vouchers-supplier.yaml
View File

@ -1,7 +1,7 @@
openapi: 3.0.1 openapi: 3.0.1
info: info:
title: Service Engine APIs for HTM voucher suppliers 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" version: "1.0"
servers: servers:
- url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0 - url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0
@ -12,30 +12,37 @@ paths:
- Vouchers - Vouchers
summary: Get a list of all voucher definitions that a touchpoint is allowed to issue summary: Get a list of all voucher definitions that a touchpoint is allowed to issue
description: |- description: |-
Get a list of all voucher definitions that the calling touch point is allowed to issue. Get a list of all voucher definitions that the calling touchpoint is allowed to issue.\
Essentially, this means that only products that have active sellingPeriods for touch points within the same Essentially, this means that only voucher definitions that have active sellingPeriods for touchpoints within the same
retailer as the calling touchpoint are returned. 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: parameters:
- name: touchpointId - name: touchpointId
in: query in: query
required: false required: false
description: | 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. 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. 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: schema:
type: integer type: integer
example: 1001 example: 8
- name: productId - name: productId
in: query in: query
required: false required: false
description: Filter the voucher definitions on a specific product id. description: Return a specific voucher definition by it's productId.
schema: schema:
type: integer type: integer
example: 263 example: 321
- name: requiredProductId - name: requiredProductId
in: query in: query
required: false 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: schema:
type: integer type: integer
example: 126 example: 126
@ -58,22 +65,24 @@ paths:
summary: No products / Empty list summary: No products / Empty list
description: No products description: No products
value: { "voucherDefinitions": [] } value: { "voucherDefinitions": [] }
List containing one voucher definition (called by touchpointId 1001): List containing one voucher definition (called by touchpointId 8):
summary: List containing one voucher definition (called by touchpointId 10010011) summary: List containing one voucher definition (called by touchpointId 8)
description: TODO 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: value:
{ {
"voucherDefinitions": "voucherDefinitions":
[ [
{ {
"productId": 1002, "productId": 321,
"productName": "Korting Ooievaarspas", "productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "Kortingsvoucher voor houders van een Ooievaarspas", "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": "validityPeriod":
{ {
"validityPeriodId": 144, "validityPeriodId": 144,
"fromInclusive": "2023-12-31T23:00:00.000+00:00", "fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2028-11-25T04:00:00.000+00:00", "toInclusive": "2030-12-31T023:59:59.000+00:00",
}, },
"productCategory": "productCategory":
{ {
@ -85,8 +94,8 @@ paths:
[ [
{ {
"productId": 126, "productId": 126,
"productName": "HTM-30001", "productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.", "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
}, },
], ],
"mandatoryCustomerDataItems": "mandatoryCustomerDataItems":
@ -94,11 +103,7 @@ paths:
{ {
"mandatoryCustomerDataItemId": 8, "mandatoryCustomerDataItemId": 8,
"customerDataItem": "padBirthDate", "customerDataItem": "padBirthDate",
}, }
{
"mandatoryCustomerDataItemId": 4,
"customerDataItem": "emailAddress",
},
], ],
"imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg",
"productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina",
@ -106,11 +111,11 @@ paths:
[ [
{ {
"sellingPeriodId": 78, "sellingPeriodId": 78,
"fromInclusive": "2024-09-30T23:00:00.000+00:00", "fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2028-11-17T23:00:00.000+00:00", "toInclusive": "2030-12-31T023:59:59.000+00:00",
"salesTouchpoint": "salesTouchpoint":
{ {
"salesTouchpointId": 1001, "salesTouchpointId": 8,
"name": "Gemeente Den Haag", "name": "Gemeente Den Haag",
"isActive": true, "isActive": true,
"retailer": "retailer":
@ -133,11 +138,10 @@ paths:
"sellingPrices": "sellingPrices":
[ [
{ {
"sellingPriceId": 78, "sellingPriceId": 91,
"amountExclTax": null, "amountInclTax": 0,
"amountInclTax": -100, "fromInclusive": "2026-01-01:00:00.000+00:00",
"fromInclusive": "2024-09-30T23:00:00.000+00:00", "toInclusive": "2030-12-31T023:59:59.000+00:00",
"toInclusive": "2028-11-17T23:00:00.000+00:00",
"internalPrice": 0.0000, "internalPrice": 0.0000,
"taxCode": "V09", "taxCode": "V09",
"taxPercentage": 9.0000, "taxPercentage": 9.0000,
@ -200,18 +204,17 @@ paths:
get: get:
summary: Get a list of issued vouchers that were issued for a specific touch point summary: Get a list of issued vouchers that were issued for a specific touch point
description: 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 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.
retailer as the calling touch point are returned.
parameters: parameters:
- name: touchpointId - name: touchpointId
in: query in: query
required: false required: false
description: | 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. 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. 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: schema:
type: integer type: integer
example: 1001 example: 8
- name: issuedVoucherId - name: issuedVoucherId
in: query in: query
required: false required: false
@ -223,14 +226,14 @@ paths:
- name: voucherCode - name: voucherCode
in: query in: query
required: false 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: schema:
type: string type: string
example: VOUCHER123 example: HTM-A7J-128-PYT
- name: productId - name: productId
in: query in: query
required: false 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: schema:
type: integer type: integer
example: 263 example: 263
@ -245,6 +248,7 @@ paths:
- 3 = redeemed - 3 = redeemed
- 4 = revoked - 4 = revoked
- 5 = expired - 5 = expired
- 6 = pendingRedemption
schema: schema:
type: array type: array
items: items:
@ -260,37 +264,45 @@ paths:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/unavailable"
examples: examples:
Voucher for a product with required attributes: List containing one issued voucher:
summary: Voucher for a single product with required attributes 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: value:
{ {
"issuedVouchers": "issuedVouchers":
[ [
{ {
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "VOUCHER123", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000", "fromInclusive": "2026-01-01:00:00.000+00:00",
"untilInclusive": "2024-11-04T00:00:00.000", "untilInclusive": "2030-12-31T023:59:59.000+00:00",
"voucherStatus": "voucherStatus":
{ "voucherStatusId": 1, "name": "New" }, { "voucherStatusId": 1, "name": "New" },
"product": "product":
{ {
"productId": 263, "productId": 321,
"productName": "HTM-80001", "productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "10 euro korting op Regiovrij maand.", "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": "productCategory":
{ {
"productCategoryId": 9, "productCategoryId": 9,
"isTravelProduct": false, "isTravelProduct": false,
"name": "Voucher", "name": "Voucher",
}, },
"amountInclTax": -1000,
"requiredProducts": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 126,
"productName": "HTM-30001", "productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Regiovrij maand.", "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
"_links": "_links":
{ {
"get_details": "get_details":
@ -298,14 +310,14 @@ paths:
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126",
"method": "GET", "method": "GET",
}, },
}, }
}, }
], ],
"_links": "_links":
{ {
"get_details": "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", "method": "GET",
}, },
}, },
@ -319,56 +331,9 @@ paths:
"customerDataItem": "padBirthDate", "customerDataItem": "padBirthDate",
}, },
"value": "1980-06-31", "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": "403":