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.
  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: 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.
            This query parameter is only intended for administrative purposes, since the touch point 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 touch points within the same retailer, for example to retrieve voucher definitions for a specific sales touch point that is different from the calling touch point.
          schema:
            type: integer
            example: 1001
        - 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: 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.
            This query parameter is only intended for administrative purposes, since the touch point 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 touch points within the same retailer, for example to retrieve issued vouchers for a specific sales touch point that is different from the calling touch point.
          schema:
            type: integer
            example: 1001
        - 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": "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",
                                      },
                                  },
                              },
                            "claims":
                              [
                                {
                                  "mandatoryCustomerDataItem":
                                    {
                                      "mandatoryCustomerDataItemId": 8,
                                      "customerDataItem": "padBirthDate",
                                    },
                                  "value": "1980-06-31",
                                },
                                {
                                  "mandatoryCustomerDataItem":
                                    {
                                      "mandatoryCustomerDataItemId": 4,
                                      "customerDataItem": "emailAddress",
                                    },
                                  "value": "harry@griffindor.co.uk",
                                },
                              ],
                          },
                        ],
                    }
                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",
                                      },
                                  },
                              },
                          },
                          "claims": [],
                        ],
                    }
        "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",
                    }
    post:
      summary: Issue a voucher for a specific product
      description: |
        Issue a voucher for a specific product. The voucher will be issued for the touch point that is associated with the access token used in the request. 
        The product for which the voucher should be issued must have active selling periods for touch points within the same retailer as the calling touch point.
      tags:
        - Vouchers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Issue a voucher with prefilled voucher code:
                summary: Issue a voucher with prefilled voucher code
                value:
                  {
                    "voucherCode": "VOUCHER123",
                    "fromInclusive": "2024-10-04T00:00:00.000",
                    "untilInclusive": "2024-11-04T00:00:00.000",
                    "productId": 263,
                    "voucherClaims":
                      [
                        {
                          "mandatoryCustomerDataItemId": 8,
                          "value": "1970-01-01",
                        },
                        {
                          "mandatoryCustomerDataItemId": 4,
                          "value": "stasjo@html.nl",
                        },
                      ],
                  }
              Issue a voucher without prefilled voucher code:
                summary: Issue a voucher without prefilled voucher code
                value:
                  {
                    "fromInclusive": "2024-10-04T00:00:00.000",
                    "untilInclusive": "2024-11-04T00:00:00.000",
                    "productId": 263,
                    "voucherClaims":
                      [
                        {
                          "mandatoryCustomerDataItemId": 8,
                          "value": "1970-01-01",
                        },
                        {
                          "mandatoryCustomerDataItemId": 4,
                          "value": "stasjo@html.nl",
                        },
                      ],
                  }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Successfully issued a voucher:
                  summary: Successfully issued a voucher
                  value:
                    {
                      "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
                      "voucherCode": "HKV-A7J-128-PYT",
                      "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",
                                },
                            },
                        },
                    }
  /issuedvouchers/{issuedVoucherId}:
    parameters:
      - name: issuedVoucherId
        in: path
        required: true
        description: The unique identifier of the issued voucher instance to update the status for.
        schema:
          type: string
          format: uuid
          example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90
    patch:
      summary: Update the status of an issued voucher
      description: Update the status of an issued voucher. This can be used to mark a voucher as redeemed, revoked or expired.
      tags:
        - Vouchers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Mark a voucher as expired:
                summary: Mark a voucher as expired
                value:
                  {
                    "voucherStatusId": 5,
                  }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Successfully updated the status of a voucher:
                  summary: Successfully updated the status of a voucher
                  value:
                    {
                      "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
                      "voucherCode": "HKV-A7J-128-PYT",
                      "fromInclusive": "2024-10-04T00:00:00.000",
                      "untilInclusive": "2024-11-04T00:00:00.000",
                      "voucherStatus": { "voucherStatusId": 5, "name": "Expired" },
                      "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",
                                },
                            },
                        },
                    }
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