api_io_sign.yaml

openapi: 3.0.1
info:
  version: 1.0.0
  title: IO Sign - Backend API
servers:
  - url: https://api-app.io.pagopa.it/api/v1/sign
security:
  - Bearer: []
paths:
  "/metadata":
    get:
      operationId: getMetadata
      summary: Get the io-sign metadata
      responses:
        "200":
          description: io-sign metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metadata"
        "401":
          description: Bearer token null or expired.
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

  "/qtsp/clauses":
    get:
      operationId: getQtspClausesMetadata
      summary: Get the qtsp clauses
      parameters:
        - in: header
          name: x-iosign-issuer-environment
          schema:
            $ref: "#/components/schemas/IssuerEnvironment"
          required: true
      responses:
        "200":
          description: The QTSP clauses list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QtspClausesMetadataDetailView"
        "401":
          description: Bearer token null or expired.
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

  "/qtsp/clauses/filled_document":
    post:
      operationId: createFilledDocument
      summary: Create a filled document for QTSP.
      description: |
        This endpoint returns a url that the client should poll until the resource has been created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFilledDocument"
      responses:
        "201":
          description: Filled document created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FilledDocumentDetailView"
          headers:
            Location:
              schema:
                type: string
                format: url
              description: |-
                Location (URL) of created request resource.
                A GET request to this URL returns the created document.
        "400":
          description: Validation error.
        "401":
          description: Bearer token null or expired.
        "404":
          description: Resource not found.
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

  "/signatures":
    post:
      operationId: createSignature
      summary: Create a Signature from SignatureRequest
      parameters:
        - name: x-pagopa-lollipop-original-method
          in: header
          description: The method of the endpoint called by IO app
          required: true
          schema:
            $ref: "#/components/schemas/LollipopMethod"
        - name: x-pagopa-lollipop-original-url
          in: header
          description: The url of the endpoint called by IO app
          required: true
          schema:
            $ref: "#/components/schemas/LollipopOriginalURL"
        - name: signature-input
          in: header
          description: The signature input, needed to verify the `signature` header
          required: true
          schema:
            $ref: "#/components/schemas/LollipopSignatureInput"
        - name: signature
          in: header
          description: The signature of the HTTP request, signed by the client with its private key.
          required: true
          schema:
            $ref: "#/components/schemas/LollipopSignature"
        - name: x-pagopa-lollipop-custom-tos-challenge
          in: header
          description: The tos challenge to sign.
          required: true
          schema:
            type: string
            example: f46a0523e83e2c45b3b948e76bb6617d35e0159f9ae2ccf27865efb5d390f8aa
            minLength: 1
        - name: x-pagopa-lollipop-custom-sign-challenge
          in: header
          description: The challenge to sign concerning documents.
          required: true
          schema:
            type: string
            example: f46a0523e83e2c45b3b948e76bb6617d35e0159f9ae2ccf27865efb5d390f8aa
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSignatureBody"
      responses:
        "200":
          description: Signature created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureDetailView"
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "401":
          description: Bearer token null or expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "403":
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "404":
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

  "/signature-requests":
    get:
      operationId: getSignatureRequests
      summary: Get the list of Signature Requests received by a Signer
      responses:
        "200":
          description: The Signature Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestList"
        "401":
          description: Bearer token null or expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "403":
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

  "/signature-requests/{id}":
    get:
      operationId: getSignatureRequestById
      summary: Get a Signature Request from id
      parameters:
        - in: path
          name: id
          schema:
            type: string
            description: Signature request Id
            format: ulid
            example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
            minLength: 1
          required: true
      responses:
        "200":
          description: The Signature Request detail
          headers:
            x-io-sign-environment:
              schema:
                $ref: "#/components/schemas/Environment"
              description: The environment to which the signature request belongs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureRequestDetailView"
        "401":
          description: Bearer token null or expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "403":
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "404":
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"
        "502":
          description: Bad gateway.
        "504":
          description: Gateway timeout.
        "500":
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemJson"

