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

Added JSON schema and updated examples and error specs for supplier - tweaked OAS for TP

Browse Source
This commit is contained in:
Max Martens 2026-06-03 19:06:17 +02:00
parent 7173bd3727
commit bd870d0fa8
2 changed files with 708 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
src/openapi/products/SE-vouchers-TP.yaml
View File

@ -28,12 +28,12 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/issuedVoucherResponse" $ref: "#/components/schemas/salesTouchpointIssuedVoucherResponse"
examples: examples:
Voucher that grants a voucher-only product for free: Voucher that grants a voucher-only product for free:
summary: Voucher that grants a voucher-only product for free summary: Voucher that grants a voucher-only product for free
description: |- description: |-
Voucher that grants a product (that can onlu be acquired via a voucher) for free. 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 In this case, the voucher has an amountInclTax of 0. If the requiredProduct has a
non-zero sellingPrice (amountInclTax), the difference between sellingPrice and non-zero sellingPrice (amountInclTax), the difference between sellingPrice and
voucher amountInclTax represents the granted discount. If the requiredProduct has voucher amountInclTax represents the granted discount. If the requiredProduct has
@ -57,6 +57,13 @@ paths:
"productId": 982, "productId": 982,
"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.",
"productCategory":
{
"productCategoryId": 2,
"isTravelProduct": true,
"name": "Afgekocht reisrecht",
},
"amountInclTax": 0,
"_links": "_links":
{ {
"get_details": "get_details":
@ -81,7 +88,7 @@ paths:
description: |- description: |-
Voucher that grants a hybrid product (that can be acquired via voucher or via ordinary order flow) 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) 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 total amount that needs to be paid for said product. If the requiredProduct has a
non-zero sellingPrice (amountInclTax), the difference between sellingPrice and non-zero sellingPrice (amountInclTax), the difference between sellingPrice and
voucher amountInclTax represents the granted discount. If the requiredProduct has voucher amountInclTax represents the granted discount. If the requiredProduct has
a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax./ a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax./
@ -142,7 +149,7 @@ paths:
{ {
"productId": 265, "productId": 265,
"productName": "Voucher 10 euro korting", "productName": "Voucher 10 euro korting",
"productDescription": "Voucher die10 euro korting geeft op je gehele winkelmand.", "productDescription": "Voucher die 10 euro korting geeft op je gehele winkelmand.",
"amountInclTax": -1000, "amountInclTax": -1000,
"requiredProducts": [] "requiredProducts": []
}, },
@ -164,20 +171,20 @@ paths:
"detail": "You do not have permission to access this resource.", "detail": "You do not have permission to access this resource.",
"instance": "/issuedvouchers", "instance": "/issuedvouchers",
} }
"404": "400":
description: Not found description: Bad request
content: content:
application/problem+json: application/problem+json:
schema: schema:
$ref: "#/components/schemas/rfc9457" $ref: "#/components/schemas/rfc9457"
examples: examples:
Voucher not found: Invalid voucher code:
summary: Voucher not found summary: Invalid voucher code
value: value:
{ {
"type": "https://example.com/probs/not-found", "type": "https://example.com/probs/bad-request",
"title": "Voucher not found", "title": "Invalid voucher code",
"detail": "The voucher with code VOUCHER123 does not exist.", "detail": "No valid voucher found for code VOUCHER123.",
"instance": "/issuedvouchers", "instance": "/issuedvouchers",
} }
"500": "500":
@ -203,7 +210,7 @@ components:
scheme: bearer scheme: bearer
bearerFormat: JWT bearerFormat: JWT
schemas: schemas:
issuedVoucherResponse: salesTouchpointIssuedVoucherResponse:
type: object type: object
required: required:
- issuedVoucherId - issuedVoucherId
@ -224,18 +231,18 @@ components:
example: "HTM-A7J-128-PYT" example: "HTM-A7J-128-PYT"
fromInclusive: fromInclusive:
type: string type: string
format: date-time format: date-time-offset
description: |- description: |-
The date and time the voucher becomes valid for redemption. This has nothing to do with 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). the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
example: "2024-10-04T00:00:00.000" example: "2024-10-04T00:00:00.000+02:00"
untilInclusive: untilInclusive:
type: string type: string
format: date-time format: date-time-offset
description: |- description: |-
The date and time the voucher becomes invalid for redemption. This has nothing to do with 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). the maximum allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
example: "2024-11-04T00:00:00.000" example: "2024-11-04T00:00:00.000+01:00"
voucherStatus: voucherStatus:
type: object type: object
required: required:
@ -258,7 +265,7 @@ components:
example: "issued" example: "issued"
product: product:
type: object type: object
description: The "product" referencing the voucher definition that this voucher instance is based on" description: The "product" referencing the voucher definition that this voucher instance is based on
required: required:
- productId - productId
- productName - productName

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

