430 lines
18 KiB
YAML
430 lines
18 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Service Engine APIs for HTM vouchers
|
|
description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub.
|
|
version: "1.0"
|
|
servers:
|
|
- url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0
|
|
paths:
|
|
/voucherdefinitions:
|
|
get:
|
|
tags:
|
|
- Vouchers
|
|
summary: Get a list of all voucher definitions that a touch point 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
|
|
retailer as the calling touch point are returned.
|
|
parameters:
|
|
- name: productId
|
|
in: query
|
|
required: false
|
|
description: Filter the voucher definitions on a specific product id.
|
|
schema:
|
|
type: integer
|
|
example: 263
|
|
- 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.
|
|
schema:
|
|
type: integer
|
|
example: 126
|
|
- name: showOnlyActive
|
|
in: query
|
|
required: false
|
|
description: Filter the voucher definitions on active selling periods. If true, only voucher definitions with at least one active selling period are returned. If false, all voucher definitions are returned regardless of their selling periods.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/unavailable"
|
|
examples:
|
|
No products / Empty list:
|
|
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
|
|
value:
|
|
{
|
|
"voucherDefinitions":
|
|
[
|
|
{
|
|
"productId": 1002,
|
|
"productName": "Korting Ooievaarspas",
|
|
"productDescription": "Kortingsvoucher voor houders van een Ooievaarspas",
|
|
"validityPeriod":
|
|
{
|
|
"validityPeriodId": 144,
|
|
"fromInclusive": "2023-12-31T23:00:00.000+00:00",
|
|
"toInclusive": "2028-11-25T04:00:00.000+00:00",
|
|
},
|
|
"productCategory":
|
|
{
|
|
"productCategoryId": 9,
|
|
"isTravelProduct": false,
|
|
"name": "Voucher",
|
|
},
|
|
"requiredProducts": [
|
|
{
|
|
"productId": 126,
|
|
"productName": "HTM-30001",
|
|
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
|
|
},
|
|
],
|
|
"mandatoryCustomerDataItems":
|
|
[
|
|
{
|
|
"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",
|
|
"sellingPeriods":
|
|
[
|
|
{
|
|
"sellingPeriodId": 78,
|
|
"fromInclusive": "2024-09-30T23:00:00.000+00:00",
|
|
"toInclusive": "2028-11-17T23:00:00.000+00:00",
|
|
"salesTouchpoint":
|
|
{
|
|
"salesTouchpointId": 1001,
|
|
"name": "Gemeente Den Haag",
|
|
"isActive": true,
|
|
"retailer":
|
|
{
|
|
"retailerId": 1001,
|
|
"name": "Gemeente Den Haag",
|
|
"street": "Koningin Julianaplein",
|
|
"number": "10",
|
|
"numberAddition": null,
|
|
"postalCode": "2595 AA",
|
|
"city": "Den Haag",
|
|
"country": "Nederland",
|
|
"emailAddress": "info@denhaag.nl",
|
|
"phoneNumber": "070 374 9002",
|
|
"taxId": "572309345923",
|
|
"imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg",
|
|
},
|
|
},
|
|
"forbiddenPaymentMethods": [],
|
|
"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",
|
|
"internalPrice": 0.0000,
|
|
"taxCode": "V09",
|
|
"taxPercentage": 9.0000,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
}
|
|
"403":
|
|
description: Forbidden
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Access denied due to insufficient permissions:
|
|
summary: Access denied due to insufficient permissions
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/forbidden",
|
|
"title": "Access denied",
|
|
"detail": "You do not have permission to access this resource.",
|
|
"instance": "/voucherdefinitions",
|
|
}
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Voucher not found:
|
|
summary: Voucher not found
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/not-found",
|
|
"title": "Voucher not found",
|
|
"detail": "The voucher definition does not exist.",
|
|
"instance": "/voucherdefinitions",
|
|
}
|
|
"500":
|
|
description: Internal server error
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Unexpected server error:
|
|
summary: Unexpected server error
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/internal-server-error",
|
|
"title": "Internal Server Error",
|
|
"detail": "An unexpected error occurred while processing your request.",
|
|
"instance": "/voucherdefinitions",
|
|
}
|
|
/issuedvouchers:
|
|
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.
|
|
parameters:
|
|
- name: issuedVoucherId
|
|
in: query
|
|
required: false
|
|
description: The unique identifier of the issued voucher instance to retrieve.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90
|
|
- name: voucherCode
|
|
in: query
|
|
required: false
|
|
description: The unique code of the issued voucher to retrieve.
|
|
schema:
|
|
type: string
|
|
example: VOUCHER123
|
|
- name: productId
|
|
in: query
|
|
required: false
|
|
description: The unique identifier of the product for which to retrieve all issued vouchers.
|
|
schema:
|
|
type: integer
|
|
example: 263
|
|
- name: highestVoucherStatusId
|
|
in: query
|
|
required: false
|
|
explode: false
|
|
description: |-
|
|
The highest voucher status id to filter the issued vouchers on.
|
|
- 1 = new
|
|
- 2 = issued
|
|
- 3 = redeemed
|
|
- 4 = revoked
|
|
- 5 = expired
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 2]
|
|
tags:
|
|
- Vouchers
|
|
responses:
|
|
"200":
|
|
description: Successful retrieval of voucher instance
|
|
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:
|
|
{
|
|
"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-80001",
|
|
"productDescription": "10 euro korting op Regiovrij maand.",
|
|
"productCategory":
|
|
{
|
|
"productCategoryId": 9,
|
|
"isTravelProduct": false,
|
|
"name": "Voucher",
|
|
},
|
|
"amountInclTax": -1000,
|
|
"requiredProducts":
|
|
[
|
|
{
|
|
"productId": 126,
|
|
"productName": "HTM-30001",
|
|
"productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
|
|
"_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:
|
|
{
|
|
"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",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
"mandatoryCustomerDataItems": [],
|
|
],
|
|
}
|
|
"403":
|
|
description: Forbidden
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Access denied due to insufficient permissions:
|
|
summary: Access denied due to insufficient permissions
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/forbidden",
|
|
"title": "Access denied",
|
|
"detail": "You do not have permission to access this resource.",
|
|
"instance": "/issuedvouchers",
|
|
}
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Voucher not found:
|
|
summary: Voucher not found
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/not-found",
|
|
"title": "Voucher not found",
|
|
"detail": "The voucher with code VOUCHER123 does not exist.",
|
|
"instance": "/issuedvouchers",
|
|
}
|
|
"500":
|
|
description: Internal server error
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: "#/components/schemas/rfc9457"
|
|
examples:
|
|
Unexpected server error:
|
|
summary: Unexpected server error
|
|
value:
|
|
{
|
|
"type": "https://example.com/probs/internal-server-error",
|
|
"title": "Internal Server Error",
|
|
"detail": "An unexpected error occurred while processing your request.",
|
|
"instance": "/issuedvouchers",
|
|
}
|
|
components:
|
|
securitySchemes:
|
|
bearerToken:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
schemas:
|
|
unavailable:
|
|
type: object
|
|
rfc9457:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
format: url
|
|
example: https://example.com/probs/out-of-credit
|
|
title:
|
|
type: string
|
|
example: You do not have enough credit.
|
|
detail:
|
|
type: string
|
|
example: Your current balance is 30, but that costs 50.
|
|
instance:
|
|
type: string
|
|
example: /account/12345/msgs/abc
|
|
balance:
|
|
type: string
|
|
example: 30
|
|
accounts:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- /account/12345
|
|
- /account/67890
|