components:
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header

  schemas:
    Timestamp:
      $ref: "https://raw.githubusercontent.com/pagopa/io-functions-commons/v26.3.0/openapi/definitions.yaml#/Timestamp"

    ProblemJson:
      $ref: "https://raw.githubusercontent.com/pagopa/io-functions-commons/v26.3.0/openapi/definitions.yaml#/ProblemJson"

    CreateFilledDocument:
      type: object
      properties:
        document_url:
          type: string
          format: url
          minLength: 1
      required:
        - document_url

    FilledDocumentDetailView:
      type: object
      properties:
        filled_document_url:
          type: string
          format: url
      required:
        - filled_document_url

    QtspClause:
        type: object
        properties:
          text:
            type: string
            minLength: 1
        required:
          - text

    QtspClausesMetadataDetailView:
      type: object
      properties:
        clauses:
          type: array
          items:
            $ref: "#/components/schemas/QtspClause"
          minItems: 1
          uniqueItems: true
        document_url:
          type: string
          format: url
        privacy_url:
          type: string
          format: url
        privacy_text:
          type: string
          minLength: 1
        terms_and_conditions_url:
          type: string
          format: url
        nonce:
          type: string
          format: base64
          minLength: 1
      required:
        - clauses
        - document_url
        - privacy_url
        - privacy_text
        - terms_and_conditions_url
        - nonce

    Id:
      type: string
      description: Entity Id
      minLength: 1
      example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

    Clause:
      type: object
      properties:
        title:
          type: string
        type:
          type: string
          enum: ["REQUIRED", "UNFAIR", "OPTIONAL"]
      required:
        - title
        - type

    ExistingSignatureFieldAttrs:
        type: object
        properties:
          unique_name:
            type: string
            minLength: 1
        required:
          - unique_name

    Metadata:
      type: object
      properties:
        serviceId:
          type: string
          minLength: 1
      required:
        - serviceId

    SignatureFieldToBeCreatedAttrs:
      type: object
      properties:
        bottom_left:
          type: object
          properties:
            x: { type: number }
            y: { type: number }
          required:
            - x
            - y
        top_right:
          type: object
          properties:
            x: { type: number }
            y: { type: number }
          required:
            - x
            - y
        page:
          type: number
          minimum: 0
      required:
        - bottom_left
        - page
        - top_right

    SignatureFieldAttrs:
      x-one-of: true
      allOf:
        - $ref: "#/components/schemas/ExistingSignatureFieldAttrs"
        - $ref: "#/components/schemas/SignatureFieldToBeCreatedAttrs"

    SignatureField:
      type: object
      properties:
        attrs:
          $ref: "#/components/schemas/SignatureFieldAttrs"
        clause:
          $ref: "#/components/schemas/Clause"
      required:
        - attrs
        - clause

    DocumentToSign:
      type: object
      properties:
        document_id:
          type: string
          format: ulid
          minLength: 1
        signature_fields:
          type: array
          items:
            $ref: "#/components/schemas/SignatureField"
      required:
        - document_id
        - signature_fields

    QtspClauses:
      type: object
      properties:
        accepted_clauses:
          type: array
          items:
            $ref: "#/components/schemas/QtspClause"
          minItems: 1
          uniqueItems: true
        filled_document_url:
          type: string
          format: url
          minLength: 1
        nonce:
          type: string
          format: base64
          minLength: 1
      required:
        - accepted_clauses
        - filled_document_url
        - nonce

    CreateSignatureBody:
      type: object
      properties:
        signature_request_id:
          $ref: "#/components/schemas/Id"
        documents_to_sign:
          type: array
          items:
            $ref: "#/components/schemas/DocumentToSign"
          minItems: 1
          uniqueItems: true
        qtsp_clauses:
          $ref: "#/components/schemas/QtspClauses"
      required:
        - signature_request_id
        - documents_to_sign
        - qtsp_clauses

    SignatureDetailView:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Id"
        signature_request_id:
          $ref: "#/components/schemas/Id"
        qtsp_signature_request_id:
          $ref: "#/components/schemas/Id"
        status:
          type: string
          enum: ["CREATED", "READY", "WAITING", "COMPLETED", "FAILED"]
        created_at:
          $ref: "#/components/schemas/Timestamp"
        updated_at:
          $ref: "#/components/schemas/Timestamp"
      required:
        - id
        - signature_request_id
        - qtsp_signature_request_id
        - status

    DocumentMetadata:
        type: object
        properties:
          title:
            type: string
          signature_fields:
            type: array
            items:
              $ref: "#/components/schemas/SignatureField"
        required:
          - title
          - signature_fields

    DocumentDetailView:
        type: object
        properties:
          id:
            $ref: "#/components/schemas/Id"
          metadata:
            $ref: "#/components/schemas/DocumentMetadata"
          url:
            type: string
            format: uri
          created_at:
            $ref: "#/components/schemas/Timestamp"
          updated_at:
            $ref: "#/components/schemas/Timestamp"
        required:
          - id
          - metadata
          - url
          - created_at
          - updated_at

    DossierTitle:
      type: string
      minLength: 1

    SignatureRequestDetailView:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Id"
        status:
          $ref: "#/components/schemas/SignatureRequestStatus"
        issuer:
          type: object
          properties:
            email:
              type: string
              format: email
            description:
              type: string
              minLength: 1
            environment:
              $ref: "#/components/schemas/IssuerEnvironment"
          required:
              - email
              - description
              - environment
        dossier_id:
          $ref: "#/components/schemas/Id"
        dossier_title:
          $ref: "#/components/schemas/DossierTitle"
        signer_id:
          $ref: "#/components/schemas/Id"
        expires_at:
          $ref: "#/components/schemas/Timestamp"
        documents:
          type: array
          items:
            $ref: "#/components/schemas/DocumentDetailView"
        created_at:
          $ref: "#/components/schemas/Timestamp"
        updated_at:
          $ref: "#/components/schemas/Timestamp"
        qr_code_url:
          type: string
          format: uri
      required:
        - id
        - status
        - issuer
        - dossier_id
        - dossier_title
        - signer_id
        - expires_at
        - documents
        - created_at
        - updated_at

    SignatureRequestStatus:
      type: string
      x-extensible-enum:
        - WAIT_FOR_SIGNATURE
        - WAIT_FOR_QTSP
        - SIGNED
        - REJECTED
        - CANCELLED

    SignatureRequestListView:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Id"
        signer_id:
          $ref: "#/components/schemas/Id"
        dossier_id:
          $ref: "#/components/schemas/Id"
        dossier_title:
          $ref: "#/components/schemas/DossierTitle"
        status:
          $ref: "#/components/schemas/SignatureRequestStatus"
        created_at:
          $ref: "#/components/schemas/Timestamp"
        updated_at:
          $ref: "#/components/schemas/Timestamp"
        expires_at:
          $ref: "#/components/schemas/Timestamp"
      required:
        - id
        - signer_id
        - dossier_id
        - dossier_title
        - status
        - created_at
        - updated_at
        - expires_at

    SignatureRequestList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SignatureRequestListView"
      required:
        - items

    IssuerEnvironment:
      type: string
      enum:
        - TEST
        - DEFAULT

    LollipopMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
    LollipopOriginalURL:
      type: string
      pattern: "^https:\/\/"
    AssertionType:
      type: string
      enum:
        - SAML
        - OIDC
    LollipopAssertionRef:
      oneOf:
        - $ref: "#/components/schemas/AssertionRefSha256"
        - $ref: "#/components/schemas/AssertionRefSha384"
        - $ref: "#/components/schemas/AssertionRefSha512"
    LollipopUserId:
      type: string
      maxLength: 16
      minLength: 16
      description: The user's fiscal code, all upper case.
      pattern: >-
        ^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$
    LollipopPublicKey:
      type: string
      minLength: 1
      description: represents a Base64url encode of a JWK Public Key
    LollipopJWTAuthorization:
      type: string
      minLength: 1

    LollipopContentType:
      type: string
      enum:
        - application/json
        - application/octet-stream
    LollipopContentDigest:
      type: string
      pattern: "^(sha-256=:[A-Za-z0-9+/=]{44}:|sha-384=:[A-Za-z0-9+/=]{66}:|sha-512=:[A-Za-z0-9+/=]{88}:)$"

    LollipopSignatureInput:
      type: string
      pattern: "^(((sig[0-9]+)=[^,]*?)(, ?)?)+$"
    LollipopSignature:
      type: string
      pattern: "^((sig[0-9]+)=:[A-Za-z0-9+/=]*:(, ?)?)+$"

    # AssertionRef possible inputs
    AssertionRefSha256:
      type: string
      pattern: ^(sha256-[A-Za-z0-9-_=]{1,44})$
    AssertionRefSha384:
      type: string
      pattern: ^(sha384-[A-Za-z0-9-_=]{1,66})$
    AssertionRefSha512:
      type: string
      pattern: ^(sha512-[A-Za-z0-9-_=]{1,88})$

    Environment:
      type: string
      enum:
        - test
        - prod