swagger: '2.0'
info:
  version: 1.1.0
  title: IO Functions CGN
  contact:
    name: IO team
    url: https://forum.italia.it/c/progetto-io
  x-logo:
    url: https://io.italia.it/assets/img/io-logo-blue.svg
  description: |
    Documentation of the IO Function API here.
host: api.cd.italia.it
basePath: /api/v1/cgn
schemes:
  - https
security:
  - ApiKey: []
paths:
  /status/{fiscalcode}:
    get:
      summary: Get CGN details Status
      operationId: getCgnStatus
      description: |
        Get the CGN status details by the provided fiscal code. 
        In case of success the response could be one of:
          - CardPending
          - CardPendingDelete
          - CardActivated
          - CardRevoked
          - CardExpired
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '200':
          description: CGN details.
          schema:
            $ref: '#/definitions/Card'
        '401':
          description: Wrong or missing function key.
        '404':
          description: No CGN found.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
    post:
      operationId: upsertCgnStatus
      summary: |
        Upsert a CGN status
      description: |
        Upsert the status of a CGN. There are 2 accepted actions:
        -  REVOKE
      parameters:
        - $ref: '#/parameters/FiscalCode'
        - in: body
          name: body
          schema:
            $ref: '#/definitions/CgnStatusUpsertRequest'
      responses:
        '201':
          description: Request created.
          schema:
            $ref: '#/definitions/InstanceId'
          headers:
            Location:
              type: string
              description: >-
                Location (URL) of created request resource.

                A GET request to this URL returns the request status and
                details.
        '202':
          description: Processing request.
          schema:
            $ref: '#/definitions/InstanceId'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '404':
          description: No CGN found.
        '409':
          description: >
            Cannot revoke the user's cgn because another updateCgn request was
            found

            for this user
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
  /eyca/status/{fiscalcode}:
    get:
      summary: Get EYCA details Status
      operationId: getEycaStatus
      description: |
        Get the EYCA status details by the provided fiscal code. 
        In case of success the response could be one of:
          - CardPending
          - EycaCardPendingDelete
          - EycaCardActivated
          - EycaCardRevoked
          - EycaCardExpired
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '200':
          description: EYCA details.
          schema:
            $ref: '#/definitions/EycaCard'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '404':
          description: No EYCA found.
        '409':
          description: EYCA Card is missing while citizen is eligible to obtain it.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
  /{fiscalcode}/eyca/activation:
    post:
      operationId: startEycaActivation
      summary: |
        Start a new Eyca activation process
      description: |
        Start an EYCA activation process related to a CGN
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '201':
          description: Request created.
          schema:
            $ref: '#/definitions/InstanceId'
          headers:
            Location:
              type: string
              description: >-
                Location (URL) of created request resource.

                A GET request to this URL returns the request status and
                details.
        '202':
          description: Processing request.
          schema:
            $ref: '#/definitions/InstanceId'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '409':
          description: |
            Cannot start a new activation because EYCA card is already activated
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
    get:
      operationId: getEycaActivation
      summary: |
        Get EYCA activation process' status
      description: |
        Get informations about an EYCA activation process
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '200':
          description: Cgn activation details.
          schema:
            $ref: '#/definitions/EycaActivationDetail'
        '401':
          description: Wrong or missing function key.
        '404':
          description: No CGN activation process found.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
  /{fiscalcode}/activation:
    post:
      operationId: startCgnActivation
      summary: |
        Start a new CGN activation process
      description: |
        Start an activation process for a CGN
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '201':
          description: Request created.
          schema:
            $ref: '#/definitions/InstanceId'
          headers:
            Location:
              type: string
              description: >-
                Location (URL) of created request resource.

                A GET request to this URL returns the request status and
                details.
        '202':
          description: Processing request.
          schema:
            $ref: '#/definitions/InstanceId'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '409':
          description: >
            Cannot start a new activation because the user's cgn is already
            activated
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
    get:
      operationId: getCgnActivation
      summary: |
        Get CGN activation process' status
      description: |
        Get informations about a CGN activation process
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '200':
          description: Cgn activation details.
          schema:
            $ref: '#/definitions/CgnActivationDetail'
        '401':
          description: Wrong or missing function key.
        '404':
          description: No CGN activation process found.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
  /{fiscalcode}/delete:
    post:
      operationId: startCgnUnsubscription
      summary: |
        Start a CGN unsubscribe process
      description: |
        Start an unsubscription process for a CGN
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '201':
          description: Request created.
          schema:
            $ref: '#/definitions/InstanceId'
          headers:
            Location:
              type: string
              description: >-
                Location (URL) of created request resource.

                A GET request to this URL returns the request status and
                details.
        '202':
          description: Processing request.
          schema:
            $ref: '#/definitions/InstanceId'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '409':
          description: |
            Cannot start an unsubscribe process.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
  /otp/{fiscalcode}:
    post:
      operationId: generateOtp
      summary: |
        Generate a new Otp related to a CGN
      description: |
        Generate a new Otp used to discount an online purchase
        through a valid CGN
      parameters:
        - $ref: '#/parameters/FiscalCode'
      responses:
        '200':
          description: Otp generated.
          schema:
            $ref: '#/definitions/Otp'
        '401':
          description: Wrong or missing function key.
        '403':
          description: Forbidden.
        '500':
          description: Service unavailable.
          schema:
            $ref: '#/definitions/ProblemJson'
