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
@ -28,99 +28,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Voucher for a product with required attributes:
|
||||
summary: Voucher for a single product with required attributes
|
||||
value:
|
||||
{
|
||||
"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-80001",
|
||||
"productDescription": "10 euro korting op Regiovrij maand.",
|
||||
"productCategory":
|
||||
{
|
||||
"productCategoryId": 9,
|
||||
"isTravelProduct": false,
|
||||
"name": "Voucher",
|
||||
},
|
||||
"amountInclTax": -1000,
|
||||
"requiredProducts":
|
||||
[
|
||||
{
|
||||
"productId": 126,
|
||||
"productName": "HTM-30001",
|
||||
"productDescription": "Regiovrij maand.",
|
||||
"_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/263",
|
||||
"method": "GET",
|
||||
},
|
||||
},
|
||||
},
|
||||
"mandatoryCustomerDataItems":
|
||||
[
|
||||
{
|
||||
"mandatoryCustomerDataItemId": 8,
|
||||
"customerDataItem": "padBirthDate",
|
||||
},
|
||||
{
|
||||
"mandatoryCustomerDataItemId": 4,
|
||||
"customerDataItem": "emailAddress",
|
||||
},
|
||||
],
|
||||
}
|
||||
Voucher for a whole order:
|
||||
summary: Voucher for a whole order
|
||||
value:
|
||||
{
|
||||
"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",
|
||||
},
|
||||
},
|
||||
},
|
||||
"mandatoryCustomerDataItems": [],
|
||||
}
|
||||
$ref: "#/components/schemas/issuedVoucherResponse"
|
||||
"403":
|
||||
description: Forbidden
|
||||
content:
|
||||
@ -176,6 +84,166 @@ components:
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
schemas:
|
||||
issuedVoucherResponse:
|
||||
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
|
||||
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"
|
||||
untilInclusive:
|
||||
type: string
|
||||
format: date-time
|
||||
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"
|
||||
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 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_details:
|
||||
type: object
|
||||
description: Link to get more details for the product that this voucher instance applies to
|
||||
properties:
|
||||
href:
|
||||
type: string
|
||||
example: https://api.integratielaag.nl/abt/touchpoint/1.0/products/982
|
||||
method:
|
||||
type: string
|
||||
example: GET
|
||||
mandatoryCustomerDataItems:
|
||||
type: array
|
||||
description: |-
|
||||
List of mandatory customer data items that are required to redeem this voucher.\
|
||||
The values provided for these data items may be checked against allowed values as provided by the voucher issuer.
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- mandatoryCustomerDataItemId
|
||||
- customerDataItem
|
||||
properties:
|
||||
mandatoryCustomerDataItemId:
|
||||
type: integer
|
||||
example: 8
|
||||
customerDataItem:
|
||||
type: string
|
||||
example: padBirthdate
|
||||
|
||||
unavailable:
|
||||
type: object
|
||||
rfc9457:
|
||||
|
||||
@ -35,7 +35,7 @@ paths:
|
||||
- name: productId
|
||||
in: query
|
||||
required: false
|
||||
description: Return a specific voucher definition by it's productId.
|
||||
description: Return a specific voucher definition by its productId.
|
||||
|
maxmartens marked this conversation as resolved
Outdated
|
||||
schema:
|
||||
type: integer
|
||||
example: 321
|
||||
@ -233,7 +233,7 @@ paths:
|
||||
- name: productId
|
||||
in: query
|
||||
required: false
|
||||
description: Return only issued vouchers that were issued for the given voucher definition (by it's productId).
|
||||
description: Return only issued vouchers that were issued for the given voucher definition (by its productId).
|
||||
|
maxmartens marked this conversation as resolved
Outdated
|
||||
schema:
|
||||
type: integer
|
||||
example: 321
|
||||
@ -370,7 +370,7 @@ paths:
|
||||
examples:
|
||||
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.
|
||||
description: This allows the voucher supplier to supply its own voucher code, which can be useful if the supplier 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.
|
||||
|
maxmartens marked this conversation as resolved
Outdated
bboterm
commented
*supplier *supplier
maxmartens
commented
i no use AI, dis is proof i no use AI, dis is proof
|
||||
value:
|
||||
{
|
||||
"voucherCode": "HTM-A7J-128-PYT",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user
its