develop #38

Merged
bboterm merged 451 commits from develop into main 2025-11-19 14:28:14 +00:00
Showing only changes of commit 8af1bed739 - Show all commits

View File

@ -0,0 +1,649 @@
openapi: 3.0.1
info:
title: Service Engine APIs for Customers
description: >-
Service Engine APIs for HTM Customers. These are NOT the CRUD APIs to access raw data in the database.
To be used by touchpoints to get information about HTM customers.
version: 'x.x'
servers:
- url: https://api.integratielaag.nl/abt/serviceengine/customers/x.x
tags:
- name: ServiceEngine Customers
description: >-
Service Engine APIs for HTM Customers. These are NOT the CRUD APIs to access raw data in the database.
To be used by touchpoints to get information about HTM customers.
paths:
/customers:
get:
tags:
- ServiceEngine Customers
summary: Get a single customer profile based on search parameters
description: Get a single customer profile based on search parameters. Only returns a profile if a single result matches the parameters; when multiple results are found, additional seach parameters are required to disambiguate.
parameters:
- name: customerProfileId
in: query
schema:
type: integer
example: 1
- name: customerNumber
in: query
schema:
type: integer
example: 1000001
- name: customerStatusId
in: query
schema:
type: integer
example: 1
- name: debtorNumber
in: query
schema:
type: integer
example: 100001
- name: debtorStatusId
in: query
schema:
type: integer
example: 1
- name: birthname
in: query
schema:
type: string
example: John
- name: surname
in: query
schema:
type: string
example: Doe
- name: emailAddress
in: query
schema:
type: string
format: email
example: john.doe@mymailprovider.com
- name: dateOfBirth
in: query
schema:
type: string
format: date
example: "2000-01-01"
- name: addressStreet
in: query
schema:
type: string
example: Sesamestreet
- name: addressHouseNumber
in: query
schema:
type: integer
example: 1
- name: addressHouseNumberSuffix
in: query
schema:
type: string
example: A
- name: addressPostalCode
in: query
schema:
type: string
example: 1234 AB
- name: addressCity
in: query
schema:
type: string
example: The Hague
- name: addressCountry
in: query
schema:
type: string
example: The Netherlands
- name: phoneNumber
in: query
schema:
type: string
example: "0123456789"
- name: ovChipcardNumber
in: query
schema:
type: integer
example: 0123456789
- name: ovChipcardAlias
in: query
schema:
type: string
example: My ovchipcard
- name: ovPayTokenNumber
in: query
schema:
type: integer
example: 0123456789
- name: ovPayTokenAlias
in: query
schema:
type: string
example: My Ov Pay Token
- name: ovPayTokenXTat
in: query
schema:
type: string
example: 180d04e0-a721-447e-a1d9-b416937b43bc
- name: ovPayTokenXBot
in: query
schema:
type: string
example: e1307c73-676a-4d07-967b-6141276f7c7c
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersResponse'
'404':
description: No customer found
content:
application/json:
example:
{
"type": "https://api.integratielaag.nl/abt/serviceengine/x.x/customers",
"apiErrorCode": "400.1",
"title": "Niet gevonden",
"detail": "Klant niet gevonden",
"instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
"errors": [
{
"subApiErrorCode": "0017"
}
]
}
'409':
description: Multiple customers found
content:
application/json:
example:
{
"type": "https://api.integratielaag.nl/abt/serviceengine/x.x/customers",
"apiErrorCode": "409.1",
"title": "Meer dan 1 klantprofiel gevonden",
"detail": "Meer dan 1 klantprofiel gevonden. Verfijn je zoekcriteria.",
"instance": "555d00b5-bc3f-4591-949b-479e76d49ea7"
}
/customers/tokens:
get:
tags:
- ServiceEngine Customers
summary: Get a list of all OvPayTokens for a certain customer
description: Get a list of all OvPayTokens for a certain customer.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OvPayTokensResponse'
/customers/tokens/{ovPayTokenId}/productinstances:
get:
tags:
- ServiceEngine Customers
summary: Get a list of all HTM products instantiated on the given OvPayToken
description: |-
Get a list of all HTM products instantiated on the given OvPayToken.
Only HTM products are returned; GBO does not allow HTM to get information on non-HTM product-instances.
Where relevant, operations to be performed are returned as HATEOAS links per product-instance.
parameters:
- name: ovPayTokenId
in: path
required: true
style: simple
description: Id of the OvPayToken to get product-instances for.
schema:
type: integer
example: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OvPayTokenProductInstancesResponse'
examples:
getEmptyProductInstances:
summary: No product-instances found on token
value:
productInstances: []
getSingleProductInstance:
summary: One non-renewable product-instance
value:
{
"productInstances": [
{
"productId": 1,
"name": "HTM 90% Korting",
"status": "Active",
"isRenewable": true,
"productCategory": {
"productCategoryId": 1,
"name": "Kortingsabonnement"
},
"fromInclusive": "2024-11-25T13:25:00+01:00",
"untilInclusive": "2024-12-25T03:59:59+01:00",
"orderId": "501B17EF-36C4-4039-B92C-6517969B464E",
"orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
"contractId": "56B17EF-C436-9043-B76C-481797WEB464F",
"_links": {
"self": {
"href": "https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1/productinstances/1",
"method": "GET"
},
"get_order": {
"href": "https://api.integratielaag.nl/abt/serviceengine/x.x/orders/501B17EF-36C4-4039-B92C-6517969B464E",
"method": "GET"
},
"get_contract": {
"href": "https://api.integratielaag.nl/abt/serviceengine/x.x/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F",
"method": "GET"
}
}
}
]
}
components:
schemas:
CustomersResponse:
type: object
properties:
customerProfileId:
type: integer
example: 1
customerNumber:
type: integer
example: 1000001
customerStatus:
type: object
properties:
customerStatusId:
type: integer
example: 1
name:
type: string
example: Active
debtorNumber:
type: string
example: DB100001
debtorStatus:
type: object
properties:
debtorStatusId:
type: integer
example: 1
name:
type: string
example: Active
person:
type: object
properties:
prefix:
type: string
example: Mr
birthname:
type: string
example: John
surname:
type: string
example: Doe
suffix:
type: string
example: Jr.
dateOfBirth:
type: string
format: date
example: '2023-02-01'
emailAddress:
type: string
format: email
example: 4j2dD@example.com
addresses:
type: array
items:
type: object
properties:
addressId:
type: integer
example: 1
isPreferred:
type: boolean
example: true
addressType:
type: object
properties:
addressTypeId:
type: integer
example: 1
name:
type: string
example: Home
street:
type: string
example: Appelstraat
houseNumber:
type: integer
example: 1
houseNumberSuffix:
type: string
example: BS
postalCode:
type: string
example: 1234AB
city:
type: string
example: Den Haag
country:
type: string
example: Nederland
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/addresses/1
method:
type: string
example: GET
delete_address:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/addresses/1
method:
type: string
example: DELETE
phones:
type: array
items:
type: object
properties:
phoneId:
type: integer
example: 1
isPreferred:
type: boolean
example: true
phoneType:
type: object
properties:
phoneTypeId:
type: integer
example: 1
name:
type: string
example: Home
number:
type: string
example: "0123456789"
countryCode:
type: string
example: "0031"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/phones/1
method:
type: string
example: GET
delete_phone:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/phones/1
method:
type: string
example: DELETE
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers
method:
type: string
example: GET
create_customer_status:
type: object
description: ONLY ALLOWED FOR SMP - Create a new customer status
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/statuses
method:
type: string
example: POST
partial_edit:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers
method:
type: string
example: PATCH
get_tokens:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens
method:
type: string
example: GET
create_token:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens
method:
type: string
example: POST
OvPayTokensResponse:
type: object
required:
- ovPayTokens
properties:
ovPayTokens:
type: array
items:
type: object
properties:
ovPayTokenId:
type: integer
example: 1
tokenType:
type: object
properties:
tokenTypeId:
type: integer
example: 1
name:
type: string
example: EMV
alias:
type: string
example: MyToken
tokenStatus:
type: object
properties:
tokenStatusId:
type: integer
example: 1
name:
type: string
example: Active
expirationDate:
type: string
format: date
example: '2023-02-01'
replacedByTokenId:
type: integer
example: 1
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1
method:
type: string
example: GET
partial_edit:
type: object
description: External touchpoints are only allowed to change alias - SMP can also change tokenStatus
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1
method:
type: string
example: PATCH
replace_token:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1/replace
method:
type: string
example: POST
delete_token:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1
method:
type: string
example: DELETE
get_productinstances:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1/productinstances
method:
type: string
example: GET
get_trips:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1/trips
method:
type: string
example: GET
OvPayTokenProductInstancesResponse:
type: object
properties:
productInstances:
type: array
items:
type: object
properties:
productId:
type: integer
example: 1
name:
type: string
example: HTM 90% Korting
status:
type: string
enum: [ "Active", "Ended", "Refunded" ]
example: Active
isRenewable:
type: boolean
example: true
productCategory:
type: object
description: The category of the originating HTM product definition
properties:
productCategoryId:
type: integer
example: 1
name:
type: string
example: Kortingsabonnement
fromInclusive:
type: string
format: date-time-offset
example: "2024-11-25T13:25:00+01:00"
untilInclusive:
type: string
format: date-time-offset
description: >-
If not present, this product-instance represents a subscription/contract without a real end date. If present, it can be either the natural end date or the refund timestamp.
example: "2024-12-25T03:59:59+01:00"
orderId:
type: string
format: uuid
example: 501B17EF-36C4-4039-B92C-6517969B464E
orderLineId:
type: string
format: uuid
example: 38B17EF-36C4-4039-B92C-4817969B464E
contractId:
type: string
format: uuid
example: 56B17EF-C436-9043-B76C-481797WEB464F
description: Only present for subscriptions/contracts
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/tokens/1/productinstances
method:
type: string
example: GET
get_order:
type: object
properties:
href:
type: string
description: Always present for any HTM product-instance
example: https://api.integratielaag.nl/abt/serviceengine/x.x/orders/501B17EF-36C4-4039-B92C-6517969B464E
method:
type: string
example: GET
get_contract:
type: object
properties:
href:
type: string
description: Only present for subscriptions/contracts
example: https://api.integratielaag.nl/abt/serviceengine/x.x/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F
method:
type: string
example: GET