consumes:
  - application/json
produces:
  - application/json
parameters:
  FiscalCode:
    name: fiscalcode
    in: path
    type: string
    maxLength: 16
    minLength: 16
    required: true
    description: The fiscal code of the user, all upper case.
    pattern: >-
      [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]
    x-example: SPNDNL80R13C555X
securityDefinitions:
  ApiKey:
    type: apiKey
    name: X-Functions-Key
    in: header
    description: The API key to access this function app.
definitions:
  Timestamp:
    type: string
    format: UTCISODateFromString
    description: A date-time field in ISO-8601 format and UTC timezone.
    x-import: '@pagopa/ts-commons/lib/dates'
    example: '2018-10-13T00:00:00.000Z'
  FiscalCode:
    type: string
    description: User's fiscal code.
    format: FiscalCode
    x-import: '@pagopa/ts-commons/lib/strings'
    example: SPNDNL80R13C555X
  ProblemJson:
    type: object
    properties:
      type:
        type: string
        format: uri
        description: |-
          An absolute URI that identifies the problem type. When dereferenced,
          it SHOULD provide human-readable documentation for the problem type
          (e.g., using HTML).
        default: about:blank
        example: https://example.com/problem/constraint-violation
      title:
        type: string
        description: |-
          A short, summary of the problem type. Written in english and readable
          for engineers (usually not suited for non technical stakeholders and
          not localized); example: Service Unavailable
      status:
        type: integer
        format: int32
        description: >-
          The HTTP status code generated by the origin server for this
          occurrence

          of the problem.
        minimum: 100
        maximum: 600
        exclusiveMaximum: true
        example: 200
      detail:
        type: string
        description: |-
          A human readable explanation specific to this occurrence of the
          problem.
        example: There was an error processing the request
      instance:
        type: string
        format: uri
        description: >-
          An absolute URI that identifies the specific occurrence of the
          problem.

          It may or may not yield further information if dereferenced.
  CommonCard:
    type: object
    properties:
      activation_date:
        $ref: '#/definitions/Timestamp'
      expiration_date:
        $ref: '#/definitions/Timestamp'
    required:
      - activation_date
      - expiration_date
  CardPending:
    type: object
    properties:
      status:
        type: string
        x-extensible-enum:
          - PENDING
    required:
      - status
  CardActivated:
    allOf:
      - $ref: '#/definitions/CommonCard'
      - type: object
        properties:
          status:
            type: string
            x-extensible-enum:
              - ACTIVATED
        required:
          - status
  CardRevoked:
    allOf:
      - $ref: '#/definitions/CommonCard'
      - type: object
        properties:
          status:
            type: string
            x-extensible-enum:
              - REVOKED
          revocation_date:
            $ref: '#/definitions/Timestamp'
          revocation_reason:
            type: string
            minLength: 1
        required:
          - status
          - revocation_date
          - revocation_reason
  CardExpired:
    allOf:
      - $ref: '#/definitions/CommonCard'
      - type: object
        properties:
          status:
            type: string
            x-extensible-enum:
              - EXPIRED
        required:
          - status
  CardPendingDelete:
    allOf:
      - $ref: '#/definitions/CommonCard'
      - type: object
        properties:
          status:
            type: string
            x-extensible-enum:
              - PENDING_DELETE
        required:
          - status
  Card:
    x-one-of: true
    allOf:
      - $ref: '#/definitions/CardPending'
      - $ref: '#/definitions/CardPendingDelete'
      - $ref: '#/definitions/CardActivated'
      - $ref: '#/definitions/CardRevoked'
      - $ref: '#/definitions/CardExpired'
    x-example:
      status: ACTIVATED
      activation_date: '2021-10-13T00:00:00.000Z'
      expiration_date: '2030-10-13T00:00:00.000Z'
  CcdbNumber:
    type: string
    description: The internal CCDB Card number
    pattern: ^[A-Z][0-9]{3}-[A-Z][0-9]{3}-[A-Z][0-9]{3}-[A-Z][0-9]{3}$
    minLength: 1
  EycaCardActivated:
    allOf:
      - $ref: '#/definitions/CardActivated'
      - type: object
        properties:
          card_number:
            $ref: '#/definitions/CcdbNumber'
        required:
          - card_number
  EycaCardExpired:
    allOf:
      - $ref: '#/definitions/CardExpired'
      - type: object
        properties:
          card_number:
            $ref: '#/definitions/CcdbNumber'
        required:
          - card_number
  EycaCardRevoked:
    allOf:
      - $ref: '#/definitions/CardRevoked'
      - type: object
        properties:
          card_number:
            $ref: '#/definitions/CcdbNumber'
        required:
          - card_number
  EycaCardPendingDelete:
    allOf:
      - $ref: '#/definitions/CardPendingDelete'
      - type: object
        properties:
          card_number:
            $ref: '#/definitions/CcdbNumber'
        required:
          - card_number
  EycaCard:
    x-one-of: true
    allOf:
      - $ref: '#/definitions/CardPending'
      - $ref: '#/definitions/EycaCardPendingDelete'
      - $ref: '#/definitions/EycaCardActivated'
      - $ref: '#/definitions/EycaCardRevoked'
      - $ref: '#/definitions/EycaCardExpired'
    x-example:
      status: ACTIVATED
      activation_date: '2021-10-13T00:00:00.000Z'
      expiration_date: '2030-10-13T00:00:00.000Z'
  CgnStatusUpsertRequest:
    type: object
    properties:
      action:
        type: string
        x-extensible-enum:
          - REVOKE
      revocation_reason:
        type: string
        minLength: 1
    required:
      - action
      - revocation_reason
  InstanceId:
    type: object
    properties:
      id:
        type: string
        minLength: 1
        description: The identifier of the created request.
    required:
      - id
  CgnActivationDetail:
    type: object
    properties:
      instance_id:
        $ref: '#/definitions/InstanceId'
      status:
        type: string
        x-extensible-enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - ERROR
          - UNKNOWN
      created_at:
        $ref: '#/definitions/Timestamp'
      last_updated_at:
        $ref: '#/definitions/Timestamp'
    required:
      - instance_id
      - status
  EycaActivationDetail:
    type: object
    properties:
      status:
        type: string
        x-extensible-enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - ERROR
          - UNKNOWN
      created_at:
        $ref: '#/definitions/Timestamp'
      last_updated_at:
        $ref: '#/definitions/Timestamp'
    required:
      - status
  OtpCode:
    description: The unique otp code that can be use for discounts
    type: string
    pattern: ^[A-Z0-9]{9,13}$
  Otp:
    type: object
    properties:
      code:
        $ref: '#/definitions/OtpCode'
      expires_at:
        $ref: '#/definitions/Timestamp'
      ttl:
        type: number
    required:
      - code
      - expires_at
      - ttl