openapi: 3.0.3
info:
  title: MasDocuments API
  description: >-
    I am <b><i>Mas Documents API</i></b>. My goal is to provide a way of storing
    and retrieving documents.
  version: v1
  contact:
    name: administrator
    email: masdoc.squad@masmovil.com
servers:
  - url: 'https://documents.masstack.com/v1/'
    description: production
  - url: 'https://documents.sta.masstack.com/v1/'
    description: staging
tags:
  - name: Documents
    description: Binary documents business logic
  - name: Forms
    description: Binary documents with field's map to fill
  - name: Sections
    description: Grouping of forms by language
  - name: Templates
    description: Document builder with sections
  - name: Templates Configuration
    description: Templates Tenant configuration
  - name: DynamicTemplates
    description: HTML based templates with fields to fill
  - name: Sign Process
    description: Access to digital sign processes management.
  - name: Biometric Signature
    description: Access to biometric signature endpoints.
  - name: Simple Signature
    description: Access to simple signature endpoints.
  - name: Identification Agent
    description: Digital agent identification services
  - name: Sign Configuration
    description: Sign Configuration
  - name: Identification OTP
    description: Digital OTP identification services
  - name: Identification with identity document
    description: Identification with identity document
  - name: Identification Agent Admin
    description: Digital agent identification administrative services
  - name: Identification OTP Admin
    description: Digital OTP identification administrative services
  - name: Identification with identity document Admin
    description: Identification with identity document administrative services
  - name: Contracts
    description: Contracts document services
  - name: Scoring
    description: Scoring services
  - name: Ingestions
    description: >-
      Asynchronous binary-ingestion read operations (executions and processed
      binaries)
