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.
schema:
type: integer
example: 8
example: 12
- name: productId
in: query
required: false
@ -65,11 +65,11 @@ paths:
summary: No products / Empty list
description: No products
value: { "voucherDefinitions": [] }
List containing one voucher definition (called by touchpointId 8):
summary: 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 12)
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).
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:
{
"voucherDefinitions":
@ -77,12 +77,12 @@ paths:
{
"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\"",
"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",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T23:59:59.000+00:00",
},
"productCategory":
{
@ -111,11 +111,11 @@ paths:
[
{
"sellingPeriodId": 78,
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T23:59:59.000+00:00",
"salesTouchpoint":
{
"salesTouchpointId": 8,
"salesTouchpointId": 12,
"name": "Gemeente Den Haag",
"isActive": true,
"retailer":
@ -140,8 +140,8 @@ paths:
{
"sellingPriceId": 91,
"amountInclTax": 0,
"fromInclusive": "2026-01-01:00:00.000+00:00",
"toInclusive": "2030-12-31T023:59:59.000+00:00",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"toInclusive": "2030-12-31T23:59:59.000+00:00",
"internalPrice": 0.0000,
"taxCode": "V09",
"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.
schema:
type: integer
example: 8
example: 12
- name: issuedVoucherId
in: query
required: false
@ -236,7 +236,7 @@ paths:
description: Return only vouchers that were issued for the given voucher definition (by it's productId).
schema:
type: integer
example: 263
example: 321
- name: highestVoucherStatusId
in: query
required: false
@ -250,10 +250,8 @@ paths:
- 5 = expired
- 6 = pendingRedemption
schema:
type: array
items:
type: integer
example: [1, 2]
example: 3
tags:
- Vouchers
responses:
@ -268,7 +266,7 @@ paths:
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.
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:
{
"issuedVouchers":
@ -276,51 +274,23 @@ paths:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01:00:00.000+00:00",
"untilInclusive": "2030-12-31T023:59:59.000+00:00",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus":
{ "voucherStatusId": 1, "name": "New" },
"product":
{
"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",
},
"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\"",
"requiredProducts":
[
{
"productId": 126,
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"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",
},
"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/321",
"method": "GET",
},
},
]
},
"claims":
[
@ -385,10 +355,9 @@ paths:
"instance": "/issuedvouchers",
}
post:
summary: Issue a voucher for a specific product
summary: Issue a voucher for a specific voucher definition
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.
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.
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).
tags:
- Vouchers
requestBody:
@ -398,43 +367,37 @@ paths:
schema:
$ref: "#/components/schemas/unavailable"
examples:
Issue a voucher with prefilled voucher code:
summary: Issue a voucher with prefilled voucher code
Issue a voucher and supply own voucher code:
summary: Issue a voucher and supply own voucher code
description: This allows the voucher supplier to supply its own voucher code, which can be useful if the 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:
{
"voucherCode": "VOUCHER123",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"productId": 263,
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 321,
"voucherClaims":
[
{
"mandatoryCustomerDataItemId": 8,
"value": "1970-01-01",
},
{
"mandatoryCustomerDataItemId": 4,
"value": "stasjo@html.nl",
},
"value": "1980-06-31",
}
],
}
Issue a voucher without prefilled voucher code:
summary: 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 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:
{
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"productId": 263,
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 321,
"voucherClaims":
[
{
"mandatoryCustomerDataItemId": 8,
"value": "1970-01-01",
},
{
"mandatoryCustomerDataItemId": 4,
"value": "stasjo@html.nl",
},
"value": "1980-06-31",
}
],
}
responses:
@ -450,32 +413,35 @@ paths:
value:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HKV-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus": { "voucherStatusId": 1, "name": "New" },
"product":
{
"productId": 263,
"productName": "HTM-80002",
"productDescription": "10 euro korting op je gehele winkelmand.",
"productCategory":
"productId": 321,
"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\"",
"requiredProducts":
[
{
"productCategoryId": 9,
"isTravelProduct": false,
"name": "Voucher",
"productId": 126,
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
}
]
},
"amountInclTax": -1000,
"requiredProducts": [],
"_links":
"claims":
[
{
"get_details":
"mandatoryCustomerDataItem":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
"method": "GET",
},
},
"mandatoryCustomerDataItemId": 8,
"customerDataItem": "padBirthDate",
},
"value": "1980-06-31",
}
]
}
/issuedvouchers/{issuedVoucherId}:
parameters:
@ -489,7 +455,15 @@ paths:
example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90
patch:
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:
- Vouchers
requestBody:
@ -500,10 +474,10 @@ paths:
$ref: "#/components/schemas/unavailable"
examples:
Mark a voucher as expired:
summary: Mark a voucher as expired
summary: Mark a voucher as revoked
value:
{
"voucherStatusId": 5,
"voucherStatusId": 4,
}
responses:
"200":
@ -518,32 +492,40 @@ paths:
value:
{
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
"voucherCode": "HKV-A7J-128-PYT",
"fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 5, "name": "Expired" },
"voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
"voucherStatus": { "voucherStatusId": 4, "name": "Revoked" },
"product":
{
"productId": 263,
"productName": "HTM-80002",
"productDescription": "10 euro korting op je gehele winkelmand.",
"productCategory":
"productId": 321,
"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\"",
"requiredProducts":
[
{
"productCategoryId": 9,
"isTravelProduct": false,
"name": "Voucher",
},
"amountInclTax": -1000,
"requiredProducts": [],
"_links":
"productId": 126,
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas."
}
]
}
}
"400":
description: Bad request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/rfc9457"
examples:
Illegal state change:
summary: Illegal state change
value:
{
"get_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
"method": "GET",
},
},
},
"type": "https://example.com/probs/bad-request",
"title": "Bad request",
"detail": "This state change is not allowed.",
"instance": "/issuedvouchers/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
}
components:
securitySchemes: