Updated OpenAPI spec for voucher supplier, with examples more relevant to the first usecase (ooievaarspas AOW) - this YAML is also shared with PASS devs #60
@ -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
|
||||
@ -12,30 +12,37 @@ paths:
|
||||
- Vouchers
|
||||
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
|
||||
Get a list of all voucher definitions that the calling touchpoint is allowed to issue.\
|
||||
|
maxmartens marked this conversation as resolved
|
||||
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.
|
||||
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.
|
||||
|
maxmartens marked this conversation as resolved
Outdated
bboterm
commented
its its
|
||||
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.
|
||||
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).
|
||||
|
maxmartens marked this conversation as resolved
Outdated
|
||||
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":
|
||||
|
maxmartens marked this conversation as resolved
Outdated
bboterm
commented
Halen we die HATEOAS er bewust uit? Kan me voorstellen dat supplier niet per definitie dit endpoint aan kan roepen, dus dat het niet zoveel nut heeft. Halen we die HATEOAS er bewust uit? Kan me voorstellen dat supplier niet per definitie dit endpoint aan kan roepen, dus dat het niet zoveel nut heeft.
maxmartens
commented
Dit idd, in de TP versie lijkt het me wel nuttig, voor de supplier niet relevant (of zelfs niet toegestaan om te zien idd) Dit idd, in de TP versie lijkt het me wel nuttig, voor de supplier niet relevant (of zelfs niet toegestaan om te zien idd)
|
||||
{
|
||||
"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,56 +331,9 @@ paths:
|
||||
"customerDataItem": "padBirthDate",
|
||||
},
|
||||
"value": "1980-06-31",
|
||||
},
|
||||
{
|
||||
"mandatoryCustomerDataItem":
|
||||
|
maxmartens marked this conversation as resolved
Outdated
bboterm
commented
Waarom halen we deze eruit? Waarom halen we deze eruit?
maxmartens
commented
Voor ooievaarspas-product gaat PASS alleen PAD geboortedatum als claim meegeven, dus ooievaarspashouders kunnen straks met elk willekeurig emailadres inwisselen Voor ooievaarspas-product gaat PASS alleen PAD geboortedatum als claim meegeven, dus ooievaarspashouders kunnen straks met elk willekeurig emailadres inwisselen
|
||||
{
|
||||
"mandatoryCustomerDataItemId": 4,
|
||||
"customerDataItem": "emailAddress",
|
||||
},
|
||||
"value": "harry@griffindor.co.uk",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
Voucher for a whole order:
|
||||
|
maxmartens marked this conversation as resolved
Outdated
bboterm
commented
Is dit niet meer van toepassing? Is dit niet meer van toepassing?
maxmartens
commented
Deze moest ik er van Paul uithalen voor PASS, en sowieso is complete winkelmand korting iets wat we nog niet echt besproken hadden toen ik dit maakte en wat ook niet formeel in scope is; de MVP is nu vooral bedoeld voor ooievaarspas. Deze moest ik er van Paul uithalen voor PASS, en sowieso is complete winkelmand korting iets wat we nog niet echt besproken hadden toen ik dit maakte en wat ook niet formeel in scope is; de MVP is nu vooral bedoeld voor ooievaarspas.
Ik vind zeker prima om examples voor winkelmandkorting + kortingsbedrag op een specifiek product weer erin te hangen, maar voor nu is iig belangrijkst dat we de ooievaarspas case helemaal scherp hebben, want die wordt het eerst gebruikt
|
||||
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":
|
||||
|
||||
Loading…
Reference in New Issue
Block a user
WAAROM DIE BACKSLASH.
Is dit mooie-formatting shaming? :O