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:
  /issuedvouchers/{voucherCode}:
    get:
      summary: Get voucher details by voucher code
      description: Retrieve voucher details using its unique voucher code.
      parameters:
        - name: voucherCode
          in: path
          required: true
          description: The unique code of the voucher details to retrieve.
          schema:
            type: string
      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:
                    {
                      "issuedVoucher":
                        {
                          "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:
                    {
                      "issuedVoucher":
                        {
                          "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/VOUCHER123",
                    }
        "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/VOUCHER123",
                    }
        "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/VOUCHER123",
                    }
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