482 lines
18 KiB
YAML
482 lines
18 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Personal Account Data (PAD) APIs for touchpoints and Service Engine
|
|
description: |-
|
|
APIs for touchpoints and Service Engine to manage Personal Account Data (PAD) on OVpay tokens (xTATs).\
|
|
These APIs connect directly to the PADP APIs in GBO APIM and are implemented in Logic Apps
|
|
in the Integration Layer.
|
|
version: '1.0'
|
|
servers:
|
|
- url: https://api.integratielaag.nl/abt/touchpoint/1.0
|
|
tags:
|
|
- name: Personal Data APIs for touchpoints
|
|
description: Personal Data APIs for touchpoints, no Service Engine in between!
|
|
- name: Personal Data APIs for Service Engine
|
|
description: Personal Data APIs for Service Engine, not to be exposed to touchpoints!
|
|
paths:
|
|
/personal-data/{xtat}:
|
|
post:
|
|
tags:
|
|
- Personal Data APIs for touchpoints
|
|
summary: Add the supplied Personal Data to the given xTAT (that should not contain any Personal Data yet).
|
|
description: |-
|
|
- The given xTAT should not contain any Personal Data yet (the PATCH endpoint should be used in that case) - if the given xTAT already contains Personal Data, an error is thrown;
|
|
- The given e-mail address will be used for future OTP challenges to manage the Personal Data in the future - this e-mail adress should therefore be validated;
|
|
- If the e-mail address is not yet validated by other means (e.g. the e-mail address is used for login, or is entered twice to prevent typos), an OTP challenge for the e-mail address should be triggered and supplied to this endpoint;
|
|
- xTAT and e-mail address are always required, for the Personal Data it is allowed to supply any subset, or all three data attributes;
|
|
- Each of the three data attributes is validated - for the requirements per attribute, see the descriptions in the request details below;
|
|
- If any attribute fails validation, none of the attributes will be added to the xTAT.
|
|
operationId: CreatePersonalData
|
|
parameters:
|
|
- name: xtat
|
|
in: path
|
|
required: true
|
|
example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d'
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- email
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: Email address to be used for OTP challenges to prove ownership and manage the Personal Data in the future
|
|
example: 8Z9dG@example.com
|
|
otp:
|
|
type: string
|
|
pattern: ^[0-9]{6}$
|
|
description: OTP is optional, should be supplied if the e-mail address is not yet validated by other means (e.g. the e-mail address is used for login, or is entered twice to prevent typo's)
|
|
example: "053395"
|
|
name:
|
|
type: string
|
|
description: Should consist of at least two words (first name and last name)
|
|
example: John Doe
|
|
birthDate:
|
|
type: string
|
|
format: date
|
|
description: Should be a date between 1900-01-01 and today, in the format `YYYY-MM-DD`
|
|
example: 2000-01-01
|
|
photo:
|
|
type: string
|
|
description: Should be a JPG image, with a filesize of max. 512KB and resolution between 520x520 and 720x720 pixels
|
|
format: binary
|
|
encoding:
|
|
photo:
|
|
contentType: image/jpeg
|
|
responses:
|
|
'201':
|
|
description: Created
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
get:
|
|
tags:
|
|
- Personal Data APIs for touchpoints
|
|
summary: Retrieve the decrypted Personal Data for the given xTAT, using the OTP for verification of ownership.
|
|
description: OTP challenge is required to retrieve the Personal Data.
|
|
operationId: GetDecryptedPersonalData
|
|
parameters:
|
|
- name: xtat
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d'
|
|
- name: otp
|
|
in: query
|
|
required: true
|
|
description: OTP challenge code that the token owner received in their e-mail inbox. OTP is always required for managing existing Personal Data.
|
|
schema:
|
|
type: string
|
|
pattern: ^[0-9]{6}$
|
|
example: "053395"
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DecryptedPersonalData'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
patch:
|
|
tags:
|
|
- Personal Data APIs for touchpoints
|
|
summary: Update the supplied personal data for the given xTAT, using the OTP for verification of ownership.
|
|
description: This is a PATCH call, so only the personal data that the user desires to change need to be supplied. Integration layer supplements with any other existing personal data to be able to call GBO (PUT call).
|
|
operationId: UpdatePersonalData
|
|
parameters:
|
|
- name: xtat
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d'
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- otp
|
|
properties:
|
|
otp:
|
|
type: string
|
|
pattern: ^[0-9]{6}$
|
|
description: OTP challenge code that the token owner received in their e-mail inbox. OTP is always required for managing existing Personal Data.
|
|
example: "053395"
|
|
name:
|
|
type: string
|
|
description: Should consist of at least two words (first name and last name)
|
|
example: John Doe
|
|
birthDate:
|
|
type: string
|
|
format: date
|
|
description: Should be a date between 1900-01-01 and today, in the format `YYYY-MM-DD`
|
|
example: 2000-01-01
|
|
photo:
|
|
type: string
|
|
description: Should be a JPG image, with a filesize of max. 512KB and resolution between 520x520 and 720x720 pixels
|
|
format: binary
|
|
encoding:
|
|
photo:
|
|
contentType: image/jpeg
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
/personal-data/generate-otp:
|
|
get:
|
|
tags:
|
|
- Personal Data APIs for touchpoints
|
|
summary: Trigger OTP email for the given xTAT or e-mail address, to prove ownership
|
|
operationId: GenerateOtp
|
|
description: |-
|
|
Generate an OTP challenge e-mail to prove ownership of the given e-mail address or xTAT.\
|
|
Only one type of parameter can be supplied, either xtat or email. When both are supplied, an error is thrown.
|
|
parameters:
|
|
- name: xtat
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d'
|
|
- name: email
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: email
|
|
example: 'sV4yj@example.com'
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OtpResponse'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
/personal-data/{xtat}/administrative-data:
|
|
get:
|
|
tags:
|
|
- Personal Data APIs for Service Engine
|
|
summary: API 1211 - Get Administrative Data
|
|
description: Integration Layer utilizes PAD management V2 in GBO APIM (`/pad-management/v2/..`)
|
|
operationId: GetAdministrativeData
|
|
parameters:
|
|
- name: xtat
|
|
description: xTAT to get administrative data for
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d'
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AdministrativeData"
|
|
examples:
|
|
Valid and complete PAD:
|
|
summary: Valid and complete PAD
|
|
value:
|
|
name:
|
|
inaccuracyFlag: false
|
|
inaccuracyFlagReason: null
|
|
inaccuracyFlagCounter: 0
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 1
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
photo:
|
|
inaccuracyFlag: false
|
|
inaccuracyFlagReason: null
|
|
inaccuracyFlagCounter: 0
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 5
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
birthdate:
|
|
inaccuracyFlag: false
|
|
inaccuracyFlagReason: null
|
|
inaccuracyFlagCounter: 0
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 3
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
Partially filled PAD (no photo):
|
|
summary: Partially filled PAD (no photo)
|
|
value:
|
|
name:
|
|
inaccuracyFlag: false
|
|
inaccuracyFlagReason: null
|
|
inaccuracyFlagCounter: 0
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 1
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
photo: null
|
|
birthdate:
|
|
inaccuracyFlag: false
|
|
inaccuracyFlagReason: null
|
|
inaccuracyFlagCounter: 0
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 3
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
Flagged PAD:
|
|
summary: Flagged PAD
|
|
value:
|
|
name:
|
|
inaccuracyFlag: true
|
|
inaccuracyFlagReason: "Invalid name"
|
|
inaccuracyFlagCounter: 1
|
|
changeCounter: 1
|
|
maxUpdatesVerificationCount: 1
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
photo:
|
|
inaccuracyFlag: true
|
|
inaccuracyFlagReason: "Invalid photo"
|
|
inaccuracyFlagCounter: 1
|
|
changeCounter: 0
|
|
maxUpdatesVerificationCount: 5
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
birthdate:
|
|
inaccuracyFlag: true
|
|
inaccuracyFlagReason: "Invalid birthdate"
|
|
inaccuracyFlagCounter: 1
|
|
changeCounter: 2
|
|
maxUpdatesVerificationCount: 3
|
|
lastChangeDate: "2025-03-26T10:18:42.947"
|
|
isValidated: false
|
|
"400":
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
Invalid UUID:
|
|
summary: Invalid UUID
|
|
value:
|
|
errors:
|
|
code: "0x03000103"
|
|
data: [
|
|
"geen-uuid"
|
|
]
|
|
message: "The provided scTat is not a valid UUID"
|
|
exceptionClassName: "PadpConstraintViolationException"
|
|
exceptionStackTrace: "not available because debug mode is turned off"
|
|
"404":
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
No PAD found for xTAT:
|
|
summary: No PAD found for xTAT
|
|
value:
|
|
errors:
|
|
code: "0x03000105"
|
|
data: []
|
|
message: "Transit account not found"
|
|
exceptionClassName: "PadpEntityNotFoundException"
|
|
exceptionStackTrace: "not available because debug mode is turned off"
|
|
"500":
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
Unknown xTAT:
|
|
summary: Unknown xTAT
|
|
value:
|
|
errors:
|
|
code: "0x00000001"
|
|
data: null
|
|
message: "400 : \"{\"errorMessage\":{\"referenceId\":\"076f0de4-df33-42a3-add0-def971ab6679\",\"message\":\"Unknown external transit account token.\"},\"businessExceptions\":[{\"code\":\"TM0207\",\"message\":\"Unknown external transit account token.\"}]}\""
|
|
exceptionClassName: "BadRequest"
|
|
exceptionStackTrace: "not available because debug mode is turned off"
|
|
components:
|
|
schemas:
|
|
AdministrativeData:
|
|
type: object
|
|
properties:
|
|
name:
|
|
$ref: '#/components/schemas/AdministrativeDataElement'
|
|
photo:
|
|
$ref: '#/components/schemas/AdministrativeDataElement'
|
|
birthdate:
|
|
$ref: '#/components/schemas/AdministrativeDataElement'
|
|
additionalProperties: false
|
|
AdministrativeDataElement:
|
|
type: object
|
|
properties:
|
|
inaccuracyFlag:
|
|
type: boolean
|
|
inaccuracyFlagReason:
|
|
type: string
|
|
nullable: true
|
|
inaccuracyFlagCounter:
|
|
type: integer
|
|
format: int32
|
|
changeCounter:
|
|
type: integer
|
|
format: int32
|
|
maxUpdatesVerificationCount:
|
|
type: integer
|
|
format: int32
|
|
lastChangeDate:
|
|
type: string
|
|
format: date-time
|
|
isValidated:
|
|
type: boolean
|
|
additionalProperties: false
|
|
DecryptedData:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
nullable: true
|
|
birthdate:
|
|
type: string
|
|
nullable: true
|
|
photo:
|
|
type: string
|
|
description: Base64 encoded photo
|
|
format: byte
|
|
nullable: true
|
|
additionalProperties: false
|
|
DecryptedPersonalData:
|
|
type: object
|
|
properties:
|
|
decryptedData:
|
|
$ref: '#/components/schemas/DecryptedData'
|
|
additionalProperties: false
|
|
Error:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
nullable: true
|
|
data:
|
|
type: array
|
|
items:
|
|
type: string
|
|
nullable: true
|
|
message:
|
|
type: string
|
|
nullable: true
|
|
additionalProperties: false
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Error'
|
|
nullable: true
|
|
exceptionClassName:
|
|
type: string
|
|
nullable: true
|
|
exceptionStackTrace:
|
|
type: string
|
|
nullable: true
|
|
additionalProperties: false
|
|
Metadata:
|
|
type: object
|
|
properties:
|
|
encryptedEphemeralKey:
|
|
type: string
|
|
nullable: true
|
|
additionalProperties: false
|
|
OtpResponse:
|
|
type: object
|
|
properties:
|
|
maskedEmailAddress:
|
|
type: string
|
|
nullable: true
|
|
additionalProperties: false |