Compare commits
No commits in common. "e5a0b52d1be837316d997a7e0395763f018c90dd" and "f198c1633b59fc58cb3af8208ef83dde9a6f01bc" have entirely different histories.
e5a0b52d1b
...
f198c1633b
@ -1,17 +1,17 @@
|
|||||||
openapi: 3.0.1
|
openapi: 3.0.1
|
||||||
info:
|
info:
|
||||||
title: Service Engine APIs for HTM voucher for sales Touchpoint
|
title: Service Engine APIs for HTM voucher for sales Touchpint
|
||||||
description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the APIs for sales touchpoints.
|
description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the api's for sales touchpoints.
|
||||||
version: "1.0"
|
version: "1.0"
|
||||||
servers:
|
servers:
|
||||||
- url: https://services.acc.api.htm.nl/abt/abtvouchersTouchpoint/1.0
|
- url: https://services.acc.api.htm.nl/abt/abtvouchersTouchpoint/1.0
|
||||||
paths:
|
paths:
|
||||||
/issuedvouchers/{voucherCode}:
|
/issuedvouchers/{voucherCode}:
|
||||||
get:
|
get:
|
||||||
summary: Get details of a voucher, that was issued for a specific touchpoint
|
summary: Get details of a voucher, that was issued for a specific touch point
|
||||||
description:
|
description:
|
||||||
Get details of an issued voucher for a specific touchpoint. This means that only products that the calling touchpoint is allowed to see or sell
|
Get details of an issued voucher for a specific touch point. This means that only products that the calling touch point is allowed to see or sell
|
||||||
(i.e. has active sellingPeriods for touchPointId of the calling touchpoint) are returned.
|
(i.e. has active sellingPeriods for touchPointId of the calling touch point) are returned.
|
||||||
parameters:
|
parameters:
|
||||||
- name: voucherCode
|
- name: voucherCode
|
||||||
in: path
|
in: path
|
||||||
@ -28,132 +28,98 @@ paths:
|
|||||||
content:
|
content:
|
||||||
application/json:
|
application/json:
|
||||||
schema:
|
schema:
|
||||||
$ref: "#/components/schemas/salesTouchpointIssuedVoucherResponse"
|
$ref: "#/components/schemas/unavailable"
|
||||||
examples:
|
examples:
|
||||||
Voucher that grants a voucher-only product for free:
|
Voucher for a product with required attributes:
|
||||||
summary: Voucher that grants a voucher-only product for free
|
summary: Voucher for a single product with required attributes
|
||||||
description: |-
|
|
||||||
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
|
|
||||||
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.
|
|
||||||
value:
|
value:
|
||||||
{
|
{
|
||||||
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
|
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
|
||||||
"voucherCode": "HTM-A7J-128-PYT",
|
"voucherCode": "VOUCHER123",
|
||||||
"fromInclusive": "2024-10-04T00:00:00.000",
|
"fromInclusive": "2024-10-04T00:00:00.000",
|
||||||
"untilInclusive": "2024-11-04T00:00:00.000",
|
"untilInclusive": "2024-11-04T00:00:00.000",
|
||||||
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
|
"voucherStatus": { "voucherStatusId": 1, "name": "New" },
|
||||||
"product":
|
"product":
|
||||||
{
|
{
|
||||||
"productId": 263,
|
"productId": 263,
|
||||||
"productName": "Voucher Ooievaarspas-product AOW",
|
"productName": "HTM-80001",
|
||||||
"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": "10 euro korting op Regiovrij maand.",
|
||||||
"amountInclTax": 0,
|
"productCategory":
|
||||||
|
{
|
||||||
|
"productCategoryId": 9,
|
||||||
|
"isTravelProduct": false,
|
||||||
|
"name": "Voucher",
|
||||||
|
},
|
||||||
|
"amountInclTax": -1000,
|
||||||
"requiredProducts":
|
"requiredProducts":
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"productId": 982,
|
"productId": 126,
|
||||||
"productName": "Ooievaarspas voor AOW-ers in Den Haag",
|
"productName": "HTM-30001",
|
||||||
"productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
|
"productDescription": "Regiovrij maand.",
|
||||||
"productCategory":
|
|
||||||
{
|
|
||||||
"productCategoryId": 2,
|
|
||||||
"isTravelProduct": true,
|
|
||||||
"name": "Afgekocht reisrecht",
|
|
||||||
},
|
|
||||||
"amountInclTax": 0,
|
|
||||||
"_links":
|
"_links":
|
||||||
{
|
{
|
||||||
"get_details":
|
"get_details":
|
||||||
{
|
{
|
||||||
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/982",
|
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126",
|
||||||
"method": "GET",
|
"method": "GET",
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
]
|
],
|
||||||
|
"_links":
|
||||||
|
{
|
||||||
|
"get_details":
|
||||||
|
{
|
||||||
|
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
|
||||||
|
"method": "GET",
|
||||||
|
},
|
||||||
|
},
|
||||||
},
|
},
|
||||||
"mandatoryCustomerDataItems":
|
"mandatoryCustomerDataItems":
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"mandatoryCustomerDataItemId": 8,
|
"mandatoryCustomerDataItemId": 8,
|
||||||
"customerDataItem": "padBirthDate"
|
"customerDataItem": "padBirthDate",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"mandatoryCustomerDataItemId": 4,
|
||||||
|
"customerDataItem": "emailAddress",
|
||||||
|
},
|
||||||
|
],
|
||||||
}
|
}
|
||||||
]
|
Voucher for a whole order:
|
||||||
}
|
summary: Voucher for a whole order
|
||||||
Voucher that grants a hybrid product for a reduced price:
|
|
||||||
summary: Voucher that grants a hybrid product for a reduced price
|
|
||||||
description: |-
|
|
||||||
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)
|
|
||||||
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.
|
|
||||||
value:
|
value:
|
||||||
{
|
{
|
||||||
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
|
"issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
|
||||||
"voucherCode": "HTM-A7J-128-PYT",
|
"voucherCode": "VOUCHER123",
|
||||||
"fromInclusive": "2024-10-04T00:00:00.000",
|
"fromInclusive": "2024-10-04T00:00:00.000",
|
||||||
"untilInclusive": "2024-11-04T00:00:00.000",
|
"untilInclusive": "2024-11-04T00:00:00.000",
|
||||||
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
|
"voucherStatus": { "voucherStatusId": 1, "name": "New" },
|
||||||
"product":
|
"product":
|
||||||
{
|
{
|
||||||
"productId": 264,
|
"productId": 263,
|
||||||
"productName": "Kortingsvoucher HTM 20% Korting ",
|
"productName": "HTM-80002",
|
||||||
"productDescription": "Voucher waarmee het product \"HTM 20% Korting\" voor een lagere prijs kan worden aangeschaft.",
|
"productDescription": "10 euro korting op je gehele winkelmand.",
|
||||||
"amountInclTax": 100,
|
|
||||||
"requiredProducts":
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"productId": 984,
|
|
||||||
"productName": "HTM 20% Korting",
|
|
||||||
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
|
|
||||||
"productCategory":
|
"productCategory":
|
||||||
{
|
{
|
||||||
"productCategoryId": 1,
|
"productCategoryId": 9,
|
||||||
"isTravelProduct": true,
|
"isTravelProduct": false,
|
||||||
"name": "Kortingsabonnement",
|
"name": "Voucher",
|
||||||
},
|
},
|
||||||
"amountInclTax": 500,
|
"amountInclTax": -1000,
|
||||||
|
"requiredProducts": [],
|
||||||
"_links":
|
"_links":
|
||||||
{
|
{
|
||||||
"get_details":
|
"get_details":
|
||||||
{
|
{
|
||||||
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/984",
|
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263",
|
||||||
"method": "GET",
|
"method": "GET",
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
]
|
"mandatoryCustomerDataItems": [],
|
||||||
},
|
|
||||||
"mandatoryCustomerDataItems": []
|
|
||||||
}
|
|
||||||
Voucher that grants a discount for a whole order:
|
|
||||||
summary: Voucher that grants a discount for a whole order
|
|
||||||
description: |-
|
|
||||||
Voucher that grants a discount for a whole order. 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).
|
|
||||||
value:
|
|
||||||
{
|
|
||||||
"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": []
|
|
||||||
},
|
|
||||||
"mandatoryCustomerDataItems": []
|
|
||||||
}
|
}
|
||||||
"403":
|
"403":
|
||||||
description: Forbidden
|
description: Forbidden
|
||||||
@ -171,20 +137,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",
|
||||||
}
|
}
|
||||||
"400":
|
"404":
|
||||||
description: Bad request
|
description: Not found
|
||||||
content:
|
content:
|
||||||
application/problem+json:
|
application/problem+json:
|
||||||
schema:
|
schema:
|
||||||
$ref: "#/components/schemas/rfc9457"
|
$ref: "#/components/schemas/rfc9457"
|
||||||
examples:
|
examples:
|
||||||
Invalid voucher code:
|
Voucher not found:
|
||||||
summary: Invalid voucher code
|
summary: Voucher not found
|
||||||
value:
|
value:
|
||||||
{
|
{
|
||||||
"type": "https://example.com/probs/bad-request",
|
"type": "https://example.com/probs/not-found",
|
||||||
"title": "Invalid voucher code",
|
"title": "Voucher not found",
|
||||||
"detail": "No valid voucher found for code VOUCHER123.",
|
"detail": "The voucher with code VOUCHER123 does not exist.",
|
||||||
"instance": "/issuedvouchers",
|
"instance": "/issuedvouchers",
|
||||||
}
|
}
|
||||||
"500":
|
"500":
|
||||||
@ -210,166 +176,6 @@ components:
|
|||||||
scheme: bearer
|
scheme: bearer
|
||||||
bearerFormat: JWT
|
bearerFormat: JWT
|
||||||
schemas:
|
schemas:
|
||||||
salesTouchpointIssuedVoucherResponse:
|
|
||||||
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_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:
|
unavailable:
|
||||||
type: object
|
type: object
|
||||||
rfc9457:
|
rfc9457:
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user