paths:
  '/orgs/{org_id}/documents':
    post:
      tags:
        - Documents
      summary: Upload a document
      description: >-
        Upload a document from a file name and its content. The document unique
        identifier and its name are returned.
      operationId: uploadDocument
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: 'File name, content and metadata for creating the document.'
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - extension
                - name
                - content
              properties:
                name:
                  type: string
                  description: >-
                    Name of the document (without spaces). The document is
                    renamed with this value.
                  example: personal_contract
                extension:
                  $ref: '#/components/schemas/DocExtension'
                tags:
                  $ref: '#/components/schemas/TagsList'
                content:
                  type: string
                  format: binary
                  description: Document content in binary format
            example:
              name: New_document
              extension: pdf
              tags:
                - DRAFT
                - CONFIDENTIAL
                - v1.0
            encoding:
              content:
                contentType: >-
                  application/pdf, application/octet-stream, image/png,
                  image/jpeg
      responses:
        '201':
          description: New Document is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDocumentResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/documents/{documentId}':
    delete:
      tags:
        - Documents
      summary: Delete a document
      description: Delete document.
      operationId: deleteDocument
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Action executed correctly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: resource already deleted
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      tags:
        - Documents
      summary: Download a document
      description: >-
        Returns the document content as binary data, if document is present;
        else, returns an error message.
      operationId: downloadDocument
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
            format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: The document binary content. Expected response to a valid request.
          headers:
            Content-Type:
              description: defines response binary media type
              schema:
                type: string
                default: application/pdf
            Content-Disposition:
              description: contains downloaded document file name
              schema:
                type: string
                default: attachment; filename=file_name.pdf
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: binary file
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/documents/{documentId}/physical':
    delete:
      tags:
        - Documents
      summary: Delete a document physically
      description: Delete document physically.
      operationId: deleteDocumentPhysical
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Action executed correctly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: resource already deleted
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/documents/{documentId}/metadata':
    get:
      tags:
        - Documents
      summary: Gets metadata associated to a document
      description: Returns metadata information associated to a document
      operationId: getDocumentMetadata
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
            format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentMetadataResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/documents/{documentId}/public_url':
    post:
      tags:
        - Documents
      summary: Generate a temporal public accesible download url
      description: >-
        Returns the url to download the specified document, if document is
        present and reachable; else, returns an error message.
      operationId: createPublicUrl
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
            format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: Duration before public url expires and becomes not accesible
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicUrlRequest'
      responses:
        '200':
          description: The generated public url. Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicUrlResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/documents/{documentId}/owner':
    put:
      tags:
        - Documents
      summary: Change document owner
      description: >-
        Changes document owner, if document exists and is already private; else,
        returns an error message.
      operationId: changeOwner
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: documentId
          in: path
          required: true
          description: >-
            The string id related with one of Grupo MasOrange
            tenants/organizations
          schema:
            type: string
            format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: >-
          The identifier of the new owner to whom ownership of the document is
          transferred
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeOwnerRequest'
      responses:
        '200':
          description: Ownership change succeeded. Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeOwnerResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/forms':
    post:
      description: >-
        Upload a form from a file name and its content. The form unique
        identifier and its name are returned.The map of the fillable fields will
        be extracted.
      tags:
        - Forms
      summary: Upload a form
      operationId: uploadForm
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: 'File name, content and metadata for creating the form.'
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - extension
                - name
                - content
              properties:
                name:
                  type: string
                  description: >-
                    Name of the form (without spaces). The form is renamed with
                    this value (will be normalized on form external Id).
                  example: customer_contract
                extension:
                  $ref: '#/components/schemas/Extension'
                tags:
                  $ref: '#/components/schemas/TemplatesTags'
                content:
                  type: string
                  format: binary
                  description: Document content in binary format
            example:
              name: new_form
              extension: pdf
            encoding:
              content:
                contentType: 'application/pdf, application/octet-stream'
      responses:
        '201':
          description: New form is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFieldResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '409':
          description: Conflict. Resource already exist
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      description: Get all stored forms metadata (by tenant)
      tags:
        - Forms
      summary: Get uploaded forms metadata by tenant
      operationId: getAllForms
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: page
          in: query
          required: false
          description: >-
            Defines forms page number to be show. If not defined, default value
            is 0 (first page).
          schema:
            $ref: '#/components/schemas/TemplatesPage'
          example: 0
        - name: pageSize
          in: query
          required: false
          description: >-
            Defines the number of forms returned in each page. If not defined,
            default value is 50.
          schema:
            $ref: '#/components/schemas/TemplatesPageSize'
          example: 1
      responses:
        '200':
          description: >-
            The forms metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllFormsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/forms/{formReference}/fill':
    post:
      tags:
        - Forms
      summary: Fill a form
      description: >-
        Returns the filled form as PDF file, if form exists; else, returns an
        error message.
      operationId: fillForm
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: formReference
          in: path
          required: true
          description: The external id or id of the form
          schema:
            type: string
          example:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
            - form_name
      requestBody:
        description: values to fill a form
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillFormRequest'
      responses:
        '200':
          description: >-
            The filled form as pdf document. Expected response to a valid
            request.
          headers:
            Content-Type:
              description: defines response binary media type
              schema:
                type: string
                default: application/pdf
            Content-Disposition:
              description: contains downloaded filled form
              schema:
                type: string
                default: attachment; filename=file_name.pdf
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: pdf document
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/sections':
    post:
      description: Create a new section of forms
      tags:
        - Sections
      summary: Create a section
      operationId: createSection
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: metadata for creating a language section
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSectionRequest'
      responses:
        '201':
          description: New section is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionMetadata'
        '204':
          description: Section created successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: Conflict. Resource already exist
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      description: >-
        Get all stored sections info (by tenant) sorted by creation date in
        descending order. Results can be paginated by page and pageSize.

        If any values of page or pageSize are be provided, response will be all
        sections in one page (no pagination).
      tags:
        - Sections
      summary: Get all sections metadata by tenant
      operationId: getAllSections
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: page
          in: query
          required: false
          description: >-
            Defines sections page number to be show. If not defined, default
            value is 0 (first page).
          schema:
            $ref: '#/components/schemas/TemplatesPage'
          example: 0
        - name: pageSize
          in: query
          required: false
          description: >-
            Defines the number of sections returned in each page. If not
            defined, default value is 50.
          schema:
            $ref: '#/components/schemas/TemplatesPageSize'
          example: 1
      responses:
        '200':
          description: >-
            The sections metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllSectionsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates':
    post:
      description: Create a new template of sections
      tags:
        - Templates
      summary: Create a template
      operationId: createTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: Metadata for creating a template from language sections.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
            example:
              templateName: contracto_convergente
              defaultLanguage: ES
              orderedSectionNames:
                - introduction
                - personal_data
                - anexo_gdpr
              rules:
                - sectionExternalId: introduction
                  condition: 'PREVIEW:ALLOW'
                - sectionExternalId: anexo_gdpr
                  condition: 'GDPR:YES'
      responses:
        '201':
          description: New template is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMetadata'
        '204':
          description: Template created successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: Conflict. Resource already exist
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      description: >-
        Get all stored templates info (by tenant) sorted by creation date in
        descending order. Results can be paginated by page and pageSize.

        If any values of page or pageSize are be provided, response will be all
        templates in one page (no pagination).
      tags:
        - Templates
      summary: Get all templates metadata by tenant
      operationId: getAllTemplates
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: page
          in: query
          required: false
          description: >-
            Defines templates page number to be show. If not defined, default
            value is 0 (first page).
          schema:
            $ref: '#/components/schemas/TemplatesPage'
          example: 0
        - name: pageSize
          in: query
          required: false
          description: >-
            Defines the number of templates returned in each page. If not
            defined, default value is 50.
          schema:
            $ref: '#/components/schemas/TemplatesPageSize'
          example: 1
      responses:
        '200':
          description: >-
            The templates metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllTemplatesResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions':
    post:
      tags:
        - Templates
      summary: Upgrade a template
      description: >-
        Upgrading a template version creating a new one with it is own use
        contract
      operationId: upgradeTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: contract_sales
      requestBody:
        description: Metadata for upgrading a template from language sections
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeTemplateRequest'
            example:
              defaultLanguage: ES
              orderedSectionNames:
                - introduction
                - personal_data
                - contract_gdpr
              rules:
                - sectionId: introduction
                  condition: 'PREVIEW:ALLOW'
                - sectionId: contract_gdpr
                  condition: 'GDPR:YES'
              changelog: >-
                Added new GDPR descriptive text and formatting changes to the
                contract.
      responses:
        '201':
          description: >-
            New version template is created. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMetadata'
        '204':
          description: Template upgraded successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions/{version}':
    delete:
      tags:
        - Templates
      summary: Delete a template
      description: Delete the latest major version of a template
      operationId: deleteTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: convergente_particulares
        - name: version
          in: path
          required: true
          description: version of the template to be updated
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
      responses:
        '204':
          description: Template deleted successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: 'Conflict. Major version can not be deleted, it is not latest'
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    patch:
      tags:
        - Templates
      summary: Update a template
      description: Update a template version without change use contract
      operationId: updateTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: convergente_particulares
        - name: version
          in: path
          required: true
          description: version of the template to be updated
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
      requestBody:
        description: Metadata for upgrading a template from language sections
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateRequest'
      responses:
        '201':
          description: Version template is updated. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMetadata'
        '204':
          description: Template updated successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: Conflict. Resource already exist
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions/{version}/minor':
    delete:
      tags:
        - Templates
      summary: Delete a template
      description: Delete the latest minor version of a template
      operationId: deleteMinorTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: convergente_particulares
        - name: version
          in: path
          required: true
          description: version of the template to be updated
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
      responses:
        '204':
          description: Template deleted successfully.
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: Conflict. Minor version can not be deleted
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions/{version}/fill':
    post:
      tags:
        - Templates
      summary: Fill a template
      description: >-
        Returns the filled template as PDF file, if template exists; else,
        returns an error message.
      operationId: fillTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: contract_sales
        - name: version
          in: path
          required: true
          description: version of the template to be updated
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
      requestBody:
        description: Metadata to fill a template
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillTemplateRequest'
      responses:
        '200':
          description: >-
            The filled template as pdf document. Expected response to a valid
            request.
          headers:
            Content-Type:
              description: defines response binary media type
              schema:
                type: string
                default: application/pdf
            Content-Disposition:
              description: contains downloaded filled template
              schema:
                type: string
                default: attachment; filename=file_name.pdf
            X-Tenant-Config-Version:
              description: tenant config version used to fill
              schema:
                type: string
                example: '3'
            X-Template-Version:
              description: template version used to fill
              schema:
                type: string
                example: '2.1'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: pdf document
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions/{version}/fill/documents':
    post:
      tags:
        - Templates
      summary: Fill a template
      description: Fill a template and return documentId (storage reference)
      operationId: fillTemplateDocuments
      parameters:
        - name: x-auth-owner
          in: header
          required: false
          description: >-
            The string id related with the document owner. It is mandatory when
            document is not public
          schema:
            type: string
          example: '2357893'
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the template
          schema:
            type: string
          example: contract_sales
        - name: version
          in: path
          required: true
          description: version of the template to be updated
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
      requestBody:
        description: Metadata to fill a template
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillTemplateDocumentsRequest'
      responses:
        '200':
          description: >-
            The filled template as pdf document. Expected response to a valid
            request.
          headers:
            X-Tenant-Config-Version:
              description: tenant config version used to fill
              schema:
                type: string
                example: '3'
            X-Template-Version:
              description: template version used to fill
              schema:
                type: string
                example: '2.1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillTemplateDocumentsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/forms/{formReference}/metadata':
    get:
      description: >-
        Get uploaded form metadata by form id. This endpoint returns the same
        response as create form endpoint.
      tags:
        - Forms
      summary: Get uploaded form metadata.
      operationId: metadataForm
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: formReference
          in: path
          required: true
          description: The string 'id' or 'external id' of the desired form
          schema:
            type: string
          example:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
            - form_name
      responses:
        '200':
          description: >-
            The form metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFieldResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/sections/{externalId}/metadata':
    get:
      description: >-
        Get section metadata by section external id. This endpoint returns the
        same response as create section endpoint.
      tags:
        - Sections
      summary: Get section metadata.
      operationId: metadataSection
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: externalId
          in: path
          required: true
          description: The external id of the desired section
          schema:
            type: string
          example: anexo_gdpr
      responses:
        '200':
          description: >-
            The section metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionMetadata'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/sections/{externalId}':
    delete:
      description: Delete section by section external id.
      tags:
        - Sections
      summary: Delete section if is not used in templates.
      operationId: deleteSection
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: externalId
          in: path
          required: true
          description: The external id of the desired section
          schema:
            type: string
          example: anexo_gdpr
      responses:
        '204':
          description: The section is deleted successfully
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: Conflict. Section is in use in some template
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/versions/{version}/metadata':
    get:
      description: >-
        Get template metadata by template external id. This endpoint returns the
        same response as create template endpoint.
      tags:
        - Templates
      summary: Get template metadata.
      operationId: metadataTemplate
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the desired template
          schema:
            type: string
          example: ifcc_template
        - name: version
          in: path
          required: true
          description: version of the template
          schema:
            type: integer
            minimum: 1
            maximum: 32767
          example: '1'
        - name: include
          in: query
          required: false
          description: >-
            Define extra options to include in response. Values:

            * 'history': return all versions (previous minor versions) of a
            major template version
          schema:
            type: string
          example: include=history
      responses:
        '200':
          description: >-
            The template metadata is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateMetadataResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/{templateExternalId}/changelog':
    get:
      description: Get template change log history by template's external id.
      tags:
        - Templates
      summary: Get template changelog history.
      operationId: geTemplateChangelog
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: templateExternalId
          in: path
          required: true
          description: The external id of the desired template
          schema:
            type: string
          example: ifcc_template
      responses:
        '200':
          description: >-
            The template changelog history is returned. Expected response for a
            valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateChangelogHistoryResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/forms/{formReference}':
    get:
      description: Download form
      tags:
        - Forms
      summary: Get form binary file.
      operationId: downloadForm
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: formReference
          in: path
          required: true
          description: The string 'id' or 'external id' of the desired form
          schema:
            type: string
          example:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
            - form_name
      responses:
        '200':
          description: The form binary content. Expected response to a valid request.
          headers:
            Content-Type:
              description: defines response binary media type
              schema:
                type: string
                default: application/pdf
            Content-Disposition:
              description: contains downloaded form name
              schema:
                type: string
                default: attachment; filename=file_name.pdf
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: binary file
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    delete:
      description: Delete form
      tags:
        - Forms
      summary: Delete form and its documents
      operationId: deleteForm
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: formReference
          in: path
          required: true
          description: The string 'id' or 'external id' of the desired form
          schema:
            type: string
          example:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
            - form_name
      responses:
        '204':
          description: Action executed correctly
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: conflict if form is in some section
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/configurations/documents':
    post:
      description: Upload a new document to be used in templates
      tags:
        - Templates Configuration
      summary: Create a new configuration document
      operationId: uploadConfigurationDocument
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: page
          in: query
          required: false
          description: >-
            Defines templates configuration page number to be show. If not
            defined, default value is 0 (first page).
          schema:
            $ref: '#/components/schemas/TemplatesPage'
          example: 0
        - name: pageSize
          in: query
          required: false
          description: >-
            Defines the number of items returned in each page. If not defined,
            default value is 50.
          schema:
            $ref: '#/components/schemas/TemplatesPageSize'
          example: 1
        - name: name
          in: query
          required: false
          description: Filter by document name
          example: my_logo
          schema:
            type: string
        - name: extension
          in: query
          required: false
          description: Filter by document extension
          example: png
          schema:
            type: string
      requestBody:
        description: Define configuration fields with value by language
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - extension
                - content
              properties:
                name:
                  type: string
                  description: Name of the document (without spaces).
                  example: masorange_logo
                extension:
                  $ref: '#/components/schemas/ConfigurationDocumentExtension'
                content:
                  type: string
                  format: binary
                  description: Document content in binary format
            example:
              name: new_logo
              extension: jpg
            encoding:
              content:
                contentType: 'image/png, image/jpeg'
      responses:
        '200':
          description: Configuration is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConfigurationDocumentResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      description: Get all configuration documents
      tags:
        - Templates Configuration
      summary: Get all tenant configuration documents
      operationId: getAllConfigurationDocuments
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      responses:
        '200':
          description: Tenant all templates configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllConfigurationDocumentsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/configurations':
    post:
      description: Create or update a tenant templates configuration
      tags:
        - Templates Configuration
      summary: Create or update a tenant templates configuration
      operationId: createOrUpdateTemplateConfiguration
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: Define configuration fields with value by language
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateTemplateConfigurationRequest'
      responses:
        '200':
          description: Configuration is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateOrUpdateTemplateConfigurationResponse
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      description: Get all tenant templates configurations
      tags:
        - Templates Configuration
      summary: Get all tenant templates configurations
      operationId: getAllTemplateConfigurations
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: page
          in: query
          required: false
          description: >-
            Defines templates configuration page number to be show. If not
            defined, default value is 0 (first page).
          schema:
            $ref: '#/components/schemas/TemplatesPage'
          example: 0
        - name: pageSize
          in: query
          required: false
          description: >-
            Defines the number of items returned in each page. If not defined,
            default value is 50.
          schema:
            $ref: '#/components/schemas/TemplatesPageSize'
          example: 1
      responses:
        '200':
          description: Tenant all templates configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllTenantConfigurationsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/templates/configurations/{version}':
    get:
      description: Get tenant templates configuration
      tags:
        - Templates Configuration
      summary: Get tenant templates configuration
      operationId: getTemplateConfiguration
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: version
          in: path
          required: true
          schema:
            type: string
          example: '1'
          description: >-
            Higher version of the template. You can use also 'latest' to get
            latest version
      responses:
        '200':
          description: Tenant templates configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTenantConfigurationResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    delete:
      description: Delete template configuration by version
      tags:
        - Templates Configuration
      summary: Delete template configuration for a given version
      operationId: deleteConfigVersion
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: version
          in: path
          required: true
          schema:
            type: string
          example: '1'
          description: Version of the template configuration.
      responses:
        '204':
          description: Action executed correctly
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '409':
          description: conflict if form is in some section
        '422':
          description: Request input can not be processed (is incomplete)
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates':
    post:
      tags:
        - DynamicTemplates
      summary: Create a new dynamic template
      description: >-
        Creates a new dynamic template by uploading HBS and JSON configuration
        files for multiple languages. The structure (JSON schema) is provided as
        part of each source metadata, extracted from the template editor. The
        system validates the structure and persists the template with version
        1.0.
      operationId: createDynamicTemplate
      parameters:
        - $ref: '#/components/parameters/OrgId'
      requestBody:
        description: >-
          Template metadata and sources (HBS and JSON files) for each language.
          Each source includes the pre-extracted structure with fields, rules,
          and engine version.
        required: true
        content:
          multipart/mixed:
            schema:
              type: object
              required:
                - metadata
              properties:
                metadata:
                  $ref: '#/components/schemas/CreateDynamicTemplateMetadata'
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Array of template and editor config files for each language
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: >-
            New dynamic template is created. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDynamicTemplateResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '409':
          description: Conflict. External ID already exists
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    get:
      tags:
        - DynamicTemplates
      summary: Get all editable dynamic templates
      description: >-
        Returns a paginated list of all dynamic templates for an organization.
        Only the latest version of each major

        version (the ones that could be edited) is included, ordered by
        creation_date in descending order.
      operationId: getAllDynamicTemplates
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - name: external_id
          in: query
          required: false
          description: Optional filter to retrieve templates for a specific external_id
          schema:
            type: string
          example: factura_mensual
        - $ref: '#/components/parameters/DynamicTemplatesPage'
        - $ref: '#/components/parameters/DynamicTemplatesPageSize'
      responses:
        '200':
          description: >-
            The templates list is returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllDynamicTemplatesResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/versions/{major_version}':
    get:
      tags:
        - DynamicTemplates
      summary: Get all minor versions of a major version
      description: >-
        Returns all minor versions for a specific major version of a dynamic
        template, ordered by minor version in

        descending order (newest to oldest). Includes JSON schema extracted from
        the template file.
      operationId: getDynamicTemplateVersions
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
      responses:
        '200':
          description: >-
            The template versions are returned. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDynamicTemplateVersionsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template or version not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    patch:
      tags:
        - DynamicTemplates
      summary: Create a new minor version
      description: >-
        Creates a new minor version of an existing dynamic template with
        non-breaking changes such as adding new

        languages or updating existing language content. Breaking changes like
        modifying the JSON schema structure, removing sources or changing
        default language will result in a 409 error.
      operationId: createDynamicTemplateMinorVersion
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
      requestBody:
        description: Template metadata and sources for creating a minor version
        required: true
        content:
          multipart/mixed:
            schema:
              type: object
              required:
                - metadata
              properties:
                metadata:
                  $ref: '#/components/schemas/CreateMinorVersionMetadata'
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Array of template and editor config files for each language
            encoding:
              metadata:
                contentType: application/json
      responses:
        '200':
          description: New minor version is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDynamicTemplateResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template not found
        '409':
          description: Breaking changes detected. Use major version endpoint instead.
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
    delete:
      tags:
        - DynamicTemplates
      summary: Delete a major version
      description: >-
        Deletes a complete major version line including all its minor versions.
        Only the latest major version can be 

        deleted.
      operationId: deleteDynamicTemplateMajorVersion
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
      responses:
        '204':
          description: Major version deleted successfully
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template or version not found
        '409':
          description: Cannot delete. Not the latest major version.
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/versions/{major_version}/minors/{minor_version}':
    get:
      tags:
        - DynamicTemplates
      summary: Get specific minor version details
      description: >-
        Returns complete information for a specific minor version of a dynamic
        template, including JSON schema

        and source URLs for rendering or analysis.
      operationId: getDynamicTemplateMinorVersion
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
        - $ref: '#/components/parameters/MinorVersion'
      responses:
        '200':
          description: >-
            The specific template version details are returned. Expected
            response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicTemplateDetails'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template or version not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/versions':
    post:
      tags:
        - DynamicTemplates
      summary: Create a new major version
      description: >-
        Creates a new major version of an existing dynamic template with
        breaking changes. All languages must be provided with their sources. The
        new version will be X+1.0 where X is the highest existing major version.

        All new information in the template must be provided, as the information
        from the previous version will not be kept.
      operationId: createDynamicTemplateMajorVersion
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
      requestBody:
        description: Template metadata and sources for creating a major version
        required: true
        content:
          multipart/mixed:
            schema:
              type: object
              required:
                - metadata
              properties:
                metadata:
                  $ref: '#/components/schemas/CreateMajorVersionMetadata'
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Array of template and editor config files for each language
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: New major version is created. Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDynamicTemplateResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/versions/{major_version}/minor':
    delete:
      tags:
        - DynamicTemplates
      summary: Delete latest minor version
      description: >-
        Deletes the latest minor version of a specific major version line.
        Cannot delete the base version (X.0) or if it's the only minor version
        in the major line.
      operationId: deleteDynamicTemplateMinorVersion
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
      responses:
        '204':
          description: Minor version deleted successfully
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template or version not found
        '409':
          description: Cannot delete base version (X.0) or only minor version in major line
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/changelog':
    get:
      tags:
        - DynamicTemplates
      summary: Get template changelog history
      description: >-
        Returns the complete changelog history for a dynamic template, showing
        all version transitions ordered by version in descending order (newest
        to oldest).
      operationId: getDynamicTemplateChangelog
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
      responses:
        '200':
          description: >-
            The template changelog history is returned. Expected response for a
            valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicTemplateChangelogResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have failed
        '404':
          description: Template not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/dynamic_templates/{external_id}/versions/{major_version}/fill':
    post:
      tags:
        - DynamicTemplates
      summary: Submit a fill request for a dynamic template
      description: >-
        Submit an asynchronous request to fill a specific version of a dynamic
        template with provided data. The system validates the field values
        against the template's JSON schema and registers the request for
        asynchronous processing. Returns immediately with a fill_process_id that
        can be used to check status via the GET /fill_process endpoint. The
        system automatically adds a template tag with format
        '{templateExternalId}-v{templateVersion}' to user-provided tags when
        creating the document.
      operationId: createFillProcess
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/MajorVersion'
        - $ref: '#/components/parameters/FillProcessOrigin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFillProcessRequest'
      responses:
        '202':
          description: Fill request accepted and registered for processing
          headers:
            fill-process-origin:
              description: >-
                The origin that was set for this fill process (either provided
                or defaulted to aud)
              schema:
                type: string
              example: sales-platform
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFillProcessResponse'
        '400':
          description: Invalid input or field values don't match template schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication
        '404':
          description: Template or version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/fill_process/{fill_process_id}':
    get:
      tags:
        - DynamicTemplates
      summary: Get fill process status
      description: >-
        Check the status of an asynchronous document fill process. Returns the
        current state (CREATED, PROCESSING, COMPLETED, FAILED) and relevant
        metadata based on the state.
      operationId: getFillProcess
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/FillProcessId'
      responses:
        '200':
          description: Fill process status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillProcessResponse'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: Fill process not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Internal server error
  '/orgs/{org_id}/sign_process':
    post:
      tags:
        - Sign Process
      summary: Create new digital sign process
      description: >-
        Creates a new digital sign process according with its input data. The
        digital sign process unique identifier is returned.
      operationId: postSignProcess
      parameters:
        - $ref: '#/components/parameters/OrgId1'
      requestBody:
        description: >-
          Data about signers, documents to be signed and associated
          identification processes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSignProcessRequest'
      responses:
        '201':
          description: >-
            New digital sign process is created. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSignProcessResponse'
          headers:
            Location:
              schema:
                type: string
              description: >-
                Created resource URI. Example
                /orgs/masmovil/sign_process/00cf016d-070d-4fe0-9fd2-ffb80cb6a642
              example: /orgs/masmovil/sign_process/00cf016d-070d-4fe0-9fd2-ffb80cb6a642
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/sign_process/{sign_process_id}':
    get:
      tags:
        - Sign Process
      summary: Get digital sign process information
      description: Get digital sign process information
      operationId: getSignProcess
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/SignProcessId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignProcessResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/sign_process/{sign_process_id}/cancel':
    post:
      tags:
        - Sign Process
      summary: Cancel digital sign process
      description: Cancel digital sign process
      operationId: cancelSignProcess
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/SignProcessId'
      requestBody:
        description: Necessary data to execute action
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSignProcessRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '409':
          description: process is not in a cancelable state
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/biometric_signs/{sign_id}':
    get:
      tags:
        - Biometric Signature
      summary: Get biometric signature information
      description: Get biometric signature information
      operationId: getBiometricSign
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/SignId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/biometric_signs/{sign_id}/preview':
    post:
      tags:
        - Biometric Signature
      summary: Preview biometric signature
      description: Preview biometric signature
      operationId: previewBiometricSignature
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/SignId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/biometric_signs/{sign_id}/sign':
    post:
      tags:
        - Biometric Signature
      summary: Sign biometric signature
      description: Sign using biometric signature
      operationId: signBiometricSignature
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/SignId'
      requestBody:
        description: Necessary data to execute action
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BiometricSignRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/simple_signs/{sign_id}':
    get:
      tags:
        - Simple Signature
      summary: Get simple signature information
      description: Get simple signature information
      operationId: getSimpleSign
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/SignId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/simple_signs/{sign_id}/preview':
    post:
      tags:
        - Simple Signature
      summary: Preview simple signature
      description: Preview simple signature
      operationId: previewSimpleSignature
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/SignId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/simple_signs/{sign_id}/sign':
    post:
      tags:
        - Simple Signature
      summary: Sign using simple signature
      description: Sign simple signature
      operationId: signSimpleSignature
      parameters:
        - $ref: '#/components/parameters/OrgId1'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/SignId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/securize':
    post:
      tags:
        - Securize
      summary: Securize data info into a web_component authn jwt token
      description: >-
        Securizes an Authn token with necessary payload and roles to validate
        AuthZ
      operationId: securize
      parameters:
        - $ref: '#/components/parameters/OrgId1'
      requestBody:
        description: Sign data to securize
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurizeSign'
      responses:
        '201':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurizeSignResponse'
  '/orgs/{org_id}/sign_process/configurations':
    get:
      tags:
        - Sign Configuration
      summary: Get sign configuration
      description: Get sign configuration
      operationId: getSignConfiguration
      parameters:
        - $ref: '#/components/parameters/OrgId2'
      responses:
        '200':
          description: Sign configuration of given tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignConfiguration'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error4011'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
    post:
      tags:
        - Sign Configuration
      summary: Create new configuration
      description: Create new configuration
      operationId: createSignConfiguration
      parameters:
        - $ref: '#/components/parameters/OrgId2'
      requestBody:
        description: Data about sign configuration
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - landing_url
                - expiration_duration
                - channels
                - content
                - sign_certificate_password
                - notification_email
              properties:
                landing_url:
                  $ref: '#/components/schemas/LandingUrl'
                expiration_duration:
                  $ref: '#/components/schemas/ExpirationDuration'
                channels:
                  $ref: '#/components/schemas/NotificationChannels'
                content:
                  $ref: '#/components/schemas/SignCertificateContent'
                sign_certificate_password:
                  $ref: '#/components/schemas/SignCertificatePassword'
                notification_email:
                  $ref: '#/components/schemas/NotificationEmail'
                identification_config:
                  type: string
                  description: JSON array of scoring provider configurations per sign type
      responses:
        '204':
          description: New sign configuration is created.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error4011'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
    patch:
      tags:
        - Sign Configuration
      summary: Update configuration
      description: Update configuration
      operationId: updateSignConfiguration
      parameters:
        - $ref: '#/components/parameters/OrgId2'
      requestBody:
        description: Data about sign configuration
        required: true
        content:
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/ConfigurationPatchRequest'
      responses:
        '204':
          description: Sign configuration is created.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error4011'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/identity_document/{identification_id}':
    get:
      tags:
        - Identification with identity document
      summary: Get identity document identification
      description: Get identity document identification
      operationId: getIdentityDocumentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/GetIdentityDocumentIdentificationMetadataResponse
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/identity_document/{identification_id}/validate':
    post:
      tags:
        - Identification with identity document
      summary: Validate identity document identification
      description: >-
        Validates an existing and previously scored identification by identity
        document.
      operationId: validateIdentityDocumentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '204':
          $ref: '#/components/responses/Success204WithAccessToken'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent/{identification_id}/validate':
    post:
      tags:
        - Identification Agent
      summary: Validate agent identification
      description: >-
        Validates an existing identification by agent. The agent acts as a
        trusted verifier, validating the actor's identification.
      operationId: validateAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/UserAgent'
      requestBody:
        description: Required data to execute action
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateAgentIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent/{identification_id}':
    get:
      tags:
        - Identification Agent
      summary: Get identification process metadata
      description: Get information about agent identification process
      operationId: getAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentIdentificationMetadataResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{identification_id}':
    get:
      tags:
        - Identification OTP
      summary: Get otp identification process metadata
      description: Get information about otp identification process
      operationId: getOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
      responses:
        '200':
          description: Expected response for a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOtpIdentificationMetadataResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{identification_id}/validate':
    put:
      tags:
        - Identification OTP
      summary: OTP identification token validation
      description: OTP identification token validation
      operationId: validateOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/UserAgent'
      requestBody:
        description: Necessary data to execute action
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateOtpIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204WithAccessToken'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '410':
          $ref: '#/components/responses/Error410'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{identification_id}/challenge':
    put:
      tags:
        - Identification OTP
      summary: OTP identification token challenge
      description: OTP identification token challenge
      operationId: challengeOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - $ref: '#/components/parameters/IdentificationId'
      requestBody:
        description: Necessary data to execute action
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOtpChallengeRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success200WithTwoFactorValue'
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/chain/{identification_chain_id}':
    get:
      tags:
        - Identification Chain
      summary: Get chained identification process status
      description: >-
        Returns the global status and step details of a chained identification
        process.
      operationId: getChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - name: identification_chain_id
          in: path
          required: true
          description: Unique identifier for the chained identification process
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '200':
          description: Chained identification status found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChainIdentificationResponse'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        default:
          $ref: '#/components/responses/ErrorDefault'
      x-headers:
        - name: Authorization
          description: Bearer token with required permissions
          required: true
        - $ref: '#/components/parameters/UserAgent'
  '/orgs/{org_id}/identifications/chain/{identification_chain_id}/validate':
    post:
      tags:
        - Identification Chain
      summary: Validate chained identification process
      description: >-
        Validates a chained identification process.  If the process exists and
        is in CREATED state, and all nested identifications are VALIDATED, the
        chain  transitions to VALIDATED and a short-lived x-access-token (JWT)
        is generated and returned in the response  header. Otherwise, returns
        409 Conflict if the process or any nested identification is not in the
        required state,  or 404 Not Found if the chain does not exist.
      operationId: validateChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - name: identification_chain_id
          in: path
          required: true
          description: Unique identifier for the chained identification process
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        - $ref: '#/components/parameters/XInstallationId'
        - $ref: '#/components/parameters/XLocation'
        - $ref: '#/components/parameters/XFingerprint'
        - $ref: '#/components/parameters/XForwardedFor'
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '204':
          $ref: '#/components/responses/Success204WithAccessToken'
        '400':
          $ref: '#/components/responses/Error400'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        default:
          $ref: '#/components/responses/ErrorDefault'
      x-headers:
        - name: Authorization
          description: Bearer token with required permissions
          required: true
        - name: User-Agent
          description: User agent string
          required: true
        - name: x-fingerprint
          description: Device fingerprint
          required: true
        - name: x-installation_id
          description: Browser installation id
          required: true
        - name: x-location
          description: Device location coordinate
          required: false
  '/orgs/{org_id}/identifications/chain/{identification_chain_id}/restart':
    post:
      tags:
        - Identification Chain
      summary: Restart chained identification process.
      description: >-
        Restores the states and metadata for a chained identification process to
        CREATED state so that all VALIDATED  steps are invalidated and should be
        done again. If a step is in CREATED state, it remains unchanged. This
        operation can only be performed if the chained identification process is
        in VALIDATED or CREATED state.
      operationId: restartChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId3'
        - name: identification_chain_id
          in: path
          required: true
          description: Unique identifier for the chained identification process
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '204':
          description: Restoration successful. No Content returned.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
      x-headers:
        - name: Authorization
          description: Bearer token with required permissions
          required: true
        - $ref: '#/components/parameters/UserAgent'
  '/orgs/{org_id}/identifications/identity_document':
    post:
      tags:
        - Identification with identity document Admin
      summary: Create new identification
      description: >-
        Creates a new identification according with its input data. The
        identification unique identifier is returned.
      operationId: createIdentityDocumentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
      requestBody:
        description: Data about actor and the identification process.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityDocumentIdentificationRequest'
      responses:
        '200':
          description: >-
            New agent identification is created. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateIdentityDocumentIdentificationResponse
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/identity_document/{admin_identification_id}/cancel':
    post:
      tags:
        - Identification with identity document Admin
      summary: Cancel an identity document identification process
      description: >-
        Cancels an ongoing identity document identification process. A cancel
        reason must be provided.
      operationId: cancelIdentityDocumentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      requestBody:
        description: Required data to cancel an identity document identification process
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/chain':
    post:
      tags:
        - Identification Chain Admin
      summary: Create a chained identification process.
      description: >-
        Creates a new chained identification process with a ordered sequence of
        identification steps (at least one, without repeated elements).
      operationId: createChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminUserAgent'
      requestBody:
        description: Data about actor and the identification chain process.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChainIdentificationRequest'
      responses:
        '201':
          description: New chain identification is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChainIdentificationResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/chain/{identification_chain_id}/cancel':
    post:
      tags:
        - Identification Chain Admin
      summary: Cancel a chained identification
      description: >-
        Cancels an active chained identification. State will transition to
        CANCELLED. Also attempts to cancel any active nested identification
        steps. Identification chain status must be in a cancellable state, i.e.
        CREATED. 409 Conflict (MDOC_005) will be  returned otherwise.
      operationId: cancelChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - name: identification_chain_id
          in: path
          required: true
          description: Unique identifier for the chained identification process
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        - $ref: '#/components/parameters/AdminUserAgent'
      requestBody:
        description: Optional reason for cancellation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/chain/{identification_chain_id}/close':
    post:
      tags:
        - Identification Chain Admin
      summary: Close a chained identification process
      description: >-
        Closes a chained identification process if it is in VALIDATED state. In
        case of SUCCEEDED, close will be  ignored. If the process is not in the
        VALIDATED or SUCCEEDED state (e.g., CREATED, FAILED, EXPIRED,
        CANCELLED), it will  return a 409 Conflict (MDOC_005), indicating the
        operation is not allowed in the current state. If the process is in
        VALIDATED state: Closes all nested identifications. Updates the chain
        process state to SUCCEEDED. Registers the close date/time.
      operationId: closeChainIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - name: identification_chain_id
          in: path
          required: true
          description: Unique identifier for the chained identification process
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        - $ref: '#/components/parameters/AdminUserAgent'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/identity_document/{admin_identification_id}/close':
    post:
      tags:
        - Identification with identity document Admin
      summary: Close an identity document Identification process
      description: Close an identity document Identification process if not is finished
      operationId: closeIdentityDocumentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent':
    post:
      tags:
        - Identification Agent Admin
      summary: Create new agent identification
      description: >-
        Creates a new agent identification according with its input data. The
        agent identification unique identifier is returned.
      operationId: createAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
      requestBody:
        description: Data about actor and the identification process.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentIdentificationRequest'
      responses:
        '201':
          description: >-
            New agent identification is created. Expected response for a valid
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentIdentificationResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent/{admin_identification_id}/cancel':
    post:
      tags:
        - Identification Agent Admin
      summary: Cancel an agent identification process
      description: >-
        Cancels an ongoing agent identification process. A cancel reason must be
        provided.
      operationId: cancelAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      requestBody:
        description: Required data to cancel an identification process
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent/{admin_identification_id}/close':
    post:
      tags:
        - Identification Agent Admin
      summary: Close an Agent Identification process
      description: Close an Agent Identification process if not is finished
      operationId: closeAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp':
    post:
      tags:
        - Identification OTP Admin
      summary: Create otp identification process
      description: Create otp identification process
      operationId: createOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
      requestBody:
        description: Data about actor and the otp identification process.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOtpIdentificationRequest'
      responses:
        '201':
          description: New otp identification is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOtpIdentificationResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{admin_identification_id}/cancel':
    post:
      tags:
        - Identification OTP Admin
      summary: Cancel an OTP identification process
      description: >-
        Cancels an ongoing OTP identification process. A cancel reason must be
        provided.
      operationId: cancelOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      requestBody:
        description: Required data to cancel an identification process
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelIdentificationRequest'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{admin_identification_id}/close':
    post:
      tags:
        - Identification OTP Admin
      summary: Close an OTP identification process
      description: Close an OTP identification process if not is finished
      operationId: closeOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/otp/{admin_identification_id}':
    delete:
      tags:
        - Identification OTP Admin
      summary: Delete otp identification process
      description: >-
        Delete otp identification process. It is intended for incomplete
        identifications unless force param is used
      operationId: deleteOtpIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
        - $ref: '#/components/parameters/ForceDelete'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/identifications/agent/{admin_identification_id}':
    delete:
      tags:
        - Identification Agent Admin
      summary: Delete agent identification process
      description: >-
        Delete agent identification process. It is intended for incomplete
        identifications unless force param is used
      operationId: deleteAgentIdentification
      parameters:
        - $ref: '#/components/parameters/OrgId4'
        - $ref: '#/components/parameters/AdminIdentificationId'
        - $ref: '#/components/parameters/ForceDelete'
      responses:
        '204':
          $ref: '#/components/responses/Success204'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
        default:
          $ref: '#/components/responses/ErrorDefault'
  '/orgs/{org_id}/contracts/{contract_id}':
    get:
      tags:
        - Contracts
      summary: Get contract information
      description: Get contract information from mas-documents storage
      operationId: getContract
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with tenants which contract belongs to
          schema:
            type: string
          example: yoigo
        - name: contract_id
          in: path
          required: true
          description: Contract identifier
          schema:
            type: string
          example: 00c6a5a6-2d8a-4857-9b32-a4abbdbd0c2c
      responses:
        '200':
          description: Expected response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContractResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: Resource not found
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/contracts/fill':
    post:
      tags:
        - Contracts
      summary: Fill a template to create a new filled contract
      description: >-
        Fill a template and return a contractId and a documentId (storage
        reference)
      operationId: createFilledContract
      parameters:
        - name: x-auth-owner
          in: header
          required: true
          description: The string id related with the contract owner. It is mandatory
          schema:
            type: string
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: Data to fill (and sign data) a template contract
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFilledContractRequest'
      responses:
        '200':
          description: Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFilledContractResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/contracts/{contract_id}/owner':
    put:
      tags:
        - Contracts
      summary: Change contract's owner
      description: Allows to change the owner of an existing contract
      operationId: changeContractOwner
      parameters:
        - name: x-auth-owner
          in: header
          required: true
          description: The string id related with the contract owner. It is mandatory
          schema:
            type: string
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
        - name: contract_id
          in: path
          required: true
          description: Contract identifier
          schema:
            type: string
            format: uuid
          example: 00c6a5a6-2d8a-4857-9b32-a4abbdbd0c2c
      requestBody:
        description: Data required to update contract's owner
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeContractOwnerRequest'
      responses:
        '200':
          description: Owner changed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeContractOwnerResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '404':
          description: resource not found
        '410':
          description: resource is not longer available
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/contracts/sign':
    post:
      tags:
        - Contracts
      summary: Create new online/onsite sign process
      description: >-
        Creates a new sign process according with its input data. The digital
        process unique identifier is returned.
      operationId: signContracts
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with one of Grupo MasOrange tenants
          schema:
            type: string
          example: masmovil
      requestBody:
        description: metadata for creating the contract's sign process
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignContractsRequest'
      responses:
        '201':
          description: >-
            New sign process is created to sign contracts. Expected response for
            a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignContractsResponse'
        '400':
          description: Request input is not valid
        '401':
          description: Unauthorized. AuthN and AuthZ validations have fail
        '500':
          description: Not expected error
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document':
    post:
      tags:
        - Scoring
      summary: Create scoring
      description: Create scoring
      operationId: createIdentityDocumentScoring
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with tenants which contract belongs to
          schema:
            type: string
          example: yoigo
      requestBody:
        description: Data to create scoring
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScoringRequest'
      responses:
        '200':
          description: Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScoringResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}/captures':
    get:
      tags:
        - Scoring
      summary: Get identity document captures
      description: Get identity document captures
      operationId: getIdentityDocumentCaptures
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with tenants which contract belongs to
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: Scoring id
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCapturesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}':
    get:
      tags:
        - Scoring
      summary: Get identity document scoring
      description: Get identity document scoring
      operationId: getIdentityDocumentScoring
      parameters:
        - name: org_id
          in: path
          required: true
          description: The string id related with tenants which contract belongs to
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: Scoring id
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityDocumentScoring'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}/score':
    put:
      tags:
        - Scoring
      summary: Submit identity document images for scoring
      description: >-
        Uploads front and/or back images of the identity document to perform
        fraud and authenticity checks, updating the scoring session with
        results.
      operationId: scoreIdentityDocument
      parameters:
        - name: org_id
          in: path
          required: true
          description: >-
            Unique identifier of the organization (tenant) that owns this
            scoring session.
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: >-
            Unique identifier of the identity document scoring session to
            update.
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - $ref: '#/components/parameters/XInstallationId1'
        - $ref: '#/components/parameters/XFingerprint1'
        - $ref: '#/components/parameters/XLocation1'
        - $ref: '#/components/parameters/UserAgent1'
        - $ref: '#/components/parameters/XForwardedFor1'
      requestBody:
        description: >-
          Multipart payload containing binary images for the front and/or back
          of the document to be evaluated.
        required: false
        content:
          multipart/mixed:
            schema:
              type: object
              properties:
                front:
                  type: string
                  format: binary
                  description: >-
                    Binary image data for the front side of the identity
                    document.
                back:
                  type: string
                  format: binary
                  description: >-
                    Binary image data for the back side of the identity
                    document.
      responses:
        '204':
          description: Identity document scored successfully; no content returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '425':
          $ref: '#/components/responses/TooEarly'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}/close':
    post:
      tags:
        - Scoring
      summary: Close identity document scoring
      description: >-
        Finalizes and closes the scoring session, preventing any further image
        submissions or status changes.
      operationId: closeIdentityDocumentScoring
      parameters:
        - name: org_id
          in: path
          required: true
          description: >-
            Unique identifier of the organization (tenant) that owns this
            scoring session.
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: Unique identifier of the identity document scoring session to close.
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '204':
          description: Scoring session successfully closed; no content returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}/delegate':
    post:
      tags:
        - Scoring
      summary: Delegate identity document scoring
      description: >-
        Sends the scoring request to an external provider and returns the
        provider’s access details.
      operationId: delegateIdentityDocumentScoring
      parameters:
        - name: org_id
          in: path
          required: true
          description: >-
            Unique identifier of the organization (tenant) that owns this
            scoring session.
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: >-
            Unique identifier of the identity document scoring session to
            delegate.
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: JSON with provider configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegateScoringProviderConfiguration'
      responses:
        '200':
          description: >-
            Delegation successful; returns external provider credentials and
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegateIdentityDocumentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/scorings/identity_document/{scoring_id}/attempts':
    get:
      tags:
        - Scoring
      summary: Get scoring attempts history
      description: >-
        Returns the list of scoring attempts for the specified identity document
        scoring session.
      operationId: getScoringAttempts
      parameters:
        - name: org_id
          in: path
          required: true
          description: >-
            Unique identifier of the organization (tenant) that owns this
            scoring session.
          schema:
            type: string
          example: yoigo
        - name: scoring_id
          in: path
          required: true
          description: Unique identifier of the identity document scoring session.
          schema:
            type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Expected response to a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoringAttemptsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/executions':
    get:
      tags:
        - Ingestions
      summary: List executions of an ingestion
      description: >
        Returns a paginated list of executions for a given ingestion, ordered
        from the most recent to the oldest.

        Results can be filtered by execution status and by a temporal range over
        the execution start instant.

        Queries are always restricted to the tenant of the bearer token:
        cross-tenant access yields 404.
      operationId: listIngestionExecutions
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
        - $ref: '#/components/parameters/ExecutionStatusFilter'
        - $ref: '#/components/parameters/FromTs'
        - $ref: '#/components/parameters/ToTs'
        - $ref: '#/components/parameters/IngestionsPage'
        - $ref: '#/components/parameters/IngestionsPageSize'
      responses:
        '200':
          description: Page of executions for the given ingestion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIngestionExecutionsResponse'
        '400':
          description: >-
            Request input is not valid (e.g. invalid id, status, timestamp,
            page_size > 200).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN/AuthZ validations have failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: Forbidden. Scope not allowed to read executions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: Ingestion not found or belongs to a different tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Not expected error.
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/executions/{execution_id}':
    get:
      tags:
        - Ingestions
      summary: Get execution detail
      description: >
        Returns the detail of a single execution (metadata + counters).

        The response never embeds the list of processed binaries — that detail
        is exposed only

        through the dedicated paginated endpoint.
      operationId: getIngestionExecution
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
        - $ref: '#/components/parameters/ExecutionId'
      responses:
        '200':
          description: Execution detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionExecution'
        '400':
          description: Request input is not valid (e.g. invalid id).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN/AuthZ validations have failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: Forbidden. Scope not allowed to read executions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: 'Ingestion or execution not found, or belongs to a different tenant.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Not expected error.
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/executions/{execution_id}/processed-binaries':
    get:
      tags:
        - Ingestions
      summary: List processed binaries of an execution
      description: >
        Returns the paginated list of binaries processed by a given execution.

        Designed to sustain executions with millions of binaries without
        exhausting memory or bandwidth.

        Results can be filtered by processing outcome and by a temporal range
        over the recorded instant.
      operationId: listIngestionExecutionProcessedBinaries
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
        - $ref: '#/components/parameters/ExecutionId'
        - $ref: '#/components/parameters/OutcomeFilter'
        - $ref: '#/components/parameters/FromTs'
        - $ref: '#/components/parameters/ToTs'
        - $ref: '#/components/parameters/IngestionsPage'
        - $ref: '#/components/parameters/IngestionsPageSize'
      responses:
        '200':
          description: Page of processed binaries for the given execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExecutionProcessedBinariesResponse'
        '400':
          description: >-
            Request input is not valid (e.g. invalid id, result, timestamp,
            page_size > 200).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN/AuthZ validations have failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: Forbidden. Scope not allowed to read executions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: 'Ingestion or execution not found, or belongs to a different tenant.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Not expected error.
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/deconsolidate':
    post:
      tags:
        - Ingestions
      summary: Deconsolidate an ingested document
      description: >-
        Reverts the consolidation of a document previously consolidated in the
        given ingestion. The client identifies the document by its document
        identifier. The service determines the original provisional owner
        internally.
      operationId: deconsolidateIngestedDocument
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
      requestBody:
        description: Identifier of the document to deconsolidate.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeconsolidateIngestedDocumentRequest'
      responses:
        '200':
          description: Document successfully deconsolidated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeconsolidateIngestedDocumentResponse'
        '400':
          description: >-
            Request input is not valid (malformed body, missing required fields,
            invalid id format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN validation has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: >-
            The caller's scope is not authorized to deconsolidate ingested
            documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: >-
            Either the ingestion does not exist or the document was not ingested
            in the given ingestion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '409':
          description: The document is not consolidated or the ingestion is closed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/close':
    post:
      tags:
        - Ingestions
      summary: Close an ingestion
      description: >
        Closes an open ingestion. The operation is idempotent: closing an
        already-closed ingestion

        returns 200 with the current state without modifying anything.

        Cross-tenant access yields 404.
      operationId: closeIngestion
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
      responses:
        '200':
          description: Ingestion successfully closed (or already closed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseIngestionResponse'
        '400':
          description: Request input is not valid (e.g. invalid ingestion id format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN/AuthZ validations have failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: Forbidden. Scope not allowed to close ingestions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: Ingestion not found or belongs to a different tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
  '/orgs/{org_id}/ingestions/{ingestion_id}/consolidate':
    post:
      tags:
        - Ingestions
      summary: Consolidate an ingested document
      description: >-
        Consolidates a document previously ingested in the given ingestion under
        the consumer domain's final owner. The client identifies the document
        by  the pair (ingestion, original filename) and supplies the final
        business  owner; provisional owners are never sent.
      operationId: consolidateIngestedDocument
      parameters:
        - $ref: '#/components/parameters/OrgId5'
        - $ref: '#/components/parameters/IngestionId'
      requestBody:
        description: >-
          Original filename of the ingested binary and the final business owner
          that will take ownership of the document.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsolidateIngestedDocumentRequest'
      responses:
        '200':
          description: Document successfully consolidated under the final owner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsolidateIngestedDocumentResponse'
        '400':
          description: >-
            Request input is not valid (malformed body, missing required fields,
            invalid filename or owner format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '401':
          description: Unauthorized. AuthN validation has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '403':
          description: >-
            The caller's scope is not authorized to consolidate ingested
            documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '404':
          description: >-
            Either the ingestion does not exist or the document was not ingested
            in the given ingestion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '409':
          description: The document is already consolidated or the ingestion is closed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
components:
  schemas:
    ErrorsResponse:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/Errors'
      description: Errors response
    Errors:
      type: array
      description: List of errors
      items:
        $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - code
        - title
        - ref
        - details
      properties:
        code:
          type: string
          example: MDOC-001
          description: |-
            Error codes:
             *  MDOC_000
             *  MDOC_001
             *  MDOC_002
             *  MDOC_003
             *  MDOC_004
             *  MDOC_005
             *  MDOC_006
        title:
          type: string
          example: RESOURCE_NOT_FOUND
          description: |-
            Error titles:
             * `PARAMETER_ERROR`
             * `INTERNAL_SERVER_ERROR`
             * `INVALID_INPUT`
             * `UNAUTHORIZED`
             * `RESOURCE_NOT_FOUND`
             * `RESOURCE_IS_NO_LONGER_AVAILABLE`
             * `CONFLICT`
             * `UNPROCESSABLE_ENTITY`
        ref:
          type: string
          example: >-
            https://developers.masstack.com/en/docs/apis_consents_doc_swagger/2/schemas/#schemaerror
          description: Url of the error details in Developer portal
        details:
          type: string
          example: Resource not found
          description: Message and details of the error
      example:
        code: MDOC-XXX
        title: ERROR_TYPE
        ref: >-
          https://developers.masstack.com/en/docs/apis_documents_doc_swagger/1/schemas/#schemaerror
        details: Detailed description of the error
    DocExtension:
      type: string
      description: >-
        Format of the document to be stored. It must match the format of the
        binary

        Allowed values: pdf, jpeg, jpg, png, html, json, hbs
      example: pdf
    DocTag:
      type: string
      description: >-
        Free values (user-defined) to tag document. These values are normalized
        following the next rules:

        - All tags will be converted to UPPERCASE

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      example: DRAFT
    PostDocumentResponse:
      type: object
      required:
        - documentId
      properties:
        documentId:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Document unique identifier
    CreatePublicUrlRequest:
      type: object
      properties:
        expiresIn:
          description: >-
            Default to 24 hours. Max 24 hours. Validity duration time (ISO-8601
            format) of the public url from now.
          type: string
          example: PT24H
        downloadDisposition:
          description: >-
            Controls the disposition of the content (if the PDF is rendered
            inline or downloaded). 

            Allowed values "attachment" or "inline".
          type: string
          example: inline
          default: attachment
          enum:
            - attachment
            - inline
    CreatePublicUrlResponse:
      type: object
      required:
        - expirationDate
        - publicUrl
        - contentType
        - name
      additionalProperties: false
      properties:
        expirationDate:
          description: Timestamp (ISO-8601 format) at which public url becomes inaccesible.
          type: string
          example: '2023-01-27T03:44:52.000Z'
        publicUrl:
          description: Signed url fully accessible without authentication or authorization.
          type: string
          example: >-
            https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
        mediaType:
          description: Binary media type of the downloadable document
          type: string
          example: application/pdf
        name:
          description: Name of the downloadable document
          type: string
          example: my_doc_name
    ChangeOwnerRequest:
      type: object
      properties:
        newOwner:
          description: The identifier of the new owner of the document
          type: string
          example: sUbScRiPtiOn_12123112a
    ChangeOwnerResponse:
      type: object
      required:
        - owner
      properties:
        owner:
          description: The normalized identifier of the new owner of the document
          type: string
          example: subscription_12123112a
    TagsList:
      type: array
      description: >-
        Free values (user-defined) to tag document. These values are normalized
        following the next rules:

        - All tags will be converted to UPPERCASE

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      maxItems: 5
      uniqueItems: true
      items:
        $ref: '#/components/schemas/DocTag'
      example:
        - Draft
        - Top_Secret
        - v1.0
    GetDocumentMetadataResponse:
      type: object
      required:
        - documentId
        - name
        - tags
        - extension
        - archiveHash
        - size
        - isPublic
      properties:
        documentId:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Document unique identifier
        name:
          type: string
          description: >-
            Name of the document (without spaces). The document is renamed with
            this value.
          example: personal_contract
        tags:
          $ref: '#/components/schemas/TagsList'
        extension:
          $ref: '#/components/schemas/DocExtension'
        archiveHash:
          type: string
          example: 938c2cc0dcc05f2b68c4287040cfcf71
          description: Document hash digest
        size:
          type: integer
          description: The size of the document in bytes.
          example: 400000000
        isPublic:
          type: boolean
          description: >-
            Indicates if document is public (without owner) or private (with
            owner defined)
          example: true
    DeleteDocumentResponse:
      type: object
      required:
        - deletedDocumentId
        - deleteTS
      properties:
        deletedDocumentId:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: deleted document unique identifier
        deleteTS:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
          description: instant when document was deleted by first time
    Extension:
      type: string
      description: |-
        Format of the form to be stored. It must match the format of the binary
        Allowed values: pdf
      example: pdf
    TemplatesLanguages:
      type: array
      minItems: 1
      description: list of available languages for the template
      example:
        - ES
        - EU
        - EN
        - DE
        - GL
        - CA
      items:
        $ref: '#/components/schemas/TemplatesLanguage'
    TemplatesLanguage:
      type: string
      description: |-
        Templates languages allowed
        Allowed values: ES, EN, EU, GL, CA, DE, UNDEFINED
      example: ES
    ConfigurationChangelog:
      description: Description of the template change in this version
      type: string
      example: TEXT
    Fields:
      type: array
      description: >-
        list all fields available to fill in all the sections that belongs to
        the template
      uniqueItems: true
      items:
        $ref: '#/components/schemas/Field'
    Field:
      type: string
      description: It's field's name in a form
      example: NAME
    FormFields:
      type: array
      description: list all fields types
      uniqueItems: true
      items:
        $ref: '#/components/schemas/FormField'
    FormField:
      type: object
      required:
        - key
        - type
      properties:
        type:
          type: string
          description: Name of the field
          example: SIGNATURE
        key:
          type: string
          description: Type of the field
          example: SIGNABLE
      description: |-
        Type of the field. One of:
          - SIGNABLE: It will contain customer signature.
          - FILLABLE: Will admit text. 
          - FILLABLE_RADIO_BUTTON: Intended for exclusive choices
          - FILLABLE_CHECK_BOX: Inteded for inclusive choices.
          - FILLABLE_IMAGE: Can contain an image.
      example:
        key: NAME
        type: FILLABLE
    TemplatesTags:
      type: array
      description: >-
        Five free values (user-defined) to tag form. These values are normalized
        following the next rules:

        - All tags will be converted to uppercase

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      maxItems: 5
      uniqueItems: true
      items:
        $ref: '#/components/schemas/TemplatesTag'
    TemplatesTag:
      type: string
      description: >-
        Free values (user-defined) to tag document. These values are normalized
        following the next rules:

        - All tags will be converted to lowercase

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      example: DRAFT
    Forms:
      type: array
      minItems: 1
      description: defines which form is defined to each language
      items:
        $ref: '#/components/schemas/Form'
    Form:
      type: object
      required:
        - language
        - formExternalId
      properties:
        language:
          $ref: '#/components/schemas/TemplatesLanguage'
        formExternalId:
          type: string
          description: Form name (normalized)
          example: contract_gdpr_en
    TemplatesConditions:
      type: array
      minItems: 0
      items:
        $ref: '#/components/schemas/TemplatesCondition'
      description: >-
        list of conditions which trigger specific sections of the template to be
        filled
      example:
        - 'GDPR:YES'
        - 'PREVIEW:ALLOW'
    TemplatesCondition:
      type: string
      description: >-
        Tuple FLAG:VALUE (flag and expected value) that will evaluated to know
        if this section have to be filled
      example: 'GDPR:YES'
    Rules:
      type: array
      items:
        $ref: '#/components/schemas/Rule'
      description: >-
        defines conditions rules that have to be matched in fill flags values,
        to allow this section to be filled
    Rule:
      type: object
      required:
        - sectionExternalId
        - condition
      properties:
        sectionExternalId:
          type: string
          description: Section external Id (section name normalized)
          example: contract_gdpr
        condition:
          $ref: '#/components/schemas/TemplatesCondition'
    FillMode:
      type: string
      description: >-
        Allowed values: 'default', 'raw'

        Describes character's filter process to execute when fill a
        form/template:

        - 'default' (also when no value or unrecognized value): all non
        alfa-numeric characters are escaped and replaced by '?'

        - 'raw': like 'default' but 'tabulation' and 'end of line' characters
        are allowed
      example: default
    Flatten:
      type: boolean
      default: true
      description: Describes if the filled template will be flattened or not.
    FormFieldResponses:
      type: array
      items:
        $ref: '#/components/schemas/FormFieldResponse'
    FormFieldResponse:
      type: object
      required:
        - id
        - externalId
        - fields
        - creationDate
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: form unique identifier
        externalId:
          type: string
          example: contract_gdpr_es
          description: form name normalized
        fields:
          $ref: '#/components/schemas/FormFields'
        tags:
          $ref: '#/components/schemas/TemplatesTags'
        creationDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
          description: date of creation of the form
    CreateSectionRequest:
      type: object
      required:
        - sectionName
        - forms
      properties:
        sectionName:
          type: string
          example: contract_gdpr
          description: name of section of forms (will be normalized on section external Id)
        forms:
          $ref: '#/components/schemas/Forms'
    SectionMetadatas:
      type: array
      description: List of sections metadata
      uniqueItems: true
      items:
        $ref: '#/components/schemas/SectionMetadata'
    SectionMetadata:
      type: object
      required:
        - externalId
        - fields
        - forms
        - creationDate
      properties:
        externalId:
          type: string
          example: anexo_gdpr
          description: normalized name of section (external id)
        forms:
          $ref: '#/components/schemas/Forms'
        fields:
          $ref: '#/components/schemas/FormFields'
        creationDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
    CreateTemplateRequest:
      type: object
      required:
        - templateName
        - defaultLanguage
        - orderedSectionNames
      properties:
        templateName:
          type: string
          example: convergentes
          description: >-
            name of template of sections (will be normalized on template
            external Id)
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        orderedSectionNames:
          $ref: '#/components/schemas/OrderedSectionNames'
        rules:
          $ref: '#/components/schemas/Rules'
    UpgradeTemplateRequest:
      type: object
      required:
        - defaultLanguage
        - orderedSectionNames
      properties:
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        orderedSectionNames:
          $ref: '#/components/schemas/OrderedSectionNames'
        rules:
          $ref: '#/components/schemas/Rules'
        changelog:
          type: string
          example: >-
            Added new GDPR descriptive text and formatting changes to the
            contract.
    UpdateTemplateRequest:
      type: object
      properties:
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        orderedSectionNames:
          $ref: '#/components/schemas/OrderedSectionNames'
        rules:
          $ref: '#/components/schemas/Rules'
        changelog:
          type: string
          example: Template change reason description.
    UpdateTemplateResponse:
      type: object
      required:
        - externalId
        - languages
        - defaultLanguage
        - fields
        - version
      properties:
        externalId:
          type: string
          example: contrato_convergente
          description: normalized name of template (external id)
        languages:
          $ref: '#/components/schemas/TemplatesLanguages'
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        fields:
          $ref: '#/components/schemas/FormFields'
        conditions:
          $ref: '#/components/schemas/TemplatesConditions'
        version:
          type: string
          example: '1'
          description: Higher version of the template
    FieldsValues:
      type: array
      items:
        $ref: '#/components/schemas/FillFieldsValues'
      description: form variables whose values will be printed in the filled form
    FillFieldsValues:
      type: object
      required:
        - name
        - value
      description: Tuple representing a form field to be filled with a value
      properties:
        name:
          description: Form field name
          type: string
        value:
          description: Form field value
          type: string
    FillTemplateRequest:
      type: object
      required:
        - language
        - fieldsValues
      properties:
        language:
          $ref: '#/components/schemas/TemplatesLanguage'
        flagsConditions:
          $ref: '#/components/schemas/TemplatesConditions'
        fieldsValues:
          $ref: '#/components/schemas/FieldsValues'
        fillMode:
          $ref: '#/components/schemas/FillMode'
    TemplatesPage:
      type: integer
      description: Forms page to be shown
      minimum: 0
      default: 0
      example: 0
    TemplatesPageSize:
      type: integer
      minimum: 1
      default: 50
      description: Number of forms that will be shown by page
      example: 50
    AllFormsResponse:
      type: object
      required:
        - totalResults
        - currentPage
        - forms
      properties:
        totalResults:
          type: integer
          example: '100'
          description: Number of total forms to get
        currentPage:
          type: integer
          example: 0
          description: Current page
        forms:
          $ref: '#/components/schemas/FormFieldResponses'
    AllSectionsResponse:
      type: object
      required:
        - totalResults
        - currentPage
        - sections
      properties:
        totalResults:
          type: integer
          example: '100'
          description: Number of total sections to get
        currentPage:
          type: integer
          example: 0
          description: Current page
        sections:
          $ref: '#/components/schemas/SectionMetadatas'
    AllTemplatesResponse:
      type: object
      required:
        - totalResults
        - currentPage
        - templates
      properties:
        totalResults:
          type: integer
          example: '100'
          description: Number of total templates to get
        currentPage:
          type: integer
          example: 0
          description: Current page
        templates:
          $ref: '#/components/schemas/TemplateMetadataList'
    TemplateMetadataResponse:
      type: object
      properties:
        templates:
          $ref: '#/components/schemas/TemplateMetadataList'
      description: Template metadata response
    TemplateMetadataList:
      type: array
      description: List of templates metadatas
      items:
        $ref: '#/components/schemas/TemplateMetadata'
    TemplateMetadata:
      type: object
      required:
        - externalId
        - languages
        - defaultLanguage
        - orderedSectionNames
        - fields
        - version
        - creationDate
      properties:
        externalId:
          type: string
          example: contrato_convergente
          description: normalized name of template (external id)
        version:
          type: string
          example: '1.0'
          description: Higher version of the template
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        languages:
          $ref: '#/components/schemas/TemplatesLanguages'
        orderedSectionNames:
          $ref: '#/components/schemas/OrderedSectionNames'
        fields:
          $ref: '#/components/schemas/FormFields'
        rules:
          $ref: '#/components/schemas/Rules'
        creationDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
          description: date when template was created
    TemplateDocTag:
      type: string
      description: >-
        Free values (user-defined) to tag document. These values are normalized
        following the next rules:

        - All tags will be converted to lowercase

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      example: DRAFT
    FillTemplateDocumentsResponse:
      type: object
      required:
        - documentId
        - renamedKeys
      properties:
        documentId:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Document unique identifier
        renamedKeys:
          $ref: '#/components/schemas/RenamedTemplateKeys'
    RenamedTemplateKeys:
      type: array
      minItems: 0
      items:
        $ref: '#/components/schemas/RenamedTemplateKey'
      description: List of template keys which name has changed from original template
    RenamedTemplateKey:
      type: object
      required:
        - currentName
        - originalName
      properties:
        currentName:
          type: string
          example: SUBSCRIPTION_ID_212
          description: Current template key name
        originalName:
          type: string
          example: SUBSCRIPTION_ID
          description: Original template key name
    FillTemplateDocumentsRequest:
      type: object
      required:
        - language
        - fieldsValues
      properties:
        language:
          $ref: '#/components/schemas/TemplatesLanguage'
        flagsConditions:
          $ref: '#/components/schemas/TemplatesConditions'
        fieldsValues:
          $ref: '#/components/schemas/FieldsValues'
        name:
          type: string
          description: >-
            Name of the document (without spaces). The document is renamed with
            this value.
          example: personal_contract
        tags:
          $ref: '#/components/schemas/TemplatesTags'
        fillMode:
          $ref: '#/components/schemas/FillMode'
        flatten:
          $ref: '#/components/schemas/Flatten'
    FillFormRequest:
      type: object
      required:
        - fieldsValues
      properties:
        fieldsValues:
          $ref: '#/components/schemas/FieldsValues'
        fillMode:
          $ref: '#/components/schemas/FillMode'
    ChangelogHistory:
      type: array
      items:
        $ref: '#/components/schemas/TemplateChangelog'
      description: list of all template's version changes with its changelog and date
    TemplateChangelog:
      type: object
      required:
        - fromVersion
        - toVersion
        - onDate
        - changelog
      description: Tuple representing a form field to be filled with a value
      properties:
        fromVersion:
          description: Initial version before template change
          type: string
          example: '1.0'
        toVersion:
          description: Final version after template change
          type: string
          example: '1.1'
        onDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
          description: date when template was changed
        changelog:
          type: string
          description: change log defined by user when template changes
          example: >-
            Added new GDPR descriptive text and formatting changes to the
            contract.
    TemplateChangelogHistoryResponse:
      type: object
      required:
        - changelogHistory
      properties:
        changelogHistory:
          $ref: '#/components/schemas/ChangelogHistory'
    GetAllTenantConfigurationsResponse:
      type: object
      required:
        - totalResults
        - currentPage
        - configurations
      description: All templates configurations
      properties:
        totalResults:
          type: integer
          example: '100'
          description: Number of total forms to get
        currentPage:
          type: integer
          example: 0
          description: Current page
        configurations:
          $ref: '#/components/schemas/Configurations'
    GetTenantConfigurationResponse:
      type: object
      required:
        - defaultLanguage
        - fieldValues
      description: Templates configuration by tenant and version
      properties:
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        fieldValues:
          $ref: '#/components/schemas/ConfigurationFieldValues'
    CreateOrUpdateTemplateConfigurationRequest:
      type: object
      required:
        - defaultLanguage
        - fieldValues
      description: Data to create or update a template configuration
      properties:
        changelog:
          $ref: '#/components/schemas/ConfigurationChangelog'
        defaultLanguage:
          $ref: '#/components/schemas/TemplatesLanguage'
        fieldValues:
          $ref: '#/components/schemas/ConfigurationFieldValues'
    Configurations:
      type: array
      description: List of forms metadata
      uniqueItems: true
      items:
        $ref: '#/components/schemas/ConfigurationMetadata'
    ConfigurationMetadata:
      type: object
      required:
        - version
        - changelog
        - creationDate
      description: configuration field type and values by language
      properties:
        version:
          type: integer
          example: 1
          description: Defines template configuration version (initial version is '1')
        changelog:
          $ref: '#/components/schemas/ConfigurationChangelog'
        creationDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
          description: date when template was created
    ConfigurationFieldValues:
      type: array
      description: Configuration fields with default values by language
      uniqueItems: true
      minItems: 1
      items:
        $ref: '#/components/schemas/ConfigurationFieldValue'
    ConfigurationFieldValue:
      type: object
      required:
        - name
        - type
        - value
      description: configuration field type and values by language
      properties:
        name:
          description: 'Configuration field name. Must start with prefix: CONFIG_TENANT.'
          type: string
          example: CONFIG_TENANT.SOCIAL_REASON
        type:
          description: 'Configuration field type. Allowed values: IMAGE and TEXT'
          type: string
          example: TEXT
        value:
          $ref: '#/components/schemas/ConfigurationFieldValueByLanguages'
    OrderedSectionNames:
      type: array
      description: >-
        list sections external Ids that belongs to the template IN THE ORDER in
        which they should be concatenated when filled
      minItems: 1
      items:
        type: string
      example:
        - introduction
        - personal_data
        - anexo_gdpr
    ConfigurationFieldValueByLanguages:
      type: array
      description: Configuration field value by language
      uniqueItems: true
      minItems: 1
      items:
        $ref: '#/components/schemas/ConfigurationFieldValueByLanguage'
    ConfigurationFieldValueByLanguage:
      type: object
      required:
        - language
        - content
      description: Field values by language
      properties:
        language:
          $ref: '#/components/schemas/TemplatesLanguage'
        content:
          description: |-
            Configuration field value. It is dependent from field 'type':
            - 'IMAGE': then value must be a valid documentId (UUID)
            - 'TEXT': then value must be a text (string)
          type: string
          example: 'Avenida de Bruselas 38, Alcobendas, Madrid'
    CreateOrUpdateTemplateConfigurationResponse:
      type: object
      required:
        - version
      properties:
        version:
          type: integer
          example: 1
          description: Defines template configuration version (initial version is '1')
    ConfigurationDocumentExtension:
      type: string
      description: >-
        Format of the document to be stored. It must match the format of the
        binary

        Allowed values: jpeg, jpg, png
      example: pdf
    CreateConfigurationDocumentResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Templates document unique identifier
    ConfigurationDocument:
      type: object
      required:
        - id
        - name
        - extension
        - creationDate
      description: configuration field type and values by language
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Templates document unique identifier.
        name:
          type: string
          description: Name of the document.
          example: new_logo_mm
        extension:
          type: string
          description: Format of the document.
          example: png
        creationDate:
          type: string
          format: date-time
          example: '2022-08-21T17:32:28Z'
          description: Creation date of the document.
    ConfigurationDocuments:
      type: array
      description: List of configuration documents
      uniqueItems: true
      items:
        $ref: '#/components/schemas/ConfigurationDocument'
    GetAllConfigurationDocumentsResponse:
      type: object
      required:
        - totalResults
        - currentPage
        - items
      description: All configuration documents
      properties:
        totalResults:
          type: integer
          example: '100'
          description: Number of total forms to get
        currentPage:
          type: integer
          example: 0
          description: Current page
        items:
          $ref: '#/components/schemas/ConfigurationDocuments'
    FillProcessId:
      type: string
      description: Unique identifier for the fill process request
      example: 11223344-aabb-ccdd-eeff-009988776655
    ExternalId:
      type: string
      description: >-
        Unique identifier for the template. Must be lowercase, numbers, and
        underscores only.
      example: factura_bilingue_premium
    DynamicTemplatesLanguage:
      type: string
      description: |-
        Language of the template in ISO 639-1 format.
        Possible values: ES, EN, EU, GL, CA, DE, UNDEFINED
        Not all values are available to all organizations.
      example: ES
    DynamicTemplatesPage:
      type: integer
      description: Page to be shown
      minimum: 0
      default: 0
      example: 0
    DynamicTemplatesPageSize:
      type: integer
      minimum: 1
      default: 50
      description: Number of templates that will be shown by page
      example: 20
    DynamicTemplateTag:
      type: string
      description: >-
        Free values (user-defined) to tag dynamic template. These values are
        normalized following the next rules:

        - All tags will be converted to uppercase

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      example: factura
    DynamicTemplateTags:
      type: array
      description: >-
        Free values (user-defined) to tag dynamic template. Maximum 5 tags
        allowed.
      maxItems: 5
      minItems: 0
      uniqueItems: true
      items:
        $ref: '#/components/schemas/DynamicTemplateTag'
      example:
        - factura
        - multi-idioma
    Source:
      type: object
      required:
        - language
        - template_part_name
        - editor_config_part_name
        - structure
        - engine_version
      properties:
        language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        template_part_name:
          type: string
          description: Name of the multipart containing the handlebars template file
        editor_config_part_name:
          type: string
          description: Name of the multipart containing the JSON editor configuration file
        structure:
          $ref: '#/components/schemas/Structure'
        engine_version:
          type: string
          description: >-
            Semantic version of the rendering engine to use for this template.
            Should only contain major and minor version, without patch.
          example: '3.12'
    TemplateDescription:
      type: string
      description: Human-readable description of the template
      example: Plantilla para facturas en Español e Inglés.
    CreateDynamicTemplateMetadata:
      type: object
      required:
        - external_id
        - description
        - default_language
        - sources
      properties:
        external_id:
          $ref: '#/components/schemas/ExternalId'
        description:
          $ref: '#/components/schemas/TemplateDescription'
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        tags:
          $ref: '#/components/schemas/DynamicTemplateTags'
        sources:
          type: array
          minItems: 1
          description: >-
            Mapping of languages to their corresponding multipart form field
            names
          items:
            $ref: '#/components/schemas/Source'
    CreateMajorVersionMetadata:
      type: object
      required:
        - description
        - default_language
        - sources
        - changelog
      properties:
        description:
          $ref: '#/components/schemas/TemplateDescription'
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        tags:
          $ref: '#/components/schemas/DynamicTemplateTags'
        sources:
          type: array
          minItems: 1
          description: >-
            Mapping of all languages to their corresponding multipart form field
            names to include in the new major 

            version with their sources. If previous existing sources not
            included they will be removed.
          items:
            $ref: '#/components/schemas/Source'
        changelog:
          type: string
          description: Description of changes made in this major version
          example: Added discount field and removed unused languages
    CreateMinorVersionMetadata:
      type: object
      required:
        - changelog
        - sources
      properties:
        description:
          type: string
          description: >-
            Updated description for the new minor version. If not provided,
            previous description is retained.
          example: Plantilla actualizada con soporte para Catalán.
        sources:
          type: array
          description: >-
            Sources to add or update (existing languages not included remain
            unchanged)
          minItems: 1
          items:
            $ref: '#/components/schemas/Source'
        changelog:
          type: string
          description: Description of changes made in this minor version
          example: Added Catalan language support
    CreateDynamicTemplateResponse:
      type: object
      required:
        - external_id
        - description
        - version
        - default_language
        - languages
        - creation_date
      properties:
        external_id:
          $ref: '#/components/schemas/ExternalId'
        description:
          $ref: '#/components/schemas/TemplateDescription'
        version:
          type: string
          example: '1.0'
          description: Template version
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplatesLanguage'
          example:
            - ES
            - EN
          description: Supported languages
        tags:
          $ref: '#/components/schemas/DynamicTemplateTags'
        creation_date:
          type: string
          format: date-time
          example: '2025-08-29T08:50:00Z'
          description: Template creation date
    DynamicTemplateSummary:
      type: object
      required:
        - external_id
        - description
        - version
        - default_language
        - languages
        - creation_date
      properties:
        external_id:
          $ref: '#/components/schemas/ExternalId'
        description:
          $ref: '#/components/schemas/TemplateDescription'
        version:
          type: string
          example: '2.7'
          description: Latest template version
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplatesLanguage'
          example:
            - ES
          description: Supported languages
        creation_date:
          type: string
          format: date-time
          example: '2025-09-22T10:00:00Z'
          description: Template creation date
    GetAllDynamicTemplatesResponse:
      type: object
      required:
        - page
        - page_size
        - templates
      properties:
        page:
          $ref: '#/components/schemas/DynamicTemplatesPage'
        page_size:
          $ref: '#/components/schemas/DynamicTemplatesPageSize'
        templates:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplateSummary'
    Structure:
      type: object
      description: >-
        Complete JSON Schema defining the structure and validation rules for the
        template's data.

        Includes field definitions in 'properties', required fields, and
        conditional rules using 'allOf', 'if/then', 'oneOf'.
      example:
        $schema: 'https://json-schema.org/draft/2020-12/schema'
        type: object
        properties:
          CUSTOMER:
            type: object
            properties:
              DNI:
                type: string
              NAME:
                type: string
              EMAIL:
                type: string
                format: email
              ADDRESS:
                type: object
                properties:
                  CITY:
                    type: string
                  COORDINATES:
                    type: object
                    properties:
                      LATITUDE:
                        type: number
                      LONGITUDE:
                        type: number
            required:
              - dni
              - name
          CONTRACT_DATE:
            type: string
            format: date-time
          TAGS:
            type: array
            items:
              type: string
          PRODUCTS:
            type: array
            items:
              type: object
              properties:
                NAME:
                  type: string
                PRICE:
                  type: number
                QUANTITY:
                  type: integer
              required:
                - NAME
                - PRICE
          TOTAL_AMOUNT:
            type: number
          HAS_DISCOUNT:
            type: boolean
          DISCOUNT_AMOUNT:
            type: number
          PAYMENT_METHOD:
            type: string
            enum:
              - bank_transfer
              - card
              - mobile_payment
          IBAN:
            type: string
          CARD_LAST_DIGITS:
            type: string
          MOBILE_PAYMENT_TYPE:
            type: string
          MOBILE_PHONE:
            type: string
          MOBILE_WALLET_ID:
            type: string
        required:
          - CUSTOMER
          - PRODUCTS
          - TOTAL_AMOUNT
          - PAYMENT_METHOD
        additionalProperties: false
        allOf:
          - if:
              properties:
                HAS_DISCOUNT:
                  const: true
            then:
              required:
                - DISCOUNT_AMOUNT
          - if:
              properties:
                PAYMENT_METHOD:
                  const: BANK_TRANSFER
            then:
              required:
                - IBAN
          - if:
              properties:
                PAYMENT_METHOD:
                  const: card
            then:
              required:
                - CARD_LAST_DIGITS
          - if:
              properties:
                PAYMENT_METHOD:
                  const: mobile_payment
            then:
              required:
                - MOBILE_PAYMENT_TYPE
              oneOf:
                - properties:
                    MOBILE_PAYMENT_TYPE:
                      const: bizum
                  required:
                    - MOBILE_PHONE
                - properties:
                    MOBILE_PAYMENT_TYPE:
                      const: wallet
                  required:
                    - MOBILE_WALLET_ID
    TemplateSource:
      type: object
      required:
        - language
        - template_url
        - editor_config_url
        - engine_version
      properties:
        language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        template_url:
          type: string
          format: uri
          description: URL to access the HTML template file
          example: 'https://storage.googleapis.com/.../v1.1_es.html'
        editor_config_url:
          type: string
          format: uri
          description: URL to access the JSON editor configuration file
          example: 'https://storage.googleapis.com/.../v1.1_es.json'
        engine_version:
          type: string
          description: >-
            Semantic version of the rendering engine to use for this source.
            Contains major and minor version, without patch.
          example: '2.0'
    DynamicTemplateVersion:
      type: object
      required:
        - external_id
        - description
        - version
        - default_language
        - languages
        - tags
        - creation_date
        - structure
        - sources
      properties:
        external_id:
          $ref: '#/components/schemas/ExternalId'
        description:
          $ref: '#/components/schemas/TemplateDescription'
        version:
          type: string
          example: '1.1'
          description: Template version
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplatesLanguage'
          minItems: 1
          example:
            - ES
            - EN
          description: Supported languages
        tags:
          $ref: '#/components/schemas/DynamicTemplateTags'
        creation_date:
          type: string
          format: date-time
          example: '2025-09-22T10:00:00Z'
          description: Version creation date
        structure:
          $ref: '#/components/schemas/Structure'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/TemplateSource'
          minItems: 1
          description: Multi-language template artifacts with URLs
    GetDynamicTemplateVersionsResponse:
      type: object
      required:
        - templates
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplateVersion'
          minItems: 1
    DynamicTemplateDetails:
      type: object
      required:
        - external_id
        - description
        - version
        - default_language
        - languages
        - tags
        - creation_date
        - structure
        - sources
      properties:
        external_id:
          $ref: '#/components/schemas/ExternalId'
        description:
          $ref: '#/components/schemas/TemplateDescription'
        version:
          type: string
          example: '1.1'
          description: Current template version
        default_language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTemplatesLanguage'
          example:
            - ES
            - EN
          description: Supported languages
        tags:
          $ref: '#/components/schemas/DynamicTemplateTags'
        creation_date:
          type: string
          format: date-time
          example: '2025-09-22T10:00:00Z'
          description: Version creation date
        structure:
          $ref: '#/components/schemas/Structure'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/TemplateSource'
    ChangelogEntry:
      type: object
      required:
        - to_version
        - on_date
        - subject
      properties:
        from_version:
          type: string
          description: Previous version before the change. Not informed if initial version.
          example: '1.1'
        to_version:
          type: string
          description: Final version after the change
          example: '2.0'
        on_date:
          type: string
          format: date-time
          example: '2025-10-01T15:00:00Z'
          description: Date when the change was made
        changelog:
          type: string
          description: Description of the changes made. Not informed if initial version.
          example: >-
            Versión Mayor: Añadido campo de descuento y se elimina el soporte
            para idiomas no usados.
        subject:
          type: string
          description: User who made the change
          example: myuser@example
    DynamicTemplateChangelogResponse:
      type: object
      required:
        - changelog_history
      properties:
        changelog_history:
          type: array
          items:
            $ref: '#/components/schemas/ChangelogEntry'
          minItems: 1
    CreateFillProcessRequest:
      type: object
      required:
        - language
        - document
        - fields_values
      properties:
        language:
          $ref: '#/components/schemas/DynamicTemplatesLanguage'
        document:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name for the generated document
              example: personal_contract_2025_001
              minLength: 1
              maxLength: 255
            tags:
              type: array
              items:
                type: string
              description: >-
                Tags to categorize the document. Maximum 4 user-defined tags
                allowed. The system automatically adds 1 additional tag with
                format '{templateExternalId}-v{templateVersion}' (e.g.,
                'invoice-template-v1.0'). All tags (both user-provided and
                system-generated) are normalized according to the mas-documents
                API rules before being persisted.
              example:
                - DRAFT
                - RETAIL
              default: []
              maxItems: 4
        fields_values:
          type: object
          description: >-
            Field values that will be used to fill the template. Must conform to
            the template's JSON schema. The entire payload is validated against
            the template's JSON schema definition.
          additionalProperties: true
          example:
            customer:
              name: Juan Pérez
              id: 12345678Z
            products:
              - name: Fibra 1Gb
                price: 20
              - name: Móvil Ilimitado
                price: 15
            total_amount: 35
        fill_priority:
          type: string
          default: low
          description: 'Processing priority for the fill request. Possible values: low, high'
    CreateFillProcessResponse:
      type: object
      required:
        - fill_process_id
      additionalProperties: false
      properties:
        fill_process_id:
          $ref: '#/components/schemas/FillProcessId'
    FillProcessResponse:
      type: object
      required:
        - fill_process_id
        - status
        - creation_date
        - template
      properties:
        fill_process_id:
          $ref: '#/components/schemas/FillProcessId'
        status:
          type: string
          example: COMPLETED
          description: >-
            Current status of the fill process. Possible values: CREATED,
            PROCESSING, COMPLETED, FAILED
        filled_document_id:
          type: string
          example: 4833979c-e045-46a9-9b1e-412d19294237
          description: >-
            UUID of the generated document. Present only when status is
            COMPLETED
        creation_date:
          type: string
          format: date-time
          example: '2025-11-18T09:35:00Z'
          description: Timestamp when the fill process was created
        finish_date:
          type: string
          format: date-time
          example: '2025-11-18T09:35:15Z'
          description: >-
            Timestamp when processing finished. Present only when status is
            COMPLETED or FAILED
        template:
          $ref: '#/components/schemas/FillProcessTemplateVersion'
        error:
          $ref: '#/components/schemas/FillProcessError'
    FillProcessTemplateVersion:
      type: object
      required:
        - external_id
        - major_version
        - minor_version
      properties:
        external_id:
          type: string
          example: telco_services
          description: ID of the template of this fill process.
        major_version:
          type: integer
          example: 1
          minimum: 1
          description: Major version of the template.
        minor_version:
          type: integer
          minimum: 0
          example: 2
          description: Minor version of the template.
    FillProcessError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Template variable 'customerName' missing in payload.
          description: Human-readable error message
    CreateSignProcessResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: >-
            uuid that identifies a digital sign process, referenced on the
            endpoints as sign_process_id
          example: 7902cd2d-80f4-4766-a3e9-a1760e0df9bd
    CreateSignProcessRequest:
      type: object
      required:
        - signers
        - sign
        - identification
      properties:
        signers:
          type: array
          items:
            $ref: '#/components/schemas/SignerData'
        sign:
          $ref: '#/components/schemas/SignRequest'
        identification:
          $ref: '#/components/schemas/IdentificationRequest'
        expires_in:
          description: >-
            Minimum 15 minutes. Default to 30 days. Max 30 days. Validity
            duration time (ISO-8601 format) from now.
          type: string
          example: P7D
    CancelSignProcessRequest:
      type: object
      required:
        - reason
      properties:
        reason:
          type: string
          description: reason for cancellation of the digital signature
    BiometricSignRequest:
      type: object
      required:
        - biometric_data
        - signature_image
      properties:
        biometric_data:
          type: string
          description: >-
            biometric data extracted from the signatory's handwritten signature.
            (Max allowed length 300kb)
        signature_image:
          type: string
          description: base64 encoded image of the signature. (Max allowed length 500kb)
    GetSignProcessResponse:
      type: object
      required:
        - signatures
        - sign_type
        - status
        - creation_date
        - modification_date
      properties:
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/Signatures'
        status:
          $ref: '#/components/schemas/SignProcessStatus'
        sign_type:
          $ref: '#/components/schemas/SignType'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        creation_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        certificate_id:
          type: string
          example: 23f65996-95e6-4fac-b4c2-f8d93f162cc9
          description: Document id of the sign process certificate
    GetSignResponse:
      type: object
      required:
        - signer
        - signable_documents
        - status
        - modification_date
        - creation_date
      properties:
        signer:
          $ref: '#/components/schemas/SignerPartial'
        preview_documents:
          $ref: '#/components/schemas/DownloadableDocuments'
        signable_documents:
          $ref: '#/components/schemas/DownloadableDocuments'
        signed_documents:
          $ref: '#/components/schemas/DownloadableDocuments'
        status:
          $ref: '#/components/schemas/SignProcessStatus'
        identification:
          $ref: '#/components/schemas/SignIdentificationInfo'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-21T17:32:28Z'
        creation_date:
          type: string
          format: date-time
          example: '2023-04-21T17:32:28Z'
    Signatures:
      type: object
      required:
        - alias
        - name
        - last_name
        - language
        - document_number
        - sign
      properties:
        alias:
          type: string
          example: signer_1
          description: >-
            alias has to be a unique value within the signing process and cannot
            overlap with other signers
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Williams Smith
        language:
          $ref: '#/components/schemas/language'
        document_number:
          type: string
          description: >-
            signer personal number that customers agent will use to
            identification
          example: 12345678A
        sign:
          $ref: '#/components/schemas/SignatureInfo'
        identification:
          $ref: '#/components/schemas/SignIdentificationInfo'
    SignerPartial:
      type: object
      required:
        - alias
        - name
        - last_name
        - document_number
        - language
      properties:
        alias:
          type: string
          example: signer_1
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        document_number:
          type: string
          example: 25478547L
        language:
          $ref: '#/components/schemas/language'
    SignerData:
      type: object
      required:
        - alias
        - name
        - last_name
        - identity_document
        - email
        - msisdn
        - language
      properties:
        alias:
          type: string
          example: signer_1
          description: >-
            alias has to be a unique value within the signing process and cannot
            overlap with other signers
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          type: object
          required:
            - document_number
            - document_type
          properties:
            document_number:
              type: string
              description: >-
                signer personal number that customers agent will use to
                identification
              example: 12345678A
            document_type:
              type: string
              description: |-
                type of the actor document number
                Allowed values: 'NIF', 'NIE', 'PASSPORT'
              example: NIF
        email:
          type: string
          example: example@email.com
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        language:
          $ref: '#/components/schemas/language'
        identification:
          oneOf:
            - $ref: '#/components/schemas/OtpIdentificationOptions'
            - $ref: '#/components/schemas/AgentIdentificationOptions'
    language:
      type: string
      description: >-
        Languages available to configure operation

        Not all values are available to all organizations.

        If language text it is not defined, a default language text will be
        provided (by default `ES`).

        Locale defined lists:

        * `ES` - Spanish language

        * `EN` - English language

        * `EU` - Basque language

        * `GL` - Galician language

        * `CA` - Catalan language

        * 'UNDEFINED' - Use default language
      example: ES
    Msisdn:
      type: object
      required:
        - country_code
        - phone_number
      properties:
        phone_number:
          type: string
          description: Phone number of the signatory that we will use to contact us
          example: 6123456789
        country_code:
          type: string
          description: country code of the phone number. Numeric code ISO 3166-1
          example: '34'
    DocumentToSign:
      type: object
      required:
        - id
        - owner
        - sign_fields
      properties:
        id:
          type: string
          example: 0a394423-6f6d-4295-8ce7-c0bd70881836
        owner:
          type: string
          example: '2357893'
          description: The string id related with the document owner.
        sign_fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldsBySigner'
    FieldsBySigner:
      type: object
      required:
        - signer
        - fields
      properties:
        signer:
          type: string
          example: signer_1
        fields:
          type: array
          items:
            type: string
            example: SIGNATURE_CUSTOMER
    SignIdentificationInfo:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          example: b3041b0c-95fe-459c-8df3-bdea4a83233a
          description: identification process id of this signer
        type:
          $ref: '#/components/schemas/SignIdentificationType'
    IdentificationRequest:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/SignIdentificationType'
    SignRequest:
      type: object
      required:
        - type
        - documents
      properties:
        type:
          $ref: '#/components/schemas/SignType'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentToSign'
        preview_documents:
          type: array
          items:
            type: string
            example: 827d7367-8ff4-4748-970e-009680a87813
    DownloadableDocuments:
      type: array
      items:
        type: object
        required:
          - name
          - url
        properties:
          name:
            type: string
            example: Document_Name
          url:
            type: string
            format: uri
            example: >-
              https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
            description: >-
              Temporary signed URL fully accessible without authentication or
              authorisation.
      description: >-
        Temporary signed URL fully accessible without authentication or
        authorisation, plus the document name, for the signed documents.
    SignatureInfo:
      type: object
      required:
        - id
        - status
        - modification_date
      properties:
        id:
          type: string
          example: 0b9bbe95-f080-4317-b371-1f9ae0b9bf4f
        status:
          $ref: '#/components/schemas/SignStatus'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-21T17:32:28Z'
    SignStatus:
      type: string
      example: CLOSED
      description: >-
        A signature can be in one of the following statuses:

        - CREATED: Signature process has been started.

        - IDENTIFIED: Signers have been identified.

        - PREVIEWED: Documents have been previewed. (This status is OPTIONAL.)

        - SIGNED: Signature has been collected, but the process is pending due
        to the asynchronous document generation process (This status persists
        while there are other pending signatures).

        - SUCCEEDED: Signature has been stamped on the document.

        - FAILED: Contract signature has failed due to an error along the
        process.
    SignProcessStatus:
      type: string
      example: CREATED
      description: >-
        Digital sign processes management. 

        A digital sign process can be on one of the following statuses:

        - CREATED: New process has been created.

        - SIGNED: Process has been successfully finished. All signs have to be
        on SUCCEEDED status. See Signature signs.

        - FAILED: Process has failed. Signature is in an error state. See
        signature statuses.

        - CANCELLED: Process has been cancelled. A process cannot be cancelled
        if it is already in SIGNED, EXPIRED or FAILED status.

        - EXPIRED: Process has exceeded the maximum time waiting for signature

        - CERTIFIED: Signatures and identifications have been certified in a PDF
        document. Certificate_id has been associated with the process.
    SignType:
      type: string
      example: BIOMETRIC
      description: |-
        Sign processes type:
        - SIMPLE: Simple Sign
        - BIOMETRIC: Biometric Sign
    SignIdentificationType:
      type: string
      example: AGENT
      description: |-
        Sign identification types:
        - OTP: Identification by One Time Password (online)
        - AGENT: Identification by a trusted agent (on-site)
    SecurizeSign:
      type: object
      description: securize payload schema to sign
      required:
        - sign_process_id
      properties:
        sign_process_id:
          type: string
    SecurizeSignResponse:
      type: object
      description: >-
        valid web_component token with necessary authz data to operate signs
        steps
      required:
        - web_component_token
      properties:
        web_component_token:
          type: string
    SignTwoFactorType:
      type: string
      description: |-
        Two factor type to validate actor identity. Possible values:
             * `DOCUMENT_NUMBER`: value defined in actor's document number field
             * `EMAIL`: value defined in actor's email field
             * `PERSONAL_DOCUMENT_IMAGE`: Image of the document number (back and front) defined in actor's document number field
      example: EMAIL
    OtpIdentificationOptions:
      type: object
      required:
        - two_factor_type
      properties:
        two_factor_type:
          $ref: '#/components/schemas/SignTwoFactorType'
    AgentIdentificationOptions:
      type: object
      required:
        - personal_document_image
      properties:
        personal_document_image:
          type: boolean
          description: >-
            Flag to indicate if the agent needs to take a picture of the actor
            personal document.

            If true, the agent will take a picture of the document.

            If false, or null, the agent will not take a picture of the
            document.
          example: true
    ConfigurationPatchRequest:
      type: object
      properties:
        landing_url:
          $ref: '#/components/schemas/LandingUrl'
        expiration_duration:
          $ref: '#/components/schemas/ExpirationDuration'
        channels:
          $ref: '#/components/schemas/NotificationChannels'
        content:
          $ref: '#/components/schemas/SignCertificateContent'
        sign_certificate_password:
          $ref: '#/components/schemas/SignCertificatePassword'
        notification_email:
          $ref: '#/components/schemas/NotificationEmail'
        identification_config:
          type: string
          description: JSON array of scoring provider configurations per sign type
    SignConfiguration:
      type: object
      properties:
        landing_url:
          type: string
          description: Sign process url
          example: www.masmovil.com
        expiration_duration:
          type: string
          description: >-
            Validity duration time (ISO-8601 format) of any sign process for the
            tenant.
          example: P7D
        channels:
          type: array
          description: >-
            Channels to send notifications. Possible values: SMS, EMAIL or
            WHATSAPP
          items:
            $ref: '#/components/schemas/Channel'
          example:
            - SMS
            - EMAIL
            - WHATSAPP
        certificate:
          $ref: '#/components/schemas/SignCertificateMetadata'
        notification_email:
          $ref: '#/components/schemas/NotificationEmail'
        identification_config:
          $ref: '#/components/schemas/IdentificationConfig'
    SignCertificateMetadata:
      type: object
      properties:
        expiration_date:
          type: string
          description: Date when certificate expires
          format: date-time
          example: '2025-04-20T11:43:13Z'
        common_name:
          type: string
          description: >-
            The common name (CN) of the certificate subject. Typically
            represents the entity or domain name associated  with the
            certificate.
          example: Mas_Orange_CA
        organization:
          type: string
          description: >-
            The organization (O) associated with the certificate. Usually
            represents the company or entity that owns the  certificate.
          example: MasOrange
        organizational_unit:
          type: string
          description: >-
            The organizational unit (OU) within the organization that is
            associated with the certificate. Often used to  indicate a
            department or division.
          example: MasOrangeCAUnit
        issuer:
          type: string
          description: >-
            The issuer of the certificate. This is the common name (CN) of the
            certificate authority (CA) that signed  and issued the certificate.
          example: Mas_Orange_Root_CA
    CreateSignConfigurationRequest:
      type: object
      required:
        - landing_url
        - expiration_duration
        - channels
        - content
        - sign_certificate_password
        - notification_email
      properties:
        landing_url:
          type: string
          description: Sign process url
          example: www.masmovil.com
        expiration_duration:
          type: string
          description: >-
            Validity duration time (ISO-8601 format) of any sign process for the
            tenant.
          example: P7D
        channels:
          type: array
          description: >-
            Channels to send notifications. Possible values: SMS, EMAIL or
            WHATSAPP
          items:
            $ref: '#/components/schemas/Channel'
          example:
            - SMS
            - EMAIL
            - WHATSAPP
        content:
          type: string
          format: binary
          description: The PKCS#12 (.p12) certificate file
        sign_certificate_password:
          $ref: '#/components/schemas/SignCertificatePassword'
        notification_email:
          $ref: '#/components/schemas/NotificationEmail'
        identification_config:
          $ref: '#/components/schemas/IdentificationConfig'
    UpdateSignConfigurationRequest:
      type: object
      properties:
        landing_url:
          type: string
          description: Sign process url
          example: www.masmovil.com
        expiration_duration:
          type: string
          description: >-
            Validity duration time (ISO-8601 format) of any sign process for the
            tenant.
          example: P7D
        channels:
          type: array
          description: >-
            Channels to send notifications. Possible values: SMS, EMAIL or
            WHATSAPP
          items:
            $ref: '#/components/schemas/Channel'
          example:
            - SMS
            - EMAIL
            - WHATSAPP
        content:
          type: string
          format: binary
          description: The PKCS#12 (.p12) certificate file
        sign_certificate_password:
          $ref: '#/components/schemas/SignCertificatePassword'
        notification_email:
          $ref: '#/components/schemas/NotificationEmail'
        identification_config:
          $ref: '#/components/schemas/IdentificationConfig'
    SignCertificatePassword:
      type: string
      description: Password for the PKCS#12 certificate
      example: Passw0rd
    Channel:
      type: string
      description: 'Channel to send notifications. Possible values: SMS, EMAIL or WHATSAPP'
      example: SMS
    LandingUrl:
      type: string
      description: Sign process URL
      example: www.masmovil.com
    ExpirationDuration:
      type: string
      description: >-
        Validity duration time (ISO-8601 format) of any sign process for the
        tenant.
      example: P7D
    NotificationChannels:
      type: array
      description: >-
        Channels to send notifications. Possible values: SMS, EMAIL, or
        WHATSAPP.
      items:
        $ref: '#/components/schemas/Channel'
      example:
        - SMS
        - EMAIL
        - WHATSAPP
    SignCertificateContent:
      type: string
      format: binary
      description: The PKCS#12 (.p12) certificate file
    NotificationEmail:
      type: string
      description: Email where the notifications about certificate expiration will be sent
      example: example@email.com
    IdentityDocumentProviderConfig:
      type: object
      properties:
        sign_type:
          type: string
          description: Type of signature
          enum:
            - SIMPLE
            - BIOMETRIC
          example: SIMPLE
        provider_type:
          type: string
          description: Scoring provider type
          enum:
            - INTERNAL
            - EXTERNAL
          example: EXTERNAL
    IdentificationConfig:
      type: object
      properties:
        identity_document:
          type: object
          properties:
            providers:
              type: array
              description: List of provider configurations per sign type
              items:
                $ref: '#/components/schemas/IdentityDocumentProviderConfig'
    TwoFactorValueResponse:
      type: object
      required:
        - two_factor_value
      properties:
        two_factor_value:
          $ref: '#/components/schemas/TwoFactorValue'
    ValidateAgentIdentificationRequest:
      type: object
      required:
        - agent
      properties:
        agent:
          type: string
          example: Jose Luis Garcia
          description: shop agent identifier of who is validating this identification
        evidence:
          $ref: '#/components/schemas/PersonalDocumentImage'
        evidence_metadata:
          $ref: '#/components/schemas/PersonalIdentificationEvidenceMetadata'
    LanguageIdentification:
      type: string
      description: >-
        Languages available to configure operation

        Not all values are available to all organizations.

        If language text it is not defined, a default language text will be
        provided (by default `ES`).

        Locale defined lists:

        * `ES` - Spanish language

        * `EN` - English language

        * `EU` - Basque language

        * `GL` - Galician language

        * `CA` - Catalan language

        * 'UNDEFINED' - Use default language
      example: ES
    ValidateOtpIdentificationRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: challenge code
          example: k4khb9
        two_factor:
          $ref: '#/components/schemas/TwoFactorValue'
    CreateOtpChallengeRequest:
      type: object
      properties:
        two_factor:
          $ref: '#/components/schemas/TwoFactorValueOrImage'
    GetIdentityDocumentIdentificationMetadataResponse:
      type: object
      required:
        - actor
        - state
        - remaining_validation_attempts
        - creation_date
        - modification_date
        - expiration_date
      properties:
        actor:
          $ref: '#/components/schemas/IdentityDocumentIdentificationActor'
        state:
          $ref: '#/components/schemas/IdentificationState'
        remaining_validation_attempts:
          type: integer
          description: Remaining validation attempts
          minimum: 0
          example: 3
        creation_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        expiration_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        scoring_id:
          type: string
          format: uuid
          example: 625fc44b-5b1c-451e-bcc7-276c911f0af8
    GetAgentIdentificationMetadataResponse:
      type: object
      required:
        - actor
        - state
        - creation_date
        - expiration_date
      properties:
        actor:
          $ref: '#/components/schemas/GetAgentIdentificationActorResponse'
        agent_id:
          type: string
          description: Agent which will identify the actor
          example: shop.agente.name@masmovil.com
        creation_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        expiration_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        state:
          $ref: '#/components/schemas/IdentificationState'
    GetAgentIdentificationActorResponse:
      type: object
      required:
        - name
        - last_name
        - document_type
      properties:
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Williams Smith
        language:
          $ref: '#/components/schemas/LanguageIdentification'
        document_type:
          $ref: '#/components/schemas/DocumentType'
    GetOtpIdentificationActorResponse:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: James
        language:
          $ref: '#/components/schemas/LanguageIdentification'
        document_type:
          $ref: '#/components/schemas/DocumentType'
    GetOtpIdentificationMetadataResponse:
      type: object
      required:
        - actor
        - state
        - creation_date
        - modification_date
        - expiration_date
        - remaining_challenges
        - remaining_validation_attempts
      properties:
        actor:
          $ref: '#/components/schemas/GetOtpIdentificationActorResponse'
        creation_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        modification_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        expiration_date:
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        remaining_challenges:
          type: integer
          description: >-
            Remaining challenge codes to request before identification process
            fail.
          minimum: 0
          example: 3
        remaining_validation_attempts:
          type: integer
          description: >-
            Remaining validation attempts of the current challenge code. Null
            when not challenge is requested.
          minimum: 0
          example: 3
        next_challenge_retry:
          description: >-
            Minimum date before request a new challenge code. Null when
            remaining_challenges is zero.
          type: string
          format: date-time
          example: '2023-04-20T11:43:13Z'
        two_factor_type:
          $ref: '#/components/schemas/IdentificationTwoFactorType'
        state:
          $ref: '#/components/schemas/IdentificationState'
    IdentityDocumentIdentificationActorExtended:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/IdentityDocumentIdentificationActor'
        configuration_name:
          type: string
          description: 'Configuration name. Possible values: ["LOW", "MEDIUM", "HIGH"]'
          example: HIGH
        expires_in:
          description: >-
            Default to 30 days. Max 30 days. Validity duration time (ISO-8601
            format) from now.
          type: string
          example: P7D
        scoring:
          type: object
          properties:
            provider:
              type: string
              description: 'Scoring provider to use: Possible values: [INTERNAL, EXTERNAL]'
              example: INTERNAL
    IdentityDocumentIdentificationActor:
      type: object
      properties:
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          type: object
          required:
            - document_number
            - document_type
          properties:
            document_number:
              type: string
              description: >-
                actor personal number that customers agent will use to
                identification
              example: 12345678A
            document_type:
              $ref: '#/components/schemas/IdentityDocumentDocType'
            country:
              type: string
              example: ES
              description: Country/region code in ISO 3166 2-letter code
    IdentificationState:
      type: string
      example: CREATED
      description: >-
        An identification process can be in one of the following statuses:

        - CREATED: Identification process has been started.

        - VALIDATED: Identification has been validated (I.e. OTP challenge has
        been solved or agent approved identification).

        - EXPIRED: Identification process has expired.

        - CANCELLED: Identification process has been cancelled.

        - SUCCEEDED: Actor has been identified successfully and the process has
        been closed.

        - FAILED: Identification process has ended with failure due to an error
        along the process.
    IdentificationTwoFactorType:
      type: string
      description: |-
        Two factor type to validate actor identity. Possible values:
             * `DOCUMENT_NUMBER`: value defined in actor's document number field
             * `EMAIL`: value defined in actor's email field
      example: EMAIL
    PersonalDocumentImage:
      type: string
      description: >-
        Evidence of the actor identified. It should be a personal document
        image. Uploaded in Base64 string format. Image extension should ONLY
        '*.png'
      example: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAABbklEQVR42mNkAAYYgZ
    PersonalIdentificationEvidenceMetadata:
      type: string
      description: >-
        Metadata of apply OCR to Evidence file. It should be in a valid Json
        format.
      example: |-
        { "document_number": "12345678A",
          "document_type": "NIF" }
    TwoFactorValue:
      type: string
      description: >-
        Value used for two factor. Will match a national id, passport number or
        email.
      example: 12345678A
    DocumentType:
      type: string
      description: |-
        type of the actor document number
        Allowed values: 'NIF', 'NIE', 'PASSPORT'
      example: NIF
    TwoFactorValueOrImage:
      type: string
      description: >-
        Value used for two factor. Value depends of two factor type: -
        DOCUMENT_NUMBER: Value must be actor's personal identification id or
        passport number. - EMAIL: Value must be actor's email address.
      example: 12345678A or actor@email.com
    GetChainIdentificationResponse:
      type: object
      required:
        - step_details
        - creation_date
        - modification_date
        - expiry_from_creation
      properties:
        status:
          type: string
          description: |
            Global status of the chained identification process.
            Enum: CREATED, VALIDATED, SUCCEEDED, FAILED, EXPIRED, CANCELLED
          example: CREATED
        step_details:
          type: array
          description: >-
            Array with the status and references of each step in the original
            sequence, in order.
          items:
            $ref: '#/components/schemas/ChainedIdentificationStepDetail'
        creation_date:
          type: string
          format: date-time
          example: '2025-06-03T10:30:00Z'
        modification_date:
          type: string
          format: date-time
          example: '2025-06-03T10:40:15Z'
        expiry_from_creation:
          description: Validity duration (ISO-8601 format) from the time it was created
          type: string
          format: duration
          example: PT15M
        failure_reason:
          type: string
          nullable: true
          description: 'Reason for failure if status is FAILED or EXPIRED, otherwise null.'
          example: null
    ChainedIdentificationStepDetail:
      type: object
      required:
        - type
        - id
        - status
        - modification_date
      properties:
        type:
          type: string
          description: 'Step identification type (e.g. OTP, IDENTITY_DOCUMENT, AGENT)'
          example: OTP
        id:
          type: string
          description: ID of the identification step
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        status:
          type: string
          nullable: true
          description: >
            Current status of the step (CREATED, VALIDATED, FAILED, EXPIRED,
            CANCELLED, SUCCEEDED, UNKNOWN).
          example: VALIDATED
        modification_date:
          type: string
          format: date-time
          description: Last update date of this step's status
          example: '2025-06-03T10:35:00Z'
    IdentityDocumentDocType:
      type: string
      description: |-
        type of the actor document number
        Allowed values: 'IDENTITY_CARD','RESIDENCE_PERMIT', 'PASSPORT'
      example: IDENTITY_CARD
    CreateIdentityDocumentIdentificationRequest:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/IdentificationActorCountry'
        name:
          type: string
          deprecated: true
          example: James
        last_name:
          type: string
          deprecated: true
          example: Smith
        identity_document:
          $ref: '#/components/schemas/IdentificationActorIdentityDocument'
        configuration_name:
          type: string
          description: 'Configuration name. Possible values: ["LOW", "MEDIUM", "HIGH"]'
          example: HIGH
        expires_in:
          description: >-
            Default to 30 days. Max 30 days. Validity duration time (ISO-8601
            format) from now.
          type: string
          example: P7D
        scoring:
          type: object
          properties:
            provider:
              type: string
              description: 'Scoring provider to use: Possible values: [INTERNAL, EXTERNAL]'
              example: INTERNAL
    CreateAgentIdentificationRequest:
      type: object
      required:
        - actor
        - expires_in
      properties:
        actor:
          $ref: '#/components/schemas/AgentIdentificationActor'
        expires_in:
          description: >-
            Minimum 1 minute. Max 30 days. Validity duration time (ISO-8601
            format) from now.
          type: string
          example: P7D
    CreateOtpIdentificationRequest:
      type: object
      required:
        - actor
        - expires_in
        - channel
      properties:
        actor:
          $ref: '#/components/schemas/IdentificationActor'
        expires_in:
          description: >-
            Default to 30 days. Max 30 days. Validity duration time (ISO-8601
            format) from now.
          type: string
          example: P7D
        two_factor_type:
          $ref: '#/components/schemas/IdentificationAdminTwoFactorType'
        channel:
          $ref: '#/components/schemas/CommunicationChannel'
    CommunicationChannel:
      type: object
      required:
        - type
        - external
      properties:
        type:
          description: >-
            Channel which will be used to send the OTP to complete the
            identification. Possible values: SMS or EMAIL
          type: string
          example: SMS
        external:
          description: >-
            Identification communications to send the OTP will be sent through
            third-party gateway instead of MasOrange one
          type: boolean
          default: 'false'
          example: 'true'
    AgentIdentificationActor:
      allOf:
        - $ref: '#/components/schemas/IdentificationActor'
        - type: object
          required:
            - identity_document
          description: >-
            Actor data for agent identification. Identity document is mandatory
            for agent identification.
    IdentificationActor:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          $ref: '#/components/schemas/IdentificationActorIdentityDocument'
        email:
          $ref: '#/components/schemas/Email'
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        language:
          $ref: '#/components/schemas/IdentificationAdminLanguage'
    IdentificationActorCountry:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          $ref: '#/components/schemas/IdentityDocumentCountry'
        email:
          $ref: '#/components/schemas/Email'
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        language:
          $ref: '#/components/schemas/IdentificationAdminLanguage'
    IdentificationActorChain:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          $ref: '#/components/schemas/IdentityDocument'
        email:
          $ref: '#/components/schemas/Email'
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        language:
          $ref: '#/components/schemas/IdentificationAdminLanguage'
    IdentificationAdminLanguage:
      type: string
      description: >-
        Languages available to configure operation

        Not all values are available to all organizations.

        If language text it is not defined, a default language text will be
        provided (by default `ES`).

        Locale defined lists:

        * `ES` - Spanish language

        * `EN` - English language

        * `EU` - Basque language

        * `GL` - Galician language

        * `CA` - Catalan language

        * 'UNDEFINED' - Use default language
      example: ES
    IdentificationAdminTwoFactorType:
      type: string
      description: |-
        Two factor type to validate actor identity. Possible values:
            * `DOCUMENT_NUMBER`: value defined in actor's document number field
            * `EMAIL`: value defined in actor's email field
      example: DOCUMENT_NUMBER
    CreateIdentityDocumentIdentificationResponse:
      type: object
      required:
        - id
        - scoring_id
      properties:
        id:
          type: string
          description: uuid that identifies an identity document identification
          example: 7902cd2d-80f4-4766-a3e9-a1760e0df9bd
        scoring_id:
          type: string
          description: Scoring id
          example: 8902cd2d-80f4-4766-a3e9-a1760e0df9bd
    CreateAgentIdentificationResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: >-
            uuid that identifies an agent identification, referenced on the
            endpoints as admin_identification_id
          example: 7902cd2d-80f4-4766-a3e9-a1760e0df9bd
    CreateOtpIdentificationResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: >-
            uuid that identifies an otp identification, referenced on the
            endpoints as admin_identification_id
          example: 7902cd2d-80f4-4766-a3e9-a1760e0df9bd
    CancelIdentificationRequest:
      type: object
      properties:
        reason:
          type: string
          example: >-
            The client does not want to continue with the identification
            process.
          description: The reason why the process is going to be cancelled.
    CreateChainIdentificationRequest:
      type: object
      required:
        - actor
        - expires_in
        - sequence
      properties:
        actor:
          $ref: '#/components/schemas/IdentificationActorChain'
        expires_in:
          type: string
          description: Validity duration time (ISO-8601 format) from now.
          example: PT15M
        sequence:
          type: array
          minItems: 1
          maxItems: 10
          description: >-
            Ordered array defining the identification steps (each step should be
            unique).
          items:
            $ref: '#/components/schemas/ChainIdentificationStep'
          example:
            - identification_type: OTP
              otp_step:
                two_factor_type: DOCUMENT_NUMBER
                channel:
                  type: SMS
                  external: false
            - identification_type: AGENT
            - identification_type: IDENTITY_DOCUMENT
              identity_document_step:
                provider_type: INTERNAL
    ChainOtpStepConfiguration:
      type: object
      required:
        - two_factor_type
        - channel
      properties:
        two_factor_type:
          $ref: '#/components/schemas/IdentificationAdminTwoFactorType'
        channel:
          $ref: '#/components/schemas/CommunicationChannel'
    ChainAgentStepConfiguration:
      type: object
    ChainIdentityDocumentStepConfiguration:
      type: object
      required:
        - provider_type
      properties:
        provider_type:
          type: string
          description: Provider type for identity document step.
          example: INTERNAL
    CreateChainIdentificationResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: uuid that identifies a chain identification
          example: cadd9e8e-7bb5-4f73-9a1a-124f8a8b0c1d
    IdentificationActorIdentityDocument:
      type: object
      required:
        - document_number
        - document_type
      properties:
        document_number:
          $ref: '#/components/schemas/DocumentNumber'
        document_type:
          $ref: '#/components/schemas/DocumentType'
        country:
          $ref: '#/components/schemas/CountryAdmin'
    IdentityDocument:
      type: object
      required:
        - document_number
        - document_type
      properties:
        document_number:
          $ref: '#/components/schemas/DocumentNumber'
        document_type:
          $ref: '#/components/schemas/IdentityDocumentTypeAdmin'
        country:
          $ref: '#/components/schemas/CountryAdmin'
    IdentityDocumentCountry:
      type: object
      required:
        - document_number
        - document_type
        - country
      properties:
        document_number:
          $ref: '#/components/schemas/DocumentNumber'
        document_type:
          $ref: '#/components/schemas/IdentityDocumentTypeAdmin'
        country:
          $ref: '#/components/schemas/CountryAdmin'
    Email:
      type: string
      format: email
      example: example@email.com
      description: Email address of the actor
    DocumentNumber:
      type: string
      description: actor personal number that customers agent will use to identification
      example: 12345678A
    IdentityDocumentTypeAdmin:
      type: string
      description: |-
        type of the actor document number
        Allowed values: 'IDENTITY_CARD','RESIDENCE_PERMIT', 'PASSPORT'
      example: IDENTITY_CARD
    CountryAdmin:
      type: string
      example: ES
      description: Country/region code in ISO 3166 2-letter code
    IdentificationType:
      type: string
      description: Type of identification to be used in the chain.
      enum:
        - OTP
        - AGENT
        - IDENTITY_DOCUMENT
      example: OTP
    ChainIdentificationStep:
      type: object
      required:
        - identification_type
      properties:
        identification_type:
          $ref: '#/components/schemas/IdentificationType'
        otp_step:
          $ref: '#/components/schemas/ChainOtpStepConfiguration'
        agent_step:
          $ref: '#/components/schemas/ChainAgentStepConfiguration'
        identity_document_step:
          $ref: '#/components/schemas/ChainIdentityDocumentStepConfiguration'
      description: >-
        Step-specific configuration. The schema used must match the
        identification_type.
    ContractsLanguage:
      type: string
      description: |-
        Templates languages allowed to generate contract
        Allowed values: ES, EN, EU, GL, CA, DE, UNDEFINED
    ContractsCondition:
      type: string
      description: >-
        Tuple FLAG:VALUE (flag and expected value) that will evaluated to know
        if this template section have to be filled
      example: 'GDPR:YES'
    ContractsTag:
      type: string
      description: >-
        Free values (user-defined) to tag document filled. These values are
        normalized following the next rules:

        - All tags will be converted to lowercase

        - All whitespaces will be removed

        - Empty or blank tags are not allowed

        - Tags matching reserved words (null, undefined or nan) are not allowed
      example: DRAFT
    DocumentId:
      type: string
      format: uuid
      description: Unique identifier of a document stored in mas-documents
      example: d290f1ee-6c54-4b01-90e6-d701748f0851
    ContractId:
      type: string
      format: uuid
      description: Unique identifier of a contract
      example: 310484e7-40ec-4b4b-8731-3e7ed29f7ef5
    ContractWithoutOwner:
      type: object
      required:
        - contract_id
      properties:
        contract_id:
          $ref: '#/components/schemas/ContractId'
    Signer:
      type: object
      required:
        - alias
        - name
        - last_name
        - identity_document
        - email
        - msisdn
        - language
      properties:
        alias:
          type: string
          example: signer_1
          description: >-
            alias has to be a unique value within the signing process and cannot
            overlap with other signers
        name:
          type: string
          example: James
        last_name:
          type: string
          example: Smith
        identity_document:
          type: object
          required:
            - document_number
            - document_type
          properties:
            document_number:
              type: string
              description: >-
                signer personal number that customers agent will use to
                identification
              example: 12345678A
            document_type:
              type: string
              description: |-
                type of the actor document number
                Allowed values: 'NIF', 'NIE', 'PASSPORT'
              example: NIF
        email:
          type: string
          example: example@email.com
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        language:
          $ref: '#/components/schemas/language'
        identification_options:
          type: object
          description: >-
            additional options to configure signer identification on sign
            process
          properties:
            personal_document_evidence:
              $ref: '#/components/schemas/PersonalDocumentEvidence'
    PersonalDocumentEvidence:
      type: boolean
      description: >-
        Flag to indicate if the signer has to provide a personal document
        evidence when is identificated to sign the contract
      example: true
    ContractValues:
      type: object
      required:
        - name
        - value
      description: Tuple representing a field to be filled with a value
      properties:
        name:
          description: contract field name to be filled
          type: string
        value:
          description: contract field value to be filled
          type: string
    ChangeContractOwnerRequest:
      type: object
      required:
        - new_owner
      properties:
        new_owner:
          type: string
          example: subsCrIptIon8172241
          description: New contract owner
    CreateFilledContractRequest:
      type: object
      required:
        - template_external_id
        - template_version
        - language
        - fields_values
      properties:
        template_external_id:
          type: string
          example: telco_services
          description: Template external id unique identifier
        template_version:
          type: integer
          minimum: 1
          maximum: 32767
          example: '1'
          description: version of the template to be updated
        language:
          $ref: '#/components/schemas/ContractsLanguage'
        flags_conditions:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/ContractsCondition'
          description: >-
            list of conditions which trigger specific sections of the template
            to be filled
        fields_values:
          type: array
          items:
            $ref: '#/components/schemas/ContractValues'
          description: >-
            template variables whose values will be printed in the filled
            template
        name:
          type: string
          description: >-
            Name of the document filled (without spaces). The document is
            renamed with this value.
          example: personal_contract
        tags:
          type: array
          description: >-
            Free values (user-defined) to tag document. These values are
            normalized following the next rules:

            - All tags will be converted to lowercase

            - All whitespaces will be removed

            - Empty or blank tags are not allowed

            - Tags matching reserved words (null, undefined or nan) are not
            allowed
          maxItems: 5
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ContractsTag'
          example:
            - Draft
            - CONTRACT
            - v1.0
    SignContractsRequest:
      type: object
      required:
        - sign_type
        - signers
        - contracts
      properties:
        sign_type:
          type: string
          description: >-
            type of the sign process in which contracts are going to be signed.
            values: 'ONSITE', 'ONLINE'
          example: ONLINE
        signers:
          type: array
          items:
            $ref: '#/components/schemas/Signer'
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/ContractWithoutOwner'
          description: List of contracts to be signed
        additional_options:
          $ref: '#/components/schemas/SignContractAdditionalOptions'
    GetContractResponse:
      type: object
      properties:
        signed_document_id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: signed document unique identifier
        filled_document_id:
          type: string
          format: uuid
          example: 8d104722-610b-4d7c-ba89-0dd825442d88
          description: filled document unique identifier
        sign_process_id:
          type: string
          format: uuid
          example: d2d3b2d0-cc4e-4280-b967-90edee0aB3d2
          description: digital process unique identifier in which contract was signed
    CreateFilledContractResponse:
      type: object
      required:
        - contract_id
        - document_id
      properties:
        contract_id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Contract unique identifier
        document_id:
          type: string
          format: uuid
          example: 8d104722-610b-4d7c-ba89-0dd825442d88
          description: filled document unique identifier
    ChangeContractOwnerResponse:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          example: subscription8172241
          description: Successfully assigned new contract owner
    SignContractsResponse:
      type: object
      required:
        - sign_process_id
      properties:
        sign_process_id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: >-
            Digital sign process unique identifier where contracts will be
            signed
    SignContractAdditionalOptions:
      type: object
      description: additional options to configure on contracts sign process
      properties:
        preview_documents:
          type: array
          description: list of public documents that will be previewed on sign process
          items:
            $ref: '#/components/schemas/DocumentId'
    DelegateIdentityDocumentResponse:
      type: object
      description: >-
        Contains the external provider’s delegation details after handing off a
        scoring request.
      properties:
        provider_id:
          type: string
          description: >-
            The unique identifier assigned by the external provider for this
            delegated scoring request.
          example: cbd2e693-d71a-4cee-8313-1972acc0394d
        access_token:
          type: string
          description: Token granting access to the provider’s scoring endpoint.
          example: access-token
        provider:
          $ref: '#/components/schemas/Provider'
    DelegateScoringProviderConfiguration:
      type: object
      properties:
        provider_config:
          type: string
          description: Provider-specific configuration json content.
        retry_reason:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Optional reason for retrying the delegate request. Used exclusively
            for retries to capture the cancellation reason from the previous
            attempt (typically the error returned by the provider to the
            frontend). Ignored without error if sent on the first call when no
            previous attempt exists.
    ScoringAttemptsResponse:
      type: object
      description: >-
        Contains the list of scoring attempts for an identity document scoring
        session.
      properties:
        attempts:
          type: array
          description: List of scoring attempts ordered by attempt number.
          items:
            $ref: '#/components/schemas/ScoringAttemptItem'
    ScoringAttemptItem:
      type: object
      description: Details of a single scoring attempt within a scoring session.
      properties:
        attempt_number:
          type: integer
          description: >-
            Sequential number of this attempt within the scoring session
            (1-based).
          example: 1
        creation_date:
          type: string
          format: date-time
          description: The timestamp when this scoring attempt was created.
          example: '2024-01-01T10:00:00Z'
        provider_id:
          type: string
          nullable: true
          description: >-
            The unique identifier assigned by the external provider for this
            scoring attempt.
          example: cbd2e693-d71a-4cee-8313-1972acc0394d
        score_result:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ScoreResult'
          description: >-
            Scoring results for this attempt, or null if the attempt failed
            before scoring.
        fail_reason:
          type: string
          nullable: true
          description: Reason for failure if this attempt did not complete successfully.
          example: PROVIDER_TIMEOUT
        captures:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DocumentCaptures'
          description: >-
            URIs of the document images used in this attempt, or null if no
            images were captured.
    IdentityDocumentScoring:
      type: object
      description: Details and results of the identity document verification process.
      properties:
        creation_date:
          type: string
          format: date-time
          description: Exact UTC timestamp when this scoring session was first created.
          example: '2023-04-20T11:43:13Z'
        modification_date:
          type: string
          format: date-time
          description: Exact UTC timestamp of the last update to this scoring session.
          example: '2023-04-20T12:05:27Z'
        expiration_date:
          type: string
          format: date-time
          description: >-
            UTC timestamp after which this scoring session can no longer accept
            new submissions or updates.
          example: '2023-05-20T11:43:13Z'
        total_score_attempts:
          type: integer
          description: >-
            Maximum number of image submissions allowed before this session is
            automatically locked.
          example: 15
        remaining_score_attempts:
          type: integer
          description: >-
            Remaining number of additional image submissions allowed before this
            session is automatically locked.
          example: 15
        remaining_delegate_attempts:
          type: integer
          deprecated: true
          description: >-
            Remaining number of additional delegate calls allowed before this
            session is automatically locked. This field is deprecated: use the
            'remaining_score_attempts' field instead, which is now the only
            valid counter.
          example: 15
        state:
          type: string
          description: |-
            Current lifecycle state of the scoring session:
              • CREATED – Initialized but no images submitted yet.  
              • SCORED – Images submitted and initial checks run.  
              • SUCCEEDED – All verification checks passed.  
              • FAILED – One or more verification checks failed.  
              • EXPIRED – Session expired before completion.
          example: CREATED
        document:
          $ref: '#/components/schemas/Document'
        score_result:
          $ref: '#/components/schemas/ScoreResult'
        provider:
          $ref: '#/components/schemas/Provider'
    ScoreResult:
      type: object
      description: Overall scoring results and extracted values.
      properties:
        global_score:
          type: number
          format: double
          description: >-
            Composite score (0.0–1.0) representing overall confidence in
            document authenticity.
          example: 0.85
        extracted_values:
          type: object
          additionalProperties:
            type: string
          description: >
            Key-value pairs extracted from the identity document. Possible keys
            include:
              - NAME: Full name of the individual.
              - LAST_NAME: Last name of the individual.
              - BIRTH_DATE: Date of birth in ISO format (YYYY-MM-DD).
              - DOCUMENT_NUMBER: Unique identifier of the document.
              - DOCUMENT_EXPIRATION_DATE: Expiration date of the document in ISO format (YYYY-MM-DD).
          example:
            NAME: John
            LAST_NAME: Doe
            BIRTH_DATE: '1990-01-01T00:00:00.000Z'
            DOCUMENT_NUMBER: X1234567
            DOCUMENT_EXPIRATION_DATE: '2030-12-31T00:00:00.000Z'
        scored_date:
          type: string
          format: date-time
          description: Exact UTC timestamp when this scoring session was scored.
          example: '2023-04-20T11:43:13Z'
        trace_metadata:
          $ref: '#/components/schemas/TraceMetadata'
        scores:
          type: array
          description: >-
            Array of detailed checks performed, each with its own risk score and
            fraud flag.
          items:
            $ref: '#/components/schemas/Score'
    Score:
      type: object
      description: Individual fraud or validity check outcome within a scoring session.
      properties:
        score_type:
          type: string
          example: MRZ_CONTROL_DIGIT
          description: >-
            Identifier for the specific check or metric applied (e.g., MRZ
            format, hologram detection).
        is_fraud:
          type: boolean
          example: false
          description: >-
            Boolean flag indicating whether this check detected fraudulent
            characteristics.
        score:
          type: number
          format: double
          example: 0.85
          description: >-
            Numeric confidence level (0.0–1.0) for this individual check’s
            result.
    DocumentWithCaptures:
      type: object
      description: High-level metadata for the document under verification.
      required:
        - type
        - country
        - captures
      properties:
        type:
          $ref: '#/components/schemas/IdentityDocumentType'
        country:
          $ref: '#/components/schemas/Country'
        captures:
          $ref: '#/components/schemas/DocumentCaptures'
    GetCapturesResponse:
      type: object
      description: URIs pointing to stored binary captures of the document images.
      required:
        - document
      properties:
        document:
          $ref: '#/components/schemas/DocumentWithCaptures'
    DocumentCaptures:
      type: object
      description: URIs pointing to stored binary captures of the document images.
      properties:
        front:
          type: string
          example: >-
            https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
          description: >-
            Secure HTTP URI for retrieving the front-side image of the identity
            document.
        back:
          type: string
          example: >-
            https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
          description: >-
            Secure HTTP URI for retrieving the back-side image of the identity
            document.
    CreateScoringRequest:
      type: object
      description: Request payload to initialize a new identity document scoring session.
      required:
        - document
        - provider
        - expires_in
      properties:
        document:
          $ref: '#/components/schemas/Document'
        provider:
          $ref: '#/components/schemas/Provider'
        expires_in:
          $ref: '#/components/schemas/ExpiresIn'
        max_score_retries:
          $ref: '#/components/schemas/MaxScoreRetries'
    CreateScoringResponse:
      type: object
      description: Response returned upon successful scoring session creation.
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Globally unique identifier for the newly created scoring session.
    TraceMetadata:
      type: object
      properties:
        browser_user_agent:
          description: >-
            Information to identify the application, operating system, vendor,
            and/or version of the requester
          type: string
          example: >-
            Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101
            Firefox/42.0
        ip_address:
          description: >-
            Device IP address automatically collected by the backend server. Any
            value provided by the client will be ignored.
          type: string
          example: 172.17.0.4
        browser_installation_id:
          description: Browser installation ID (unique identifier).
          type: string
        device_location:
          description: 'Device location coordinates (latitude, longitude).'
          type: string
          example: '88.52,-123.1'
        device_finger_print:
          description: Device fingerprint for tracking and fraud detection.
          type: string
          example: 33dd65c7fefc7078776965ca85cee243
    ExpiresIn:
      description: >-
        ISO-8601 duration string specifying how long (minimum 1 minute, maximum
        30 days) the scoring session will remain active.
      type: string
      example: P7D
    Provider:
      type: string
      example: GOOGLE
      description: >-
        Name of the external service provider used for performing the document
        verification (e.g., GOOGLE, VERIDAS).
    MaxScoreRetries:
      type: integer
      example: 5
      description: >-
        Maximum number of retries allowed for scoring attempts. This helps
        prevent abuse or excessive retries. By default, it is set to 5 retries.
    Country:
      type: string
      example: ES
      description: Two-letter ISO 3166-1 code representing the issuing country or region.
    IdentityDocumentType:
      type: string
      example: IDENTITY_CARD
      description: >-
        Type of document presented (IDENTITY_CARD, RESIDENCE_PERMIT, or
        PASSPORT).
    Document:
      type: object
      description: Structure defining the document’s classification and issuing country.
      required:
        - type
        - country
      properties:
        type:
          $ref: '#/components/schemas/IdentityDocumentType'
        country:
          $ref: '#/components/schemas/Country'
    IngestionsPage:
      type: integer
      description: Page to be shown (0-indexed).
      minimum: 0
      default: 0
      example: 0
    IngestionsPageSize:
      type: integer
      description: Number of items returned per page (max 200).
      minimum: 1
      maximum: 200
      default: 50
      example: 50
    DocumentId1:
      type: string
      example: d290f1ee-6c54-4b01-90e6-d701748f0851
      description: Unique identifier of a document stored in mas-documents
    ExecutionStatus:
      type: string
      example: PARTIAL
      description: >-
        Global result of an execution. An execution can be in one of the
        following statuses:

        - `ONGOING`: The execution is still in progress.

        - `SUCCESS`: The execution finished and every processed binary ended in
        a successful result.

        - `PARTIAL`: The execution finished but some binaries ended in a
        non-successful result (e.g. rejected as duplicate or failed).

        - `FAILED`: The execution finished and no binary could be ingested.
    ProcessingResult:
      type: string
      example: FAILED
      description: >-
        Per-binary processing result within an execution. Possible values:

        - `INGESTED`: The binary was ingested as a new document.

        - `OVERRIDDEN`: The binary replaced a previously ingested document with
        the same filename (conflict policy OVERRIDE).

        - `REJECTED_DUPLICATE`: The binary was rejected because a document with
        the same filename already existed in the ingestion (conflict policy
        BLOCK).

        - `FAILED`: The binary could not be processed due to an error.
    ExecutionCounters:
      type: object
      description: Aggregated counters of an execution.
      required:
        - total
        - ingested
        - overridden
        - rejected_duplicate
        - failed
      properties:
        total:
          type: integer
          minimum: 0
          description: Total binaries processed by the execution.
          example: 120
        ingested:
          type: integer
          minimum: 0
          example: 117
        overridden:
          type: integer
          minimum: 0
          example: 1
        rejected_duplicate:
          type: integer
          minimum: 0
          example: 1
        failed:
          type: integer
          minimum: 0
          example: 1
    IngestionExecution:
      type: object
      description: >
        Detail of a single execution. Contains metadata (identity, instants,
        status) and counters.

        It never embeds the list of processed binaries — that is exposed only by
        the dedicated paginated endpoint.
      required:
        - execution_id
        - ingestion_id
        - started_date
        - status
        - counters
      properties:
        execution_id:
          type: string
          example: 9b1c7a32-5d0f-4c88-9f2e-3c8d7a1e0042
        ingestion_id:
          type: string
          example: e7c2f4a0-3a1f-4d8b-8ad4-2f6a7b1a0001
        started_date:
          type: string
          format: date-time
          example: '2026-04-21T10:00:00Z'
          description: Instant at which the execution started.
        finished_date:
          type: string
          format: date-time
          example: '2026-04-21T10:04:17Z'
          description: >-
            Instant at which the execution finished. Absent while the execution
            is still running.
        status:
          $ref: '#/components/schemas/ExecutionStatus'
        counters:
          $ref: '#/components/schemas/ExecutionCounters'
    ListIngestionExecutionsResponse:
      type: object
      required:
        - executions
        - page
        - page_size
        - total
      properties:
        executions:
          type: array
          description: 'Page of executions, ordered from the most recent to the oldest.'
          items:
            $ref: '#/components/schemas/IngestionExecution'
        page:
          $ref: '#/components/schemas/IngestionsPage'
        page_size:
          $ref: '#/components/schemas/IngestionsPageSize'
        total:
          type: integer
          minimum: 0
          description: Total number of executions matching the filters across all pages.
          example: 1
    ExecutionProcessedBinary:
      type: object
      description: One binary processed during an execution.
      required:
        - filename
        - result
        - recorded_date
      properties:
        filename:
          type: string
          description: Original filename of the ingested binary.
          example: contract_00004.pdf
        result:
          $ref: '#/components/schemas/ProcessingResult'
        document_id:
          type: string
          nullable: true
          description: >-
            Identifier of the resulting document when the result produced one
            (INGESTED / OVERRIDDEN). Null otherwise.
          example: null
        error_message:
          type: string
          nullable: true
          description: >-
            Human-readable error message when the result is FAILED. Null
            otherwise.
          example: 'GCS read error: timeout'
        recorded_date:
          type: string
          format: date-time
          description: Instant at which the result was recorded.
          example: '2026-04-21T10:02:33Z'
    ListExecutionProcessedBinariesResponse:
      type: object
      required:
        - execution_binaries
        - page
        - page_size
        - total
      properties:
        execution_binaries:
          type: array
          items:
            $ref: '#/components/schemas/ExecutionProcessedBinary'
        page:
          $ref: '#/components/schemas/IngestionsPage'
        page_size:
          $ref: '#/components/schemas/IngestionsPageSize'
        total:
          type: integer
          minimum: 0
          description: >-
            Total number of processed binaries matching the filters across all
            pages.
          example: 2
    IngestedFilename:
      type: string
      minLength: 1
      maxLength: 255
      description: >-
        Original filename of the binary as it was ingested. Identifies the
        document inside the ingestion together with the ingestion id.
      example: contract_20260410_00123.pdf
    OwnerFinal:
      type: string
      minLength: 1
      description: >-
        Final business owner that will take ownership of the document after
        consolidation. Conventionally prefixed by the consumer-domain entity
        (e.g. `contract:<uuid>`, `billing:<uuid>`, `subscription:<id>`).
      example: 'contract:17ab9c0e-5432-42d1-9a8f-5e2d3c1b0088'
    DeconsolidateIngestedDocumentRequest:
      type: object
      required:
        - document_id
      additionalProperties: false
      properties:
        document_id:
          $ref: '#/components/schemas/DocumentId1'
      example:
        document_id: 8d3c2f10-6b22-4a91-bf34-9e2a1c0d4050
    DeconsolidateIngestedDocumentResponse:
      type: object
      required:
        - document_id
      additionalProperties: false
      properties:
        document_id:
          $ref: '#/components/schemas/DocumentId1'
      example:
        document_id: 8d3c2f10-6b22-4a91-bf34-9e2a1c0d4050
    ConsolidateIngestedDocumentRequest:
      type: object
      required:
        - filename
        - owner_final
      additionalProperties: false
      properties:
        filename:
          $ref: '#/components/schemas/IngestedFilename'
        owner_final:
          $ref: '#/components/schemas/OwnerFinal'
      example:
        filename: contract_20260410_00123.pdf
        owner_final: 'contract:17ab9c0e-5432-42d1-9a8f-5e2d3c1b0088'
    CloseIngestionResponse:
      type: object
      description: >-
        State of the ingestion after a close request (first close or idempotent
        second call).
      required:
        - id
        - tags
        - conflict_policy
        - status
        - creation_date
        - modification_date
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier of the ingestion.
          example: e7c2f4a0-3a1f-4d8b-8ad4-2f6a7b1a0001
        tags:
          type: array
          items:
            type: string
          description: Labels attached to the ingestion.
          example:
            - contracts
            - recable_2026
        conflict_policy:
          type: string
          description: Conflict resolution policy of the ingestion (block or override).
          example: block
        status:
          type: string
          description: Current status of the ingestion (open or closed).
          example: closed
        creation_date:
          type: string
          format: date-time
          description: Instant at which the ingestion was created.
          example: '2026-04-10T09:15:32Z'
        modification_date:
          type: string
          format: date-time
          description: Instant at which the ingestion was last updated.
          example: '2026-04-21T11:45:00Z'
        closed_date:
          type: string
          format: date-time
          nullable: true
          description: >-
            Instant at which the ingestion was closed. Absent while the
            ingestion is still open.
          example: '2026-04-21T11:45:00Z'
      example:
        id: e7c2f4a0-3a1f-4d8b-8ad4-2f6a7b1a0001
        tags:
          - contracts
          - recable_2026
        conflict_policy: block
        status: closed
        creation_date: '2026-04-10T09:15:32Z'
        modification_date: '2026-04-21T11:45:00Z'
        closed_date: '2026-04-21T11:45:00Z'
    ConsolidateIngestedDocumentResponse:
      type: object
      required:
        - document_id
        - filename
      additionalProperties: false
      properties:
        document_id:
          $ref: '#/components/schemas/DocumentId1'
        filename:
          $ref: '#/components/schemas/IngestedFilename'
      example:
        document_id: 8d3c2f10-6b22-4a91-bf34-9e2a1c0d4050
        filename: contract_20260410_00123.pdf
  securitySchemes:
    AuthNToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token provided By AuthN
  parameters:
    OrgId:
      name: org_id
      in: path
      required: true
      description: The string id related with one of Grupo MasOrange tenants
      schema:
        type: string
      example: masmovil
    ExternalId:
      name: external_id
      in: path
      required: true
      description: The external id of the dynamic template
      schema:
        type: string
      example: factura_mensual
    MajorVersion:
      name: major_version
      in: path
      required: true
      description: The major version number
      schema:
        type: integer
        minimum: 1
      example: 1
    MinorVersion:
      name: minor_version
      in: path
      required: true
      description: The minor version number
      schema:
        type: integer
        minimum: 0
      example: 1
    FillProcessId:
      name: fill_process_id
      in: path
      required: true
      description: Unique identifier of the fill process
      schema:
        type: string
      example: 11223344-aabb-ccdd-eeff-009988776655
    FillProcessOrigin:
      name: fill-process-origin
      in: header
      required: false
      description: >-
        Identifies the system originating the request. If not provided, it
        defaults to the Authn token's audience (x-auth-aud).
      schema:
        type: string
      example: sales-platform
    DynamicTemplatesPage:
      name: page
      in: query
      required: false
      description: >-
        Defines templates page number to be show. If not defined, default value
        is 0 (first page).
      schema:
        $ref: '#/components/schemas/DynamicTemplatesPage'
      example: 0
    DynamicTemplatesPageSize:
      name: page_size
      in: query
      required: false
      description: >-
        Defines the number of templates returned in each page. If not defined,
        default value is 50.
      schema:
        $ref: '#/components/schemas/DynamicTemplatesPageSize'
      example: 20
    OrgId1:
      name: org_id
      in: path
      required: true
      description: Organization name
      schema:
        type: string
        example: masmovil
    XInstallationId:
      name: x-installation_id
      in: header
      required: true
      description: browser installation id (unique identifier)
      schema:
        type: string
        example: 625fc44b-5b1c-451e-bcc7-276c911f0af8
    XFingerprint:
      name: x-fingerprint
      in: header
      required: true
      description: device fingerprint
      schema:
        type: string
        example: 33dd65c7fefc7078776965ca85cee243
    XLocation:
      name: x-location
      in: header
      required: false
      description: device location coordinate
      schema:
        type: string
        example: '88.52,-123.1'
    SignProcessId:
      name: sign_process_id
      in: path
      required: true
      description: uuid that identifies a digital sign process
      schema:
        type: string
        example: 7902cd2d-80f4-4766-a3e9-a1760e0df9bd
    SignId:
      name: sign_id
      in: path
      required: true
      description: >-
        uuid that identifies signature data by signer, associated to a digital
        sign process
      schema:
        type: string
        example: 0b9bbe95-f080-4317-b371-1f9ae0b9bf4f
    OrgId2:
      name: org_id
      in: path
      required: true
      description: Organization name
      schema:
        type: string
        example: masmovil
    OrgId3:
      name: org_id
      in: path
      required: true
      description: Organization name
      schema:
        type: string
        example: masmovil
    IdentificationId:
      name: identification_id
      in: path
      required: true
      description: >-
        uuid for each signer's identification process associated to a digital
        sign process
      schema:
        type: string
        example: 0b9bbe95-f080-4317-b371-1f9ae0b9bf4f
    XForwardedFor:
      name: x-forwarded-for
      in: header
      required: true
      description: >-
        Device IP address automatically collected by the backend server. Any
        value provided by the client will be ignored.
      schema:
        type: string
        example: 88.88.88.88
    UserAgent:
      name: User-Agent
      in: header
      required: true
      description: >-
        information to identify the application, operating system, vendor,
        and/or version of the requester
      schema:
        type: string
        example: >-
          Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101
          Firefox/42.0
    OrgId4:
      name: org_id
      in: path
      required: true
      description: Organization name
      schema:
        type: string
        example: masmovil
    AdminIdentificationId:
      name: admin_identification_id
      in: path
      required: true
      description: uuid identification unique identifier
      schema:
        type: string
        example: 0b9bbe95-f080-4317-b371-1f9ae0b9bf4f
    ForceDelete:
      name: force
      in: query
      required: false
      description: >-
        If the process is not in CREATED state this parameter has to be passed
        as true AND needed permission has  to be present at the token for the
        deletion to happen. A FORBIDDEN code will be thrown otherwise.

        - 'true' if identification process must be deleted regardless of the
        state.

        - 'false' or not present otherwise.
      schema:
        type: string
        example: true
    AdminUserAgent:
      name: User-Agent
      in: header
      required: true
      description: >-
        information to identify the application, operating system, vendor,
        and/or version of the requester
      schema:
        type: string
        example: >-
          Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101
          Firefox/42.0
    AdminXInstallationId:
      name: x-installation_id
      in: header
      required: true
      description: browser installation id (unique identifier)
      schema:
        type: string
        example: 625fc44b-5b1c-451e-bcc7-276c911f0af8
    AdminXFingerprint:
      name: x-fingerprint
      in: header
      required: true
      description: device fingerprint
      schema:
        type: string
        example: 33dd65c7fefc7078776965ca85cee243
    AdminXLocation:
      name: x-location
      in: header
      required: false
      description: device location coordinate
      schema:
        type: string
        example: '88.52,-123.1'
    XInstallationId1:
      name: x-installation_id
      in: header
      required: true
      description: Browser installation id (unique identifier)
      schema:
        type: string
        example: 625fc44b-5b1c-451e-bcc7-276c911f0af8
    XFingerprint1:
      name: x-fingerprint
      in: header
      required: true
      description: Device fingerprint for tracking and fraud detection.
      schema:
        type: string
        example: 33dd65c7fefc7078776965ca85cee243
    XForwardedFor1:
      name: x-forwarded-for
      in: header
      required: true
      description: >-
        Device IP address automatically collected by the backend server. Any
        value provided by the client will be ignored.  Make sure this value is
        not dropped within nested requests on calls between microservices
      schema:
        type: string
        example: 88.88.88.88
    XLocation1:
      name: x-location
      in: header
      required: false
      description: 'Device location coordinates (latitude, longitude).'
      schema:
        type: string
        example: '88.52,-123.1'
    UserAgent1:
      name: User-Agent
      in: header
      required: true
      description: >-
        Information to identify the application, operating system, vendor,
        and/or version of the requester
      schema:
        type: string
        example: >-
          Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101
          Firefox/42.0
    OrgId5:
      name: org_id
      in: path
      required: true
      description: The string id related with one of Grupo MasOrange tenants.
      schema:
        type: string
      example: masmovil
    IngestionId:
      name: ingestion_id
      in: path
      required: true
      description: Unique identifier of the ingestion.
      schema:
        type: string
      example: e7c2f4a0-3a1f-4d8b-8ad4-2f6a7b1a0001
    ExecutionId:
      name: execution_id
      in: path
      required: true
      description: Unique identifier of an execution within the ingestion.
      schema:
        type: string
      example: 9b1c7a32-5d0f-4c88-9f2e-3c8d7a1e0042
    ExecutionStatusFilter:
      name: status
      in: query
      required: false
      description: Optional filter by execution global status.
      schema:
        $ref: '#/components/schemas/ExecutionStatus'
      example: PARTIAL
    OutcomeFilter:
      name: result
      in: query
      required: false
      description: Optional filter by per-binary processing result.
      schema:
        $ref: '#/components/schemas/ProcessingResult'
      example: FAILED
    FromTs:
      name: from_ts
      in: query
      required: false
      description: >-
        Inclusive lower bound (ISO-8601) of the temporal range to filter results
        by.
      schema:
        type: string
        format: date-time
      example: '2026-04-01T00:00:00Z'
    ToTs:
      name: to_ts
      in: query
      required: false
      description: >-
        Exclusive upper bound (ISO-8601) of the temporal range to filter results
        by.
      schema:
        type: string
        format: date-time
      example: '2026-05-01T00:00:00Z'
    IngestionsPage:
      name: page
      in: query
      required: false
      description: Page number (0-indexed). Defaults to 0.
      schema:
        $ref: '#/components/schemas/IngestionsPage'
      example: 0
    IngestionsPageSize:
      name: page_size
      in: query
      required: false
      description: Number of items per page. Defaults to 50. Maximum 200.
      schema:
        $ref: '#/components/schemas/IngestionsPageSize'
      example: 50
  responses:
    Success204:
      description: Action executed correctly
    Error400:
      description: Request input is not valid
    Error401:
      description: Unauthorized. AuthN and AuthZ validations have fail
    Error500:
      description: Not expected error
    ErrorDefault:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
    Error4011:
      description: >-
        Unauthorized. AuthN and AuthZ validations have fail or certificate
        password is not correct
    Success204WithAccessToken:
      description: Action executed correctly
      headers:
        x-access-token:
          schema:
            type: string
          description: securized authn web_component token.
          required: true
    Success200WithTwoFactorValue:
      description: Action executed correctly
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwoFactorValueResponse'
    Error403:
      description: Forbidden. Request has invalid credentials
    Error404:
      description: Not found. Entity does not exist or can not be found
    Error409:
      description: >-
        Conflict. Entity state has conflicts between its new state and the old
        one.
    Error410:
      description: Gone. Resource is no longer available
    Error412:
      description: Precondition failed. Request can not be processed yet
    BadRequest:
      description: Request input is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
    TooEarly:
      description: 'The request cannot be processed at this time, try again later'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
    Unauthorized:
      description: The user is not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
    InternalServerError:
      description: The request failed to be processed by the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsResponse'
