diff --git a/src/openapi/customers/SE-customers.yaml b/src/openapi/customers/SE-customers.yaml new file mode 100644 index 0000000..7238481 --- /dev/null +++ b/src/openapi/customers/SE-customers.yaml @@ -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 + + + + +