Compare commits
11 Commits
develop
...
features/O
| Author | SHA1 | Date | |
|---|---|---|---|
| 42ff41baea | |||
| 699c633a4e | |||
| 95bc19d7ff | |||
| 8e77863480 | |||
| 07e1dc91e3 | |||
| 75531b4fdc | |||
| 00a98a6178 | |||
| 937a0323ed | |||
| ebee1178ef | |||
| 6e37b7c4fe | |||
| a0ebde6ae2 |
1845
src/openapi/container/abt-container-notifications.yaml
Normal file
1845
src/openapi/container/abt-container-notifications.yaml
Normal file
File diff suppressed because it is too large
Load Diff
403
src/openapi/container/abt-container-tokens.yaml
Normal file
403
src/openapi/container/abt-container-tokens.yaml
Normal file
@ -0,0 +1,403 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Integration layer APIs for token storage for ABT
|
||||
description: >-
|
||||
APIs that give business processes access to the security and authorization state of a token within the scope of HTM. In the backend this is connected to a container which handles the accessToken en refreshToken management for an OVpas as given by GBO.
|
||||
version: "1.0"
|
||||
servers:
|
||||
- url: https://services.acc.api.htm.nl/abt/containertokens/1.0
|
||||
security:
|
||||
- oAuthSample: [profile]
|
||||
tags:
|
||||
- name: securitytokens
|
||||
paths:
|
||||
/securitytokens:
|
||||
post:
|
||||
tags:
|
||||
- securitytokens
|
||||
summary: Create a new security token entry in the vault
|
||||
description: Create a new security token entry in the vault, if the customerProfileId has been supplied create in the customerToken DB otherwise in the AnonymousToken DB
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/CreateSecurityTokenBody"
|
||||
examples:
|
||||
token details:
|
||||
value:
|
||||
{
|
||||
"xTat": "cf694905-7f76-4799-b0bc-490716921323",
|
||||
"otpKey": "123456789123456789123456789abcde",
|
||||
"customerProfileId": 12314
|
||||
}
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
"400":
|
||||
description: Bad Request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Missing Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Missing Mandatory Parameter
|
||||
detail: Required parameter {0} is missing.
|
||||
Invalid Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Invalid Parameter
|
||||
detail: Required parameter {0} is invalid.
|
||||
"401":
|
||||
description: Unauthorized
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Unauthorized:
|
||||
value:
|
||||
status: 401
|
||||
title: Unauthorized
|
||||
detail: Invalid Access Token
|
||||
"404":
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
TAT not found:
|
||||
value:
|
||||
status: 404
|
||||
title: Not Found
|
||||
detail: TAT Account Not Found
|
||||
"409":
|
||||
description: Conflict
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
TAT already exists:
|
||||
value:
|
||||
status: 409
|
||||
title: Conflict
|
||||
detail: Security Token already exists
|
||||
"500":
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Internal Server Error:
|
||||
value:
|
||||
status: 500
|
||||
title: Internal Server Error
|
||||
detail: An unknown error has occurred
|
||||
/securitytokens/{xTat}/status:
|
||||
parameters:
|
||||
- name: xTat
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
example: 85dbeacc-b9aa-4d5b-bdec-9319010c597f
|
||||
required: true
|
||||
description: The xTat of the OVpastoken for which the status needs to be checked
|
||||
- name: customerProfileId
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
example: 323
|
||||
required: false
|
||||
description: The id of the customer Profile for which the request is being done, if customer has identified themselves
|
||||
get:
|
||||
tags:
|
||||
- securitytokens
|
||||
summary: Request the security and authorization status of an OV pas token
|
||||
description: Request the security and authorization status of an OV pas token, if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SecurityTokenStatusResponse"
|
||||
examples:
|
||||
Not secured and not authorized :
|
||||
summary: Not secured, not authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": false,
|
||||
"isSecured": false
|
||||
}
|
||||
Secured and not authorized :
|
||||
summary: Secured, not authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": false,
|
||||
"isSecured": true
|
||||
}
|
||||
Secured and authorized :
|
||||
summary: Secured and authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": true,
|
||||
"isSecured": true
|
||||
}
|
||||
"400":
|
||||
description: Bad Request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Missing Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Missing Mandatory Parameter
|
||||
detail: Required parameter {0} is missing.
|
||||
Invalid Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Invalid Parameter
|
||||
detail: Required parameter {0} is invalid.
|
||||
"401":
|
||||
description: Unauthorized
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Unauthorized:
|
||||
value:
|
||||
status: 401
|
||||
title: Unauthorized
|
||||
detail: Invalid Access Token
|
||||
"404":
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
TAT not found:
|
||||
value:
|
||||
status: 404
|
||||
title: Not Found
|
||||
detail: TAT Account Not Found
|
||||
"500":
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Internal Server Error:
|
||||
value:
|
||||
status: 500
|
||||
title: Internal Server Error
|
||||
detail: An unknown error has occurred
|
||||
/securitytokens/{xTat}:
|
||||
parameters:
|
||||
- name: xTat
|
||||
in: path
|
||||
schema:
|
||||
type: string
|
||||
example: uuid
|
||||
required: true
|
||||
description: The xTat of the ovPastoken for which the status needs to be checked
|
||||
- name: customerProfileId
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
example: 323
|
||||
required: false
|
||||
description: The id of the customer Profile for which the request is being done, if customer has identified themselves
|
||||
patch:
|
||||
tags:
|
||||
- securitytokens
|
||||
summary: Validate the supplied OTP and secure and/or authorize the token
|
||||
description: Validate the supplied OTP and secure and/or authorize the token if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SecurityValidateTokenBody"
|
||||
examples:
|
||||
token:
|
||||
value:
|
||||
{
|
||||
"otp": "123456"
|
||||
}
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SecurityTokenStatusResponse"
|
||||
examples:
|
||||
Not secured and not authorized :
|
||||
summary: Not secured, not authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": false,
|
||||
"isSecured": false
|
||||
}
|
||||
Secured and not authorized :
|
||||
summary: Secured, not authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": false,
|
||||
"isSecured": true
|
||||
}
|
||||
Secured and authorized :
|
||||
summary: Secured and authorized
|
||||
value:
|
||||
{
|
||||
"isAuthorized": true,
|
||||
"isSecured": true
|
||||
}
|
||||
"400":
|
||||
description: Bad Request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Missing Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Missing Mandatory Parameter
|
||||
detail: Required parameter {0} is missing.
|
||||
Invalid Parameters:
|
||||
value:
|
||||
status: 400
|
||||
title: Invalid Parameter
|
||||
detail: Required parameter {0} is invalid.
|
||||
"422":
|
||||
description: Unprocessable Entity
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Validation failed:
|
||||
value:
|
||||
status: 422
|
||||
title: OTP validation failed
|
||||
detail: The supplied OTP could not be validated
|
||||
"401":
|
||||
description: Unauthorized
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Unauthorized:
|
||||
value:
|
||||
status: 401
|
||||
title: Unauthorized
|
||||
detail: Invalid Access Token
|
||||
"404":
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
TAT not found:
|
||||
value:
|
||||
status: 404
|
||||
title: Not Found
|
||||
detail: TAT Account Not Found
|
||||
"500":
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Internal Server Error:
|
||||
value:
|
||||
status: 500
|
||||
title: Internal Server Error
|
||||
detail: An unknown error has occurred
|
||||
components:
|
||||
securitySchemes:
|
||||
oAuthSample:
|
||||
type: oauth2
|
||||
description: This API uses OAuth 2 with the clientCredentials flow. [More info](https://api.example.com/docs/auth)
|
||||
flows:
|
||||
clientCredentials: # <---- OAuth flow( clientCredentials)
|
||||
tokenUrl: https://identity.{env}.api.htm.nl/oauth2/token
|
||||
scopes:
|
||||
profile: "Access user profile"
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
description: Default response when an invalid request has been sent
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: integer
|
||||
description: >-
|
||||
A status IS An integer that represents the HTTP status code of the
|
||||
response.
|
||||
example: 400
|
||||
title:
|
||||
type: string
|
||||
description: A title IS A string that provides a brief summary of the error.
|
||||
detail:
|
||||
type: string
|
||||
description: A detail IS A string that provides more details about the error.
|
||||
CreateSecurityTokenBody:
|
||||
description: Body for when the a new security token entry is created
|
||||
type: object
|
||||
required:
|
||||
- xTat
|
||||
- otpKey
|
||||
properties:
|
||||
xTat:
|
||||
type : string
|
||||
description: >-
|
||||
Unique identifier for the GBO transit account
|
||||
example: 03071794-482a-4168-b60f-84669a9e6a76
|
||||
otpKey:
|
||||
type : string
|
||||
description: >-
|
||||
Key used to validate the OTP at GBO
|
||||
example: 123456789123456789123456789abcde
|
||||
customerProfileId:
|
||||
type : integer
|
||||
description: >-
|
||||
CustomerProfileId of the account requesting security or giving authorization
|
||||
example: 123456
|
||||
SecurityTokenStatusResponse:
|
||||
description: Response for when the status of a token is requested
|
||||
type: object
|
||||
properties:
|
||||
isSecured:
|
||||
type: boolean
|
||||
description: >-
|
||||
Is the OVpas secured according to the GBO
|
||||
example: false
|
||||
isAuthorized:
|
||||
type: boolean
|
||||
description: >-
|
||||
Does HTM have the authorization to access the secured the data of the OVpas
|
||||
example: false
|
||||
SecurityValidateTokenBody:
|
||||
description: Body for when the a token entry is validated
|
||||
type: object
|
||||
required:
|
||||
- otp
|
||||
properties:
|
||||
otp:
|
||||
type : string
|
||||
description: >-
|
||||
OTP to be used to secure the token and retrieve the JWT at GBO
|
||||
example: 123456
|
||||
@ -45,36 +45,12 @@ paths:
|
||||
"contractStatus":
|
||||
{ "contractStatusId": 2, "name": "active" },
|
||||
"productId": 1,
|
||||
"productName": "HTM Maand 20% korting doorlopend",
|
||||
"termDuration": "P1M",
|
||||
"productName": "HTM Maand 20% korting",
|
||||
"termDuration": "P0Y1M0D",
|
||||
"billingDay": 15,
|
||||
"highestInvoiceTerm": 1,
|
||||
"created": "2024-08-01T15:01:00.000Z",
|
||||
"created": "2024-08-01 15:01:00.000",
|
||||
"ovPayTokenId": 1337,
|
||||
"contractVersions": [
|
||||
{
|
||||
"contractVersionId": 1,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM Maand 20% korting doorlopend",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2024-08-01T15:01:00.000Z",
|
||||
"end": "2025-01-01T03:00:00.000Z"
|
||||
},
|
||||
{
|
||||
"contractVersionId": 2,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM Maand 20% korting doorlopend",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9,
|
||||
"termAmountInclTax": 500,
|
||||
"start": "2025-01-01T03:00:00.000Z",
|
||||
"end": null
|
||||
}
|
||||
],
|
||||
"_links":
|
||||
{
|
||||
"get_token":
|
||||
@ -92,38 +68,14 @@ paths:
|
||||
"orderLineId": "42f68042-908f-41f4-9d9b-4cab843ff0e8",
|
||||
"touchpointId": 2,
|
||||
"contractStatus":
|
||||
{ "contractStatusId": 6, "name": "pending cancellation" },
|
||||
{ "contractStatusId": 1, "name": "new" },
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"termDuration": "P1M",
|
||||
"productName": "HTM Maand 20% korting",
|
||||
"termDuration": "P0Y1M0D",
|
||||
"billingDay": 15,
|
||||
"highestInvoiceTerm": 1,
|
||||
"created": "2024-08-01T15:01:00.000Z",
|
||||
"created": "2024-08-01 15:01:00.000",
|
||||
"ovPayTokenId": 1338,
|
||||
"contractVersions": [
|
||||
{
|
||||
"contractVersionId": 1,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2024-08-01T15:01:00.000Z",
|
||||
"end": "2025-01-01T03:00:00.000Z"
|
||||
},
|
||||
{
|
||||
"contractVersionId": 2,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9,
|
||||
"termAmountInclTax": 500,
|
||||
"start": "2025-01-01T03:00:00.000Z",
|
||||
"end": "2025-02-01T03:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"_links":
|
||||
{
|
||||
"get_token":
|
||||
@ -202,8 +154,8 @@ paths:
|
||||
"contractStatus":
|
||||
{ "contractStatusId": 2, "name": "active" },
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"termDuration": "P1M",
|
||||
"productName": "HTM Maand 20% korting",
|
||||
"termDuration": "P0Y1M0D",
|
||||
"billingDay": 15,
|
||||
"highestInvoiceTerm": 1,
|
||||
"ovPayTokenId": 1337,
|
||||
@ -213,22 +165,22 @@ paths:
|
||||
"contractVersionId": 1,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"productName": "HTM Maand 20% korting",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9.0,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2024-08-01T15:01:00.000Z",
|
||||
"end": "2025-01-01T03:00:00.000Z",
|
||||
"start": "2024-07-04 15:01:00.000",
|
||||
"end": "2024-12-31 15:01:00.000",
|
||||
},
|
||||
{
|
||||
"contractVersionId": 2,
|
||||
"termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
|
||||
"productId": 1,
|
||||
"productName": "HTM 20% Korting doorlopend",
|
||||
"productName": "HTM Maand 20% korting",
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9.0,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2025-01-01T03:00:00.000Z",
|
||||
"start": "2025-01-01 15:01:00.000",
|
||||
},
|
||||
],
|
||||
"contractActions":
|
||||
@ -238,7 +190,7 @@ paths:
|
||||
"actionType":
|
||||
{ "actionTypeId": 1, "name": "create" },
|
||||
"user": "subid123456",
|
||||
"timestamp": "2024-07-02T15:01:00.000Z",
|
||||
"timestamp": "2024-07-02 15:01:00.000",
|
||||
"details": "Contract created",
|
||||
"correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
|
||||
},
|
||||
@ -247,7 +199,7 @@ paths:
|
||||
"actionType":
|
||||
{ "actionTypeId": 2, "name": "change" },
|
||||
"user": "subid123456",
|
||||
"timestamp": "2024-07-03T15:01:00.000Z",
|
||||
"timestamp": "2024-07-03 15:01:00.000",
|
||||
"details": "Contract changed",
|
||||
"correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
|
||||
},
|
||||
@ -259,8 +211,8 @@ paths:
|
||||
"externalReference": "F2024-0001",
|
||||
"term": 1,
|
||||
"invoiceDate": "2024-07-02",
|
||||
"created": "2024-07-02T15:01:00.000Z",
|
||||
"updated": "2024-07-02T15:01:00.000Z",
|
||||
"created": "2024-07-02 15:01:00.000",
|
||||
"updated": "2024-07-02 15:01:00.000",
|
||||
"state": "invoice_created",
|
||||
"data": "{json}",
|
||||
"isCredit": false,
|
||||
@ -318,8 +270,8 @@ paths:
|
||||
"externalReference": "F2024-0001",
|
||||
"term": 1,
|
||||
"invoiceDate": "2024-07-02",
|
||||
"created": "2024-07-02T15:01:34.000Z",
|
||||
"updated": "2024-07-04T00:04:56.000Z",
|
||||
"created": "2024-07-02 15:01:34.000",
|
||||
"updated": "2024-07-04 00:04:56.000",
|
||||
"state": "invoice_created",
|
||||
"public_link": "http://mijnfactuurinzien.nl/F2024-0001",
|
||||
"isCredit": false,
|
||||
@ -330,8 +282,8 @@ paths:
|
||||
"externalReference": "F2024-0002",
|
||||
"term": 2,
|
||||
"invoiceDate": "2024-08-02",
|
||||
"created": "2024-08-02T15:01:34.000Z",
|
||||
"updated": "2024-08-04T00:04:56.000Z",
|
||||
"created": "2024-08-02 15:01:34.000",
|
||||
"updated": "2024-08-04 00:04:56.000",
|
||||
"state": "invoice_created",
|
||||
"public_link": "http://mijnfactuurinzien.nl/F2024-0002",
|
||||
"isCredit": false,
|
||||
@ -376,8 +328,8 @@ paths:
|
||||
"cancellationMoment": "termBound",
|
||||
"termDuration": "P1M",
|
||||
"billingDay": 18,
|
||||
"cancellationFrom": "2024-08-10T00:00:00Z",
|
||||
"cancellationUntil": "2026-08-10T00:00:00Z",
|
||||
"cancellationFrom": "2024-08-10T00:00:00",
|
||||
"cancellationUntil": "2026-08-10T00:00:00",
|
||||
}
|
||||
/contracts/{contractId}/cancellationvalidation:
|
||||
parameters:
|
||||
@ -430,7 +382,7 @@ paths:
|
||||
{
|
||||
"validationResult": true,
|
||||
"validationMessage": "",
|
||||
"end": "2024-08-10T03:59:59Z",
|
||||
"end": "2024-08-10T03:59:59",
|
||||
"refundAmount": 2489,
|
||||
"refundMethods": ["creditInvoice", "iDeal"],
|
||||
}
|
||||
@ -499,7 +451,7 @@ paths:
|
||||
the refund amount and refund method.
|
||||
value:
|
||||
{
|
||||
"end": "2024-08-10T03:59:59Z",
|
||||
"end": "2024-08-10T03:59:59",
|
||||
"refundAmount": 2489,
|
||||
"refundMethod": "creditInvoice",
|
||||
}
|
||||
@ -564,8 +516,8 @@ paths:
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9.0,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2024-07-04T15:01:00.000Z",
|
||||
"end": "2024-12-31T15:01:00.000Z",
|
||||
"start": "2024-07-04 15:01:00.000",
|
||||
"end": "2024-12-31 15:01:00.000",
|
||||
},
|
||||
{
|
||||
"contractVersionId": 2,
|
||||
@ -575,8 +527,7 @@ paths:
|
||||
"taxCode": "V9",
|
||||
"taxPercentage": 9.0,
|
||||
"termAmountInclTax": 400,
|
||||
"start": "2025-01-01T15:01:00.000Z",
|
||||
"end": null
|
||||
"start": "2025-01-01 15:01:00.000",
|
||||
},
|
||||
],
|
||||
"contractActions":
|
||||
@ -586,7 +537,7 @@ paths:
|
||||
"actionType":
|
||||
{ "actionTypeId": 1, "name": "create" },
|
||||
"user": "subid123456",
|
||||
"timestamp": "2024-07-02T15:01:00.000Z",
|
||||
"timestamp": "2024-07-02 15:01:00.000",
|
||||
"details": "Contract created",
|
||||
"correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
|
||||
},
|
||||
@ -595,7 +546,7 @@ paths:
|
||||
"actionType":
|
||||
{ "actionTypeId": 2, "name": "change" },
|
||||
"user": "subid123456",
|
||||
"timestamp": "2024-07-03T15:01:00.000Z",
|
||||
"timestamp": "2024-07-03 15:01:00.000",
|
||||
"details": "Contract changed",
|
||||
"correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
|
||||
},
|
||||
@ -607,8 +558,8 @@ paths:
|
||||
"externalReference": "F2024-0001",
|
||||
"term": 1,
|
||||
"invoiceDate": "2024-07-02",
|
||||
"created": "2024-07-02T15:01:00.000Z",
|
||||
"updated": "2024-07-02T15:01:00.000Z",
|
||||
"created": "2024-07-02 15:01:00.000",
|
||||
"updated": "2024-07-02 15:01:00.000",
|
||||
"state": "invoice_created",
|
||||
"data": "{json}",
|
||||
"isCredit": false,
|
||||
@ -731,7 +682,7 @@ paths:
|
||||
"termDuration": "P0Y1M0D",
|
||||
"billingDay": 15,
|
||||
"highestInvoiceTerm": 1,
|
||||
"created": "2024-08-01T15:01:00.000Z",
|
||||
"created": "2024-08-01 15:01:00.000",
|
||||
"ovPayTokenId": 1337,
|
||||
"contractVersions":
|
||||
[
|
||||
@ -830,7 +781,7 @@ paths:
|
||||
"termDuration": "P0Y1M0D",
|
||||
"billingDay": 15,
|
||||
"highestInvoiceTerm": 1,
|
||||
"created": "2024-08-01T15:01:00.000Z",
|
||||
"created": "2024-08-01 15:01:00.000",
|
||||
"ovPayTokenId": 1337,
|
||||
"contractVersions":
|
||||
[
|
||||
|
||||
@ -111,6 +111,14 @@ paths:
|
||||
explode: false
|
||||
required: false
|
||||
description: Filter on most recent order status. 1 = concept, 2 = awaitingPayment, 3 = pendingPayment, 4 = paid, 5 = delivered, 6 = cancelled.
|
||||
- in: query
|
||||
name: issuedVoucherId
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "b0a9f3c9-9b92-4f8c-b78d-6129be7218a6"
|
||||
required: false
|
||||
description: Filter on applied issuedVoucherId for the order.
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
|
||||
@ -479,7 +479,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PostOrder"
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Create order with OVpas and PAD:
|
||||
summary: Create order with OVpas and PAD
|
||||
@ -494,11 +494,7 @@ paths:
|
||||
{
|
||||
"externalOrderLineId": null,
|
||||
"productId": 1,
|
||||
"vouchers":[
|
||||
{
|
||||
"voucherCode": "Voucher1234"
|
||||
}
|
||||
],
|
||||
"vouchers":[],
|
||||
"quantity": 1,
|
||||
"validFrom": "2024-03-22T09:00:00",
|
||||
"validUntil": null,
|
||||
@ -1868,7 +1864,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PostOrderLine"
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Add order line to concept order:
|
||||
summary: Add order line to concept order product with children
|
||||
@ -1877,11 +1873,7 @@ paths:
|
||||
{
|
||||
"externalOrderLineId": null,
|
||||
"productId": 2,
|
||||
"vouchers":[
|
||||
{
|
||||
"voucherCode": "HTM-787466"
|
||||
}
|
||||
],
|
||||
"vouchers":[],
|
||||
"quantity": 1,
|
||||
"validFrom": "2024-03-22T09:00:00",
|
||||
"validUntil": null,
|
||||
@ -1905,6 +1897,7 @@ paths:
|
||||
value:
|
||||
{
|
||||
"productId": 2,
|
||||
"vouchers":[],
|
||||
"quantity": 1,
|
||||
"createdOn": "2024-03-22T09:00:00",
|
||||
}
|
||||
@ -1969,64 +1962,7 @@ paths:
|
||||
"taxAmount": null,
|
||||
"amountExclTax": null,
|
||||
"amountInclTax": 121,
|
||||
"vouchers":[
|
||||
{
|
||||
"issuedVoucherId": "8e405272-470f-4ed6-8303-791ab40e72b5",
|
||||
"voucherCode": "HTM-787466",
|
||||
"fromInclusive": "2025-10-04T00:00:00.000",
|
||||
"untilInclusive": "2026-11-04T00:00:00.000",
|
||||
"voucherStatus":
|
||||
{ "voucherStatusId": 1, "name": "New" },
|
||||
"product":
|
||||
{
|
||||
"productId": 263,
|
||||
"productName": "HTM-80001",
|
||||
"productDescription": "10 euro korting op HTM maandkorting 20%",
|
||||
"productCategory":
|
||||
{
|
||||
"productCategoryId": 9,
|
||||
"isTravelProduct": false,
|
||||
"name": "Voucher",
|
||||
},
|
||||
"amountInclTax": -1000,
|
||||
"requiredProducts":
|
||||
[
|
||||
{
|
||||
"productId": 1,
|
||||
"productName": "HTM-30001",
|
||||
"productDescription": "HTM Maandkorting 20%",
|
||||
"_links":
|
||||
{
|
||||
"get_details":
|
||||
{
|
||||
"href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/1",
|
||||
"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"
|
||||
},
|
||||
],
|
||||
}
|
||||
],
|
||||
"vouchers":[],
|
||||
"quantity": 1,
|
||||
"orderLineTerms":
|
||||
[
|
||||
@ -2392,7 +2328,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PatchOrderLine"
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Update order line:
|
||||
summary: Update order line
|
||||
@ -2400,6 +2336,7 @@ paths:
|
||||
value:
|
||||
{
|
||||
"productId": 21,
|
||||
"vouchers":[],
|
||||
"quantity": 1,
|
||||
"validFrom": "2024-03-25T09:00:00",
|
||||
"validUntil": null,
|
||||
@ -2871,7 +2808,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PostVoucher"
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Add voucher to orderLine:
|
||||
summary: Add voucher to orderLine to receive voucher benefits for a specific product
|
||||
@ -3178,7 +3115,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PostVoucher"
|
||||
$ref: "#/components/schemas/unavailable"
|
||||
examples:
|
||||
Add voucher to concept order:
|
||||
summary: Add voucher to orderLine to receive voucher benefits for a whole order
|
||||
@ -6876,98 +6813,3 @@ components:
|
||||
ageToInclusive:
|
||||
type: integer
|
||||
example: 11
|
||||
PostOrder:
|
||||
type: object
|
||||
properties:
|
||||
externalOrderId:
|
||||
type: string
|
||||
description: |-
|
||||
The id used in an external sales system
|
||||
example: "MyOrder123"
|
||||
languageId:
|
||||
type: integer
|
||||
description: |-
|
||||
The id of the language for this order, all communications about the order will be in the given language
|
||||
example: 1
|
||||
externalDeviceId:
|
||||
type: string
|
||||
description: |-
|
||||
The mobile device in use when placing the order
|
||||
example: "ae3d9f69-945b-4290-a286-8c2dd5d7db8e"
|
||||
orderLines:
|
||||
type: array
|
||||
description: |-
|
||||
The orderLines with the chosen product and if known/required a voucher and customerToken
|
||||
items:
|
||||
$ref: "#/components/schemas/PostOrderLine"
|
||||
PostOrderLine:
|
||||
type: object
|
||||
required:
|
||||
- productId
|
||||
- quantity
|
||||
- createdOn
|
||||
properties:
|
||||
productId:
|
||||
type: integer
|
||||
description: |-
|
||||
The id of the chosen product
|
||||
example: 1
|
||||
quantity:
|
||||
type: integer
|
||||
description: |-
|
||||
Amount of the products to be delivered, in case of saldo quantity is used to define the amount of saldo to be charged in eurocents. If multiple GBO products are added, the same amount of customerTokens will be required.
|
||||
example: 1
|
||||
createdOn:
|
||||
type: string
|
||||
format: date-time
|
||||
description: |-
|
||||
Current datetime, moment client added orderLine to the order
|
||||
example: "2024-03-22T09:00:00"
|
||||
externalOrderLineId:
|
||||
type: string
|
||||
description: |-
|
||||
The orderLineId as known in an external sales system, used for reconcilliation
|
||||
example: "MyOrderLine123"
|
||||
validFrom:
|
||||
type: string
|
||||
format: date-time
|
||||
description: |-
|
||||
The moment the chosen product should be activated
|
||||
example: "2024-03-30T09:00:00"
|
||||
validUntil:
|
||||
type: string
|
||||
format: date-time
|
||||
description: |-
|
||||
Only required when a product does not have a fixed duration, otherwise it is calculated by the back end system
|
||||
example: null
|
||||
vouchers:
|
||||
type: array
|
||||
description: |-
|
||||
List of vouchers applicable for this orderLine
|
||||
items:
|
||||
$ref: "#/components/schemas/PostVoucher"
|
||||
PatchOrderLine:
|
||||
type: object
|
||||
properties:
|
||||
productId:
|
||||
type: integer
|
||||
example: 1
|
||||
quantity:
|
||||
type: integer
|
||||
example: 1
|
||||
validFrom:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2024-03-30T09:00:00"
|
||||
validUntil:
|
||||
type: string
|
||||
format: date-time
|
||||
example: null
|
||||
PostVoucher:
|
||||
type: object
|
||||
required:
|
||||
- voucherCode
|
||||
properties:
|
||||
voucherCode:
|
||||
type: string
|
||||
example: "Voucher1234"
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Service Engine APIs for HTM voucher suppliers
|
||||
description: Service Engine APIs for HTM voucher suppliers, this means all instances responsible for supplying vouchers. These are NOT the CRUD APIs to the data hub. These are ALSO NOT the APIs for sales touchpoints.
|
||||
description: Service Engine APIs for HTM voucher 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
|
||||
@ -24,6 +24,15 @@ paths:
|
||||
|
||||
When a requiredProduct is configured, all attributes of the requiredProduct are also prerequisites for redeeming the voucher; thus they do not need to also be configured for the voucher definition. The requiredProduct itself is the single source of truth for this; and voucher definitions do not need to be updated if the requirements of the requiredProduct change. For example, if the requiredProduct requires an OVpay token, an OVpay token is automatically required to redeem issued vouchers.
|
||||
parameters:
|
||||
- name: touchpointId
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Filter the voucher definitions on a specific touchpointId. This means that only voucher definitions with active selling periods for the specified touchpoint are returned.
|
||||
This query parameter is only intended for administrative purposes, since the touchpoint 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 touchpoints within the same retailer, for example to retrieve voucher definitions for a specific sales touchpoint that is different from the calling touchpoint.
|
||||
schema:
|
||||
type: integer
|
||||
example: 12
|
||||
- name: productId
|
||||
in: query
|
||||
required: false
|
||||
@ -197,15 +206,18 @@ paths:
|
||||
/issuedvouchers:
|
||||
get:
|
||||
summary: Get a list of issued vouchers that were issued for a specific touch point
|
||||
description: |-
|
||||
Retrieve all issued vouchers that match the given query parameters. \
|
||||
At least on of the following query parameters should be provided:
|
||||
- `issuedVoucherId` (internal and globally unique ID);
|
||||
- `voucherCode` (code that the customer uses for redeeming the voucher, can be reissued as long as only one instance is active at the same time);
|
||||
- `productId` (the productId of the voucher definition).
|
||||
|
||||
When a voucher code has been issued multiple times, all issuedvouchers with the same voucher code will be returned, together with their statuses.
|
||||
description:
|
||||
Retrieve all issued vouchers for a specific touchpoint. This means that only vouchers that were issued by a touchpoint within the same retailer as the calling touchpoint are returned.
|
||||
parameters:
|
||||
- name: touchpointId
|
||||
in: query
|
||||
required: false
|
||||
description: |-
|
||||
Filter the issued vouchers on a specific touchpointId. This means that only vouchers that were issued by the specified touchpoint are returned.
|
||||
This query parameter is only intended for administrative purposes, since the touchpoint 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 touchpoints within the same retailer, for example to retrieve issued vouchers for a specific sales touchpoint that is different from the calling touchpoint.
|
||||
schema:
|
||||
type: integer
|
||||
example: 12
|
||||
- name: issuedVoucherId
|
||||
in: query
|
||||
required: false
|
||||
@ -404,22 +416,6 @@ paths:
|
||||
}
|
||||
]
|
||||
}
|
||||
"400":
|
||||
description: Bad request
|
||||
content:
|
||||
application/problem+json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/rfc9457"
|
||||
examples:
|
||||
Missing required query parameters:
|
||||
summary: Missing required query parameters
|
||||
value:
|
||||
{
|
||||
"type": "https://example.com/probs/bad-request",
|
||||
"title": "Missing required query parameters",
|
||||
"detail": "At least one of the following query parameters should be provided: issuedVoucherId, voucherCode, or productId.",
|
||||
"instance": "/issuedvouchers"
|
||||
}
|
||||
"403":
|
||||
description: Forbidden
|
||||
content:
|
||||
@ -470,20 +466,10 @@ paths:
|
||||
}
|
||||
post:
|
||||
summary: Issue a voucher for a specific voucher definition
|
||||
description: |-
|
||||
Issue a voucher for a specific voucher definition. Vouchers can only be issued on a one-by-one basis, so that it is always clear what voucher code has been issued for specific voucher claims (which by itself may not uniquely identify the voucher; however the voucher code is guaranteed to be unique).\
|
||||
The voucher can only be issued if the calling touchpoint (recognized by the access token) has an active selling period for the voucher definition (recognized by the productId).
|
||||
|
||||
When providing a voucher code, the supplier is allowed to re-use a voucher code that has already been issued, but only if the previously issued voucher is not active anymore.\
|
||||
This means that a voucher code can only be re-used once the previous instance has a `voucherStatus` of "revoked" or "expired".\
|
||||
Redeemed is NOT a valid end-state, as this voucher might still refer to an active travel product (which can be revoked by revoking the voucher).
|
||||
|
||||
The `fromInclusive` and `untilInclusive` fields specify the date-time range in which the voucher can be redeemed by the customer.\
|
||||
This has nothing to do with the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).
|
||||
|
||||
description: |
|
||||
Issue a voucher for a specific voucher definition. Vouchers can only be issued on a one-by-one basis, so that it is always clear what voucher code has been issued for specific voucher claims (which by itself my not uniquely identify the voucher; however the voucher code is guaranteed to be unique). The voucher can only be issued if the calling touchpoint (recognized by the access token) has an active selling period for the voucher definition (recognized by the productId).\
|
||||
The \"fromInclusive\" and \"untilInclusive\" fields specify the date-time range in which the voucher can be redeemed by the customer. This has nothing to do with the allowed start date of a requiredProduct (for this, the existing order flow logic is applied).\
|
||||
If the voucher definition contains mandatoryCustomerDataItems, a value (to be checked against customer input when redeeming the voucher) has to be provided for each of these items.
|
||||
|
||||
A newly issued voucher will always receive the status "new". Vouchers can only be redeemed after they have been explicitly set to the status "issued" (via `PATCH /issuedvouchers/{issuedVoucherId}`), for example when the customer receives the actual voucher code.
|
||||
tags:
|
||||
- Vouchers
|
||||
requestBody:
|
||||
@ -495,9 +481,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 supplier already has its own (internal or external) source for voucher codes.\
|
||||
The supplied voucher code must be unique (or a previous instance must be revoked/expired, see main endpoint description).
|
||||
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.
|
||||
value:
|
||||
{
|
||||
"voucherCode": "HTM-A7J-128-PYT",
|
||||
@ -514,21 +498,12 @@ paths:
|
||||
}
|
||||
Issue a voucher and receive a voucher code (generated by ABT backend) in response:
|
||||
summary: Issue a voucher and receive a voucher code (generated by ABT backend) in response
|
||||
description: |-
|
||||
If the supplier is not able to generate its own unique voucher codes, it can issue a voucher without supplying any voucher code.\
|
||||
The ABT backend will then generate a unique voucher code and return it in response.
|
||||
description: If the supplier is not able to generate its own unique voucher codes, it can issue a voucher without supplying any voucher code - the ABT backend will then receive a unique voucher code and return it in response.
|
||||
value:
|
||||
{
|
||||
"fromInclusive": "2026-01-01T00:00:00.000+00:00",
|
||||
"untilInclusive": "2030-12-31T23:59:59.000+00:00",
|
||||
"productId": 264,
|
||||
"voucherClaims":
|
||||
[
|
||||
{
|
||||
"mandatoryCustomerDataItemId": 8,
|
||||
"value": "1980-06-31",
|
||||
}
|
||||
],
|
||||
"productId": 264
|
||||
}
|
||||
responses:
|
||||
"201":
|
||||
@ -546,7 +521,7 @@ paths:
|
||||
"voucherCode": "HTM-A7J-128-PYT",
|
||||
"fromInclusive": "2024-10-04T00:00:00.000",
|
||||
"untilInclusive": "2024-11-04T00:00:00.000",
|
||||
"voucherStatus": { "voucherStatusId": 1, "name": "new" },
|
||||
"voucherStatus": { "voucherStatusId": 2, "name": "issued" },
|
||||
"product":
|
||||
{
|
||||
"productId": 263,
|
||||
@ -598,12 +573,12 @@ paths:
|
||||
$ref: "#/components/schemas/rfc9457"
|
||||
examples:
|
||||
Voucher code already in use:
|
||||
summary: Another active voucher instance already exists for this voucher code
|
||||
summary: Voucher code already in use
|
||||
value:
|
||||
{
|
||||
"type": "https://example.com/probs/bad-request",
|
||||
"title": "Invalid voucher code",
|
||||
"detail": "Another active voucher instance already exists for this voucher code.",
|
||||
"detail": "This voucher code is already in use.",
|
||||
"instance": "/issuedvouchers"
|
||||
}
|
||||
Missing mandatory voucher claims:
|
||||
@ -639,9 +614,6 @@ paths:
|
||||
summary: Update the status of an issued voucher
|
||||
description: |-
|
||||
Update the status of an issued voucher. Not every state change is allowed; an error will be returned if an invalid state change is attempted.\
|
||||
If a redeemed voucher is revoked using this endpoint, it may also impact any active travel products that have been acquired using this voucher.\
|
||||
This depends on specific business rules that are agreed upon with HTM.
|
||||
|
||||
Possible voucher statuses are:
|
||||
- 1 = new
|
||||
- 2 = issued
|
||||
@ -658,16 +630,8 @@ paths:
|
||||
schema:
|
||||
$ref: "#/components/schemas/supplierTouchpointUpdateIssuedVoucherRequest"
|
||||
examples:
|
||||
Mark a voucher as issued:
|
||||
summary: Mark a voucher as issued
|
||||
description: Mark a voucher as issued. Only vouchers with a status of "issued" can actually be redeemed.
|
||||
value:
|
||||
{
|
||||
"voucherStatusId": 2
|
||||
}
|
||||
Mark a voucher as revoked:
|
||||
summary: Mark a voucher as revoked
|
||||
description: Mark a voucher as revoked. This may also impact any active travel products that have been acquired using this voucher. This depends on specific business rules that are agreed upon with HTM.
|
||||
value:
|
||||
{
|
||||
"voucherStatusId": 4
|
||||
|
||||
Loading…
Reference in New Issue
Block a user