openapi: 3.0.1
info:
  title: Personal Account Data (PAD) APIs for TouchPoint
  description: >-
    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
    description: API ABT GBO APIM
tags:
  - name: Personal Data APIs for TouchPoint
    description: Personal Data APIs for TouchPoint, no Service Engine in between!
paths:
  /personal-data/{xtat}:
    post:
      tags:
        - Personal Data APIs for TouchPoint
      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 TouchPoint
      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 TouchPoint
      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 TouchPoint
      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'
components:
  schemas:
    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