@ -21,7 +21,8 @@ paths:
- requiredProduct contains the productId of the product that is acquired when redeeming the 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 - 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 - 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.)
When a requiredProduct is configured, all attributes of the requiredProduct are also prerequisites for redeeming the voucher; thus they do not need to also be configured for the voucher definition. The requiredProduct itself is the single source of truth for this; and voucher definitions do not need to be updated if the requirements of the requiredProduct change. For example, if the requiredProduct requires an OVpay token, an OVpay token is automatically required to redeem issued vouchers.
parameters: parameters:
- name: touchpointId - name: touchpointId
in: query in: query
@ -59,7 +60,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointVoucherDefinitionsListResponse"
examples: examples:
No products / Empty list: No products / Empty list:
summary: No products / Empty list summary: No products / Empty list
@ -69,13 +70,15 @@ paths:
summary: List containing one voucher definition (called by touchpointId 12) 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 birthdate (that is checked against the PAD of the actual OVpay-token and against the voucherClaim provided by the voucher issuer). In this case, the voucher definition has a sellingPrice of 0, which means that vouchers issued from this voucher definition can be redeemed to acquire the requiredProduct for free. The requiredProduct also has a sellingPrice of 0, so no "discount" is shown to the customer; just the voucher's amountInclTax.\
To issue vouchers for this voucher definition, the calling touchpoint must also provide voucherClaims (values to be checked against customer input when redeeming the voucher) for each of the mandatoryCustomerDataItems of the voucher definition (in this case, a PAD birthdate).\
To redeem the voucher, 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":
[ [
{ {
"productId": 321, "productId": 263,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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":
@ -93,7 +96,7 @@ paths:
"requiredProducts": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 982,
"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.",
}, },
@ -106,7 +109,7 @@ paths:
} }
], ],
"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", "termsUrl": "https://www.htm.nl/voorwaarden/vouchers/voucher-xxx-voorwaarden.pdf",
"sellingPeriods": "sellingPeriods":
[ [
{ {
@ -145,12 +148,12 @@ paths:
"internalPrice": 0.0000, "internalPrice": 0.0000,
"taxCode": "V09", "taxCode": "V09",
"taxPercentage": 9.0000, "taxPercentage": 9.0000,
}, }
], ]
}, }
], ]
}, }
], ]
} }
"403": "403":
description: Forbidden description: Forbidden
@ -243,6 +246,8 @@ paths:
explode: false explode: false
description: |- description: |-
Return only issued vouchers that currently have the given voucher status(es). Return only issued vouchers that currently have the given voucher status(es).
Possible voucher statuses are:
- 1 = new
- 2 = issued - 2 = issued
- 3 = redeemed - 3 = redeemed
- 4 = revoked - 4 = revoked
@ -261,13 +266,14 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointIssuedVouchersListResponse"
examples: examples:
List containing one issued voucher: List containing one issued voucher that grants a product for free:
summary: List containing one issued voucher summary: List containing one issued voucher that grants a product for free
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" for free.\
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. In this case, the voucher has an amountInclTax of 0. The requiredProduct also has a sellingPrice of 0, so no "discount" is shown to the customer; just the voucher's amountInclTax.
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 "voucherClaims" array of the issued voucher.
value: value:
{ {
"issuedVouchers": "issuedVouchers":
@ -275,25 +281,41 @@ 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-01T00:00:00.000+00:00", "fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2030-12-31T23:59:59.000+00:00", "untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": "voucherStatus": { "voucherStatusId": 2, "name": "issued" },
{ "voucherStatusId": 1, "name": "New" },
"product": "product":
{ {
"productId": 321, "productId": 263,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 982,
"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.",
} "productCategory":
] {
"productCategoryId": 2,
"isTravelProduct": true,
"name": "Afgekocht reisrecht",
},
"amountInclTax": 0
},
],
"_links":
{
"get_voucher_definition_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/263",
"method": "GET",
},
},
}, },
"claims": "voucherClaims":
[ [
{ {
"mandatoryCustomerDataItem": "mandatoryCustomerDataItem":
@ -303,9 +325,96 @@ paths:
}, },
"value": "1980-06-31", "value": "1980-06-31",
} }
], ]
}
]
}
List containing one issued voucher that grants a product for a reduced price:
summary: List containing one issued voucher that grants a product for a reduced price
description: |-
List containing one issued voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag" 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.
To redeem it, the customer needs to provide only the voucher code; there are no voucherClaims to be checked against.
value:
{
"issuedVouchers":
[
{
"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": 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_voucher_definition_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/264",
"method": "GET",
}
}
},
"voucherClaims":[]
}, },
], ]
}
List containing one issued voucher that grants a discount for a whole order:
summary: List containing one issued voucher that grants a discount for a whole order
description: |-
List containing one issued voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag" for a reduced price.\
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).
To redeem it, the customer needs to provide only the voucher code; there are no voucherClaims to be checked against.
value:
{
"issuedVouchers":
[
{
"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": [],
"_links":
{
"get_voucher_definition_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/265",
"method": "GET",
}
}
},
"voucherClaims":[]
}
]
} }
"403": "403":
description: Forbidden description: Forbidden
@ -358,7 +467,9 @@ paths:
post: post:
summary: Issue a voucher for a specific voucher definition summary: Issue a voucher for a specific voucher definition
description: | description: |
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). 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 \"fromInclusive\" and \"untilInclusive\" fields specify the date-time range in which the voucher can be redeemed by the customer. This has nothing to do with the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).\
If the voucher definition contains mandatoryCustomerDataItems, a value (to be checked against customer input when redeeming the voucher) has to be provided for each of these items.
tags: tags:
- Vouchers - Vouchers
requestBody: requestBody:
@ -366,7 +477,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointCreateIssuedVoucherRequest"
examples: examples:
Issue a voucher and supply own voucher code: Issue a voucher and supply own voucher code:
summary: Issue a voucher and supply own voucher code summary: Issue a voucher and supply own voucher code
@ -376,7 +487,7 @@ paths:
"voucherCode": "HTM-A7J-128-PYT", "voucherCode": "HTM-A7J-128-PYT",
"fromInclusive": "2026-01-01T00:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 321, "productId": 263,
"voucherClaims": "voucherClaims":
[ [
{ {
@ -392,14 +503,7 @@ paths:
{ {
"fromInclusive": "2026-01-01T00:00:00.000+00:00", "fromInclusive": "2026-01-01T00:00:00.000+00:00",
"untilInclusive": "2030-12-31T23:59:59.000+00:00", "untilInclusive": "2030-12-31T23:59:59.000+00:00",
"productId": 321, "productId": 264
"voucherClaims":
[
{
"mandatoryCustomerDataItemId": 8,
"value": "1980-06-31",
}
],
} }
responses: responses:
"201": "201":
@ -407,7 +511,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointIssuedVoucherResponse"
examples: examples:
Successfully issued a voucher: Successfully issued a voucher:
summary: Successfully issued a voucher summary: Successfully issued a voucher
@ -415,24 +519,41 @@ 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-01T00:00:00.000+00:00", "fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2030-12-31T23:59:59.000+00:00", "untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 1, "name": "New" }, "voucherStatus": { "voucherStatusId": 2, "name": "issued" },
"product": "product":
{ {
"productId": 321, "productId": 263,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 982,
"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.",
} "productCategory":
] {
"productCategoryId": 2,
"isTravelProduct": true,
"name": "Afgekocht reisrecht",
},
"amountInclTax": 0
},
],
"_links":
{
"get_voucher_definition_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/263",
"method": "GET",
},
},
}, },
"claims": "voucherClaims":
[ [
{ {
"mandatoryCustomerDataItem": "mandatoryCustomerDataItem":
@ -442,8 +563,43 @@ paths:
}, },
"value": "1980-06-31", "value": "1980-06-31",
} }
] ],
} }
"400":
description: Bad request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/rfc9457"
examples:
Voucher code already in use:
summary: Voucher code already in use
value:
{
"type": "https://example.com/probs/bad-request",
"title": "Invalid voucher code",
"detail": "This voucher code is already in use.",
"instance": "/issuedvouchers"
}
Missing mandatory voucher claims:
summary: Missing mandatory voucher claims
value:
{
"type": "https://example.com/probs/bad-request",
"title": "Missing mandatory voucher claims",
"detail": "Please provide a value for all mandatoryCustomerDataItems as defined in the voucher definition.",
"instance": "/issuedvouchers"
}
Voucher validity period out of allowed range:
summary: Voucher validity period out of allowed range
value:
{
"type": "https://example.com/probs/bad-request",
"title": "Invalid voucher validity period",
"detail": "The validity period of the voucher is outside the allowed range for this voucher definition's sellingPeriod.",
"instance": "/issuedvouchers"
}
/issuedvouchers/{issuedVoucherId}: /issuedvouchers/{issuedVoucherId}:
parameters: parameters:
- name: issuedVoucherId - name: issuedVoucherId
@ -472,13 +628,13 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointUpdateIssuedVoucherRequest"
examples: examples:
Mark a voucher as expired: Mark a voucher as revoked:
summary: Mark a voucher as revoked summary: Mark a voucher as revoked
value: value:
{ {
"voucherStatusId": 4, "voucherStatusId": 4
} }
responses: responses:
"200": "200":
@ -486,7 +642,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/unavailable" $ref: "#/components/schemas/supplierTouchpointIssuedVoucherResponse"
examples: examples:
Successfully updated the status of a voucher: Successfully updated the status of a voucher:
summary: Successfully updated the status of a voucher summary: Successfully updated the status of a voucher
@ -494,23 +650,51 @@ 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-01T00:00:00.000+00:00", "fromInclusive": "2024-10-04T00:00:00.000",
"untilInclusive": "2030-12-31T23:59:59.000+00:00", "untilInclusive": "2024-11-04T00:00:00.000",
"voucherStatus": { "voucherStatusId": 4, "name": "Revoked" }, "voucherStatus": { "voucherStatusId": 4, "name": "revoked" },
"product": "product":
{ {
"productId": 321, "productId": 263,
"productName": "Voucher Ooievaarspas-product AOW", "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\"", "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": "requiredProducts":
[ [
{ {
"productId": 126, "productId": 982,
"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.",
} "productCategory":
] {
} "productCategoryId": 2,
"isTravelProduct": true,
"name": "Afgekocht reisrecht",
},
"amountInclTax": 0
},
],
"_links":
{
"get_voucher_definition_details":
{
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/263",
"method": "GET",
},
},
},
"voucherClaims":
[
{
"mandatoryCustomerDataItem":
{
"mandatoryCustomerDataItemId": 8,
"customerDataItem": "padBirthDate",
},
"value": "1980-06-31",
}
]
} }
"400": "400":
description: Bad request description: Bad request
@ -535,6 +719,441 @@ components:
scheme: bearer scheme: bearer
bearerFormat: JWT bearerFormat: JWT
schemas: schemas:
supplierTouchpointVoucherDefinitionsListResponse:
type: object
properties:
voucherDefinitions:
type: array
items:
$ref: "#/components/schemas/supplierTouchpointVoucherDefinitionResponse"
supplierTouchpointVoucherDefinitionResponse:
type: object
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\""
validityPeriod:
type: object
required:
- validityPeriodId
- fromInclusive
- toInclusive
properties:
validityPeriodId:
type: integer
example: 1
fromInclusive:
type: string
format: date-time-offset
example: "2024-09-03T10:01:34.000+00:00"
toInclusive:
type: string
format: date-time-offset
example: "2024-09-03T23:59:59.999+00:00"
productCategory:
type: object
required:
- productCategoryId
- name
- isTravelProduct
properties:
productCategoryId:
type: integer
example: 1
name:
type: string
example: Kortingsabonnement
isTravelProduct:
type: boolean
example: true
requiredProducts:
type: array
description: |-
Currently, only one requiredProduct for vouchers is supported and thus, this array can contain at most one element.
items:
type: object
required:
- requiredProductId
- productName
properties:
requiredProductId:
type: integer
example: 2
productName:
type: string
example: Product name
mandatoryCustomerDataItems:
type: array
items:
type: object
required:
- mandatoryCustomerDataItemId
- customerDataItem
properties:
mandatoryCustomerDataItemId:
type: integer
example: 8
customerDataItem:
type: string
example: padBirthdate
imageReference:
type: string
description: Can be a URL or a base64 encoded image
example: https://htm.azure.net/abt/products/product_1.svg
termsUrl:
type: string
example: https://www.htm.nl/voorwaarden/vouchers/voucher-xxx-voorwaarden.pdf
sellingPeriods:
type: array
items:
type: object
required:
- sellingPeriodId
- fromInclusive
- toInclusive
- salesTouchpoint
properties:
sellingPeriodId:
type: integer
example: 1
fromInclusive:
type: string
format: date-time-offset
example: "2022-03-01T00:00:00.000+00:00"
toInclusive:
type: string
format: date-time-offset
example: "2022-06-01T00:00:00.000+00:00"
salesTouchpoint:
type: object
required:
- salesTouchpointId
- name
- isActive
- retailer
properties:
salesTouchpointId:
type: integer
example: 1
name:
type: string
example: HTM App
isActive:
type: boolean
example: true
retailer:
type: object
required:
- retailerId
- name
properties:
retailerId:
type: integer
example: 1001
name:
type: string
example: HTM
street:
type: string
example: Kon. Julianaplein
number:
type: string
example: "10"
numberAddition:
type: string
example: a
postalCode:
type: string
example: 2595 AA
city:
type: string
example: Den Haag
country:
type: string
example: Nederland
emailAddress:
type: string
format: email
example: info@htm.nl
phoneNumber:
type: string
example: "09004864636"
taxId:
type: string
example: "09004864636"
imageReference:
type: string
example: https://htm.azure.net/abt/retailers/htm.svg
sellingPrices:
type: array
items:
type: object
required:
- sellingPriceId
- amountInclTax
- fromInclusive
- toInclusive
- internalPrice
properties:
sellingPriceId:
type: integer
example: 1
taxCode:
type: string
example: "V09"
taxPercentage:
type: number
example: 9.0000
amountInclTax:
type: integer
example: 908
fromInclusive:
type: string
format: date-time-offset
example: "2022-03-01T00:00:00.000+00:00"
toInclusive:
type: string
format: date-time-offset
example: "2022-06-01T00:00:00.000+00:00"
internalPrice:
type: number
example: 908.1234
supplierTouchpointCreateIssuedVoucherRequest:
type: object
required:
- fromInclusive
- untilInclusive
- productId
properties:
voucherCode:
type: string
description: The voucher code that is shared with the customer and uniquely identifies this voucher. When not provided, a random voucher code will be generated by the backend system and returned in the response.
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"
productId:
type: integer
description: The productId for the voucher definition for which this voucher instance is issued.
example: 263
voucherClaims:
type: array
items:
type: object
required:
- mandatoryCustomerDataItemId
- value
properties:
mandatoryCustomerDataItemId:
type: integer
description: The mandatoryCustomerDataItemId for the mandatoryCustomerDataItem for which this value is provided.
example: 8
value:
type: string
description: The value that the customer must provide for this mandatoryCustomerDataItem to be able to redeem the voucher.
example: "1970-01-01"
supplierTouchpointUpdateIssuedVoucherRequest:
type: object
required:
- voucherStatusId
properties:
voucherStatusId:
type: integer
description: The new status of the voucher.
example: 4
supplierTouchpointIssuedVouchersListResponse:
type: object
properties:
issuedVouchers:
type: array
items:
$ref: "#/components/schemas/supplierTouchpointIssuedVoucherResponse"
supplierTouchpointIssuedVoucherResponse:
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_voucher_definition_details:
type: object
description: Link to get more details for the voucher definition that this voucher is instanced from
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/263
method:
type: string
example: GET
voucherClaims:
type: array
description: |-
List of pairs, each containing a mandatoryCustomerDataItem and the value that the customer must provide for this mandatoryCustomerDataItem to be able to redeem the voucher.
The values to be checked against are provided by the voucher issuer/supplier.
items:
type: object
required:
- mandatoryCustomerDataItem
- value
properties:
mandatoryCustomerDataItem:
type: object
required:
- mandatoryCustomerDataItemId
- customerDataItem
properties:
mandatoryCustomerDataItemId:
type: integer
example: 8
customerDataItem:
type: string
example: padBirthdate
value:
type: string
example: 1970-01-01
unavailable: unavailable:
type: object type: object
rfc9457: rfc9457: