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

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

Browse Source
This commit is contained in:
Max Martens 2026-05-06 22:44:55 +02:00
parent 9fb20a491f
commit 69908f58b0
1 changed files with 110 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -31,7 +31,7 @@ paths:
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: 8 example: 12
- name: productId - name: productId
in: query in: query
required: false required: false
@ -65,11 +65,11 @@ 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 8): List containing one voucher definition (called by touchpointId 12):
summary: List containing one voucher definition (called by touchpointId 8) summary: List containing one voucher definition (called by touchpointId 12)
description: |- description: |-
List containing one voucher definition for a voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag".\ 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). To redeem it, the customer must provide a valid PAD birthdate (that is checked against the PAD of the actual OVpay-token and against the voucherClaim provided by the voucher issuer).
value: value:
{ {
"voucherDefinitions": "voucherDefinitions":
@ -77,12 +77,12 @@ paths:
{ {
"productId": 321, "productId": 321,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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\"",
"validityPeriod": "validityPeriod":
{ {
"validityPeriodId": 144, "validityPeriodId": 144,
"fromInclusive": "2026-01-01:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00", "toInclusive": "2030-12-31T23:59:59.000+00:00",
}, },
"productCategory": "productCategory":
{ {
@ -111,11 +111,11 @@ paths:
[ [
{ {
"sellingPeriodId": 78, "sellingPeriodId": 78,
"fromInclusive": "2026-01-01:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00", "toInclusive": "2030-12-31T23:59:59.000+00:00",
"salesTouchpoint": "salesTouchpoint":
{ {
"salesTouchpointId": 8, "salesTouchpointId": 12,
"name": "Gemeente Den Haag", "name": "Gemeente Den Haag",
"isActive": true, "isActive": true,
"retailer": "retailer":
@ -140,8 +140,8 @@ paths:
{ {
"sellingPriceId": 91, "sellingPriceId": 91,
"amountInclTax": 0, "amountInclTax": 0,
"fromInclusive": "2026-01-01:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00", "toInclusive": "2030-12-31T23:59:59.000+00:00",
"internalPrice": 0.0000, "internalPrice": 0.0000,
"taxCode": "V09", "taxCode": "V09",
"taxPercentage": 9.0000, "taxPercentage": 9.0000,
@ -214,7 +214,7 @@ paths:
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: 8 example: 12
- name: issuedVoucherId - name: issuedVoucherId
in: query in: query
required: false required: false
@ -236,7 +236,7 @@ paths:
description: Return only vouchers that were issued for the given voucher definition (by it's productId). 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: 321
- name: highestVoucherStatusId - name: highestVoucherStatusId
in: query in: query
required: false required: false
@ -250,10 +250,8 @@ paths:
- 5 = expired - 5 = expired
- 6 = pendingRedemption - 6 = pendingRedemption
schema: schema:
type: array
items:
type: integer type: integer
example: [1, 2] example: 3
tags: tags:
- Vouchers - Vouchers
responses: responses:
@ -268,7 +266,7 @@ paths:
summary: List containing one issued voucher summary: List containing one issued voucher
description: |- description: |-
List containing one issued voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag".\ 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. To redeem it, the customer must provide a valid PAD birthdate (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":
@ -276,51 +274,23 @@ paths:
{ {
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HTM-A7J-128-PYT", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T023:59:59.000+00:00", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus": "voucherStatus":
{ "voucherStatusId": 1, "name": "New" }, { "voucherStatusId": 1, "name": "New" },
"product": "product":
{ {
"productId": 321, "productId": 321,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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\"",
"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",
},
"requiredProducts": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 126,
"productName": "Ooievaarspas voor AOW-ers in Den Haag", "productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.", "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
"_links":
{
"get_details":
{
"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/321",
"method": "GET",
},
},
}, },
"claims": "claims":
[ [
@ -385,10 +355,9 @@ paths:
"instance": "/issuedvouchers", "instance": "/issuedvouchers",
} }
post: post:
summary: Issue a voucher for a specific product summary: Issue a voucher for a specific voucher definition
description: | description: |
Issue a voucher for a specific product. The voucher will be issued for the touch point that is associated with the access token used in the request. Issue a voucher for a specific voucher definition. Vouchers can only be issued on a one-by-one basis, so that it is always clear what voucher code has been issued for specific voucher claims (which by itself my not uniquely identify the voucher; however the voucher code is guaranteed to be unique). The voucher can only be issued if the calling touchpoint (recognized by the access token) has an active selling period for the voucher definition (recognized by the productId).
The product for which the voucher should be issued must have active selling periods for touch points within the same retailer as the calling touch point.
tags: tags:
- Vouchers - Vouchers
requestBody: requestBody:
@ -398,43 +367,37 @@ paths:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/unavailable"
examples: examples:
Issue a voucher with prefilled voucher code: Issue a voucher and supply own voucher code:
summary: Issue a voucher with prefilled voucher code summary: Issue a voucher and supply own voucher code
description: This allows the voucher supplier to supply its own voucher code, which can be useful if the suplier already has its own (internal or external) source for voucher codes. The supplied voucher code must be unique - if this code is already in use, the request will fail.
value: value:
{ {
"voucherCode": "VOUCHER123", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2024-11-04T00:00:00.000", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 263, "productId": 321,
"voucherClaims": "voucherClaims":
[ [
{ {
"mandatoryCustomerDataItemId": 8, "mandatoryCustomerDataItemId": 8,
"value": "1970-01-01", "value": "1980-06-31",
}, }
{
"mandatoryCustomerDataItemId": 4,
"value": "stasjo@html.nl",
},
], ],
} }
Issue a voucher without prefilled voucher code: Issue a voucher and receive a voucher code (generated by ABT backend) in response:
summary: Issue a voucher without prefilled voucher code summary: Issue a voucher and receive a voucher code (generated by ABT backend) in response
description: If the supplier is not able to generate its own unique voucher codes, it can issue a voucher without supplying any voucher code - the ABT backend will then receive a unique voucher code and return it in response.
value: value:
{ {
"fromInclusive": "2024-10-04T00:00:00.000", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2024-11-04T00:00:00.000", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 263, "productId": 321,
"voucherClaims": "voucherClaims":
[ [
{ {
"mandatoryCustomerDataItemId": 8, "mandatoryCustomerDataItemId": 8,
"value": "1970-01-01", "value": "1980-06-31",
}, }
{
"mandatoryCustomerDataItemId": 4,
"value": "stasjo@html.nl",
},
], ],
} }
responses: responses:
@ -450,32 +413,35 @@ paths:
value: value:
{ {
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HKV-A7J-128-PYT", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2024-11-04T00:00:00.000", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus": { "voucherStatusId": 1, "name": "New" }, "voucherStatus": { "voucherStatusId": 1, "name": "New" },
"product": "product":
{ {
"productId": 263, "productId": 321,
"productName": "HTM-80002", "productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "10 euro korting op je gehele winkelmand.", "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\"",
"productCategory": "requiredProducts":
[
{ {
"productCategoryId": 9, "productId": 126,
"isTravelProduct": false, "productName": "Ooievaarspas voor AOW-ers in Den Haag",
"name": "Voucher", "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
}
]
}, },
"amountInclTax": -1000, "claims":
"requiredProducts": [], [
"_links":
{ {
"get_details": "mandatoryCustomerDataItem":
{ {
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", "mandatoryCustomerDataItemId": 8,
"method": "GET", "customerDataItem": "padBirthDate",
},
},
}, },
"value": "1980-06-31",
}
]
} }
/issuedvouchers/{issuedVoucherId}: /issuedvouchers/{issuedVoucherId}:
parameters: parameters:
@ -489,7 +455,15 @@ paths:
example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90
patch: patch:
summary: Update the status of an issued voucher summary: Update the status of an issued voucher
description: Update the status of an issued voucher. This can be used to mark a voucher as redeemed, revoked or expired. description: |-
Update the status of an issued voucher. Not every state change is allowed; an error will be returned if an invalid state change is attempted.\
Possible voucher statuses are:
- 1 = new
- 2 = issued
- 3 = redeemed
- 4 = revoked
- 5 = expired
- 6 = pendingRedemption
tags: tags:
- Vouchers - Vouchers
requestBody: requestBody:
@ -500,10 +474,10 @@ paths:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/unavailable"
examples: examples:
Mark a voucher as expired: Mark a voucher as expired:
summary: Mark a voucher as expired summary: Mark a voucher as revoked
value: value:
{ {
"voucherStatusId": 5, "voucherStatusId": 4,
} }
responses: responses:
"200": "200":
@ -518,32 +492,40 @@ paths:
value: value:
{ {
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HKV-A7J-128-PYT", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2024-11-04T00:00:00.000", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus": { "voucherStatusId": 5, "name": "Expired" }, "voucherStatus": { "voucherStatusId": 4, "name": "Revoked" },
"product": "product":
{ {
"productId": 263, "productId": 321,
"productName": "HTM-80002", "productName": "Voucher Ooievaarspas-product AOW",
"productDescription": "10 euro korting op je gehele winkelmand.", "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\"",
"productCategory": "requiredProducts":
[
{ {
"productCategoryId": 9, "productId": 126,
"isTravelProduct": false, "productName": "Ooievaarspas voor AOW-ers in Den Haag",
"name": "Voucher", "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
}, }
"amountInclTax": -1000, ]
"requiredProducts": [], }
"_links": }
"400":
description: Bad request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/rfc9457"
examples:
Illegal state change:
summary: Illegal state change
value:
{ {
"get_details": "type": "https://example.com/probs/bad-request",
{ "title": "Bad request",
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", "detail": "This state change is not allowed.",
"method": "GET", "instance": "/issuedvouchers/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
},
},
},
} }
components: components:
securitySchemes: securitySchemes: