openapi: 3.1.0
info:
  title: Soyio API
  description: |-
    API del Servicio de Identidad de Soyio.

    ## Permisos
    Cada operación puede declarar `x-permissions`. Esta extensión es solo documentación y no es un header.
    `x-permissions` usa llaves `dashboard_any_of` y/o `api_any_of` para listar permisos válidos según el
    tipo de autenticación. Los permisos definidos están en `components.schemas.Permission`.
  contact:
    email: soporte@soyio.id
  version: 1.0.0
servers:
  - url: 'https://sandbox.soyio.id/api/v1'
    description: Servidor de pruebas (sandbox)
  - url: 'https://app.soyio.id/api/v1'
    description: Servidor de producción (production)
tags:
  - name: Configuration
    description: |
      Representa a los aspectos configurables de tu empresa, tales como canales de comunicación u otros datos relevantes.
  - name: Disclosure requests
    description: |
      Los disclosure requests representan el proceso en que una compañía solicita datos de una identidad verificada.
  - name: Auth requests
    description: |
      Los auth requests son una forma de autenticar a identidades previamente validadas a través de un `disclosure_request`.
  - name: Consent templates
    description: |
      Los templates de consentimiento te permiten estandarizar la forma en que solicitas datos a tus usuarios.
      Contienen la lista de datos requeridos, sus usos, así como referencias a documentos de privacidad.
  - name: Disclosure templates
    description: |
      Los templates de divulgación definen los datos, documentos y validadores necesarios para ejecutar un proceso de
      verificación de identidad y compartir información con tu compañía durante un disclosure request.
  - name: Consent actions
    description: |
      Los consent actions permiten crear acciones de consentimiento.
  - name: Consent revocations
    description: |
      Las consent revocations permiten registrar revocaciones de consentimiento iniciadas por la empresa.
  - name: Consent commits
    description: |
      Los consent commits permiten crear múltiples acciones de consentimiento.
  - name: Privacy documents
    description: |
      Los documentos de privacidad son archivos que contienen información legal y de privacidad
      que pueden ser referenciados tanto en los `disclosure_templates` como los `consent_templates`.
  - name: Identities
    description: Los objetos de identidad permiten gestionar los datos de identidad de tus usuarios.
  - name: Validation attempts
    description: |
      Los intentos de validación, representan los procesos de validación de identidades de los usuarios. Estos obedecen a una serie de reglas de validación representadas por un template de validación.
  - name: Auth attempts
    description: |
      Los intentos de autenticación representan movimientos de una identidad al intentar autenticarse con tu sistema.

      El tipo de autenticación dependerá del registro del dispositivo de autenticación del usuario. En el caso de que un usuario no tenga su dispositivo de autenticación registrado, el tipo de validación será facial. En ese momento se le pedirá registrar el dispositivo.
  - name: Signature attempts
    description: |
      Representan los intentos de los usuarios para firmar ciertos documentos, los cuales dependen del SignatureAttemptTemplate. La firma puede realizarse por medio de llaves de acceso para cuando el usuario haya registrado una, o por medio de video facial cuando el usuario por alguna razón no puede usar la llave de acceso.
  - name: Data subject requests
    description: |
      Representan las solicitudes de ejercicio de derechos de los usuarios.

      ### Guías relacionadas

      - [Gestión de derechos](/docs/integration-guide/rights-management/introduction)
      - [Centro de privacidad](/docs/integration-guide/privacy-center/introduction)
  - name: Events
    description: |
      Los eventos nos permiten comunicarte cambios relevantes en el sistema. Cuando ocurre un evento interesante, se crea un objeto evento. Por ejemplo, cuando se valida una identidad, se crea un evento `validation_attempt.succeeded`; cuando una validación falla, se crea un objeto `validation_attempt.failed`.

      > Una llamada a la API **puede generar 1 o más eventos**.

      Los eventos pueden ser enviados directamente a tu servidor a través de la utilización de webhooks.

      ### Guías relacionadas

      - [Webhooks](/docs/api/webhooks)
  - name: Signed documents
    description: |
      Los documentos firmados son documentos digitales que han sido autenticados por los usuarios mediante su firma electrónica. Estos documentos pueden incluir contratos, acuerdos legales, y otros documentos importantes que requieren confirmación de identidad y consentimiento explícito del usuario.

      La firma de estos documentos se gestiona a través del modelo `SignatureAttempt`, que verifica la identidad del usuario y asegura que la firma sea válida y segura.
  - name: Agreements
    description: |
      Los acuerdos (agreements) representan las reglas de compartimiento de datos entre la empresa y un usuario.
      Cada acuerdo puede tener múltiples versiones y evidencias asociadas que respaldan su validez.
      Las evidencias pueden incluir archivos descargables que proporcionan prueba del consentimiento otorgado.
  - name: Webhooks
    description: |
      Los webhooks permiten recibir notificaciones en tiempo real cuando ocurren eventos en el sistema.
      Puedes configurar múltiples webhooks y suscribirlos a diferentes tipos de eventos.

      > Cada webhook puede estar suscrito a uno o más tipos de eventos. Por ejemplo, puedes suscribirte a todos los eventos de la identidad, o a todos los eventos de validación.

      :::danger[Atención]
      Si un webhook falla, se intentará enviar nuevamente hasta un máximo de 15 veces. Luego de eso, el webhook se **deshabilitará automáticamente**.
      :::

      ### Guías relacionadas
      - [Webhooks](/docs/api/webhooks)
  - name: Products
    description: |
      Diferentes productos o servicios que ofrece tu compañía.
  - name: Entities
    description: |
      Las entidades representan a los usuarios que interactúan con tu compañía, pero que no han realizado una validación de identidad.
  - name: Company
    description: |
      La compañía es el objeto que representa a tu empresa y sus respectivas configuraciones. La mayoría de los objetos de nuestra API están relacionados a una compañía.
  - name: Company users
    description: |
      Los usuarios de compañía representan las cuentas con acceso al dashboard de tu empresa.
      Cada usuario puede tener un rol asignado con permisos específicos.
  - name: Branches
    description: |
      Las branches representan divisiones o unidades de negocio específicas dentro de tu compañía.
  - name: Privacy center
    description: |
      El centro de privacidad permite a los usuarios gestionar sus consentimientos y datos personales.
      Proporciona endpoints para obtener tokens de sesión que permiten acceder a funcionalidades específicas
      del centro de privacidad.

      ### Guías relacionadas

      - [Centro de privacidad](/docs/integration-guide/privacy-center/introduction)
      - [Gestión de derechos](/docs/integration-guide/rights-management/introduction)
  - name: API Keys
    description: |
      Las API keys permiten autenticar y autorizar el acceso a la API de Soyio.
      Cada API key puede tener un alcance específico que limita las operaciones que puede realizar.

      ### Guías relacionadas

      - [Autenticación](/docs/api/authentication)
  - name: Reports
    description: |
      Reportes generados por la empresa para cumplimiento y análisis operativos.
  - name: Exports
    description: |
      Exportaciones asíncronas de alto volumen para recursos de la API.
  - name: Government check requests
    description: |
      Los government check requests representan solicitudes de verificación de identidad directamente contra el registro civil,
      sin necesidad de biometría. Permiten validar datos de identidad (RUT y número de documento) contra bases de datos gubernamentales.
  - name: REDEC
    description: |
      Endpoints específicos para el cumplimiento normativo REDEC (Registro de Empresas y Entidades de Crédito) de Chile.
paths:
  /consent_templates:
    get:
      tags:
        - Consent templates
      summary: Obtener todos los templates de consentimiento
      operationId: indexConsentTemplates
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Templates de consentimiento encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplateIndexList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Consent templates
      summary: Crear un template de consentimiento
      operationId: createConsentTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentTemplateInput'
            examples:
              scopes_with_explicit_versions:
                summary: Crear template con scopes versionados explícitamente
                value:
                  name: Consentimiento marketing por alcance
                  title: Autorización de tratamiento
                  text: 'Autorizo el tratamiento de mis datos según {{ privacy_policy }}'
                  data_subject: customer
                  duration_type: fixed
                  duration: P6M
                  data_requirements:
                    - key: email
                      data_uses:
                        - marketing.email
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 2
                    - scope_type: branch
                      scope_id: branch_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 4
              scopes_without_version:
                summary: Crear template dejando que API resuelva latest
                value:
                  name: Consentimiento operacional
                  title: Consentimiento base
                  text: Acepto el tratamiento para fines operacionales
                  data_subject: customer
                  duration_type: conditional
                  duration_clause_type: while_contractual_relationship
                  data_requirements:
                    - key: phone_number
                      data_uses:
                        - essential.service.notifications
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
              legacy_fields:
                summary: Compatibilidad legado con product_id y branch_id
                value:
                  name: Consentimiento legado
                  title: Consentimiento
                  text: Acepto los términos del consentimiento
                  data_subject: customer
                  duration_type: fixed
                  duration: P3M
                  data_requirements:
                    - key: email
                      data_uses:
                        - essential.service.authentication
                  product_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                  branch_id: branch_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '201':
          description: Template de consentimiento creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Availability period in months is not a number
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/consent_templates/{id}':
    get:
      tags:
        - Consent templates
      summary: Obtener la última versión de un template de consentimiento
      operationId: getConsentTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de consentimiento
          schema:
            type: string
      responses:
        '200':
          description: Última versión del template de consentimiento encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Consent templates
      summary: Actualizar un template de consentimiento
      description: 'El modelo de template de consentimiento es versionado, por lo que cada cambio realizado no modifica la versión actual, sino que genera una nueva versión, dejando trazable el historial de cambios.'
      operationId: updateConsentTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de consentimiento
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentTemplateInput'
            examples:
              update_and_pin_new_scope_version:
                summary: Actualizar template creando nueva versión con scope fijo
                value:
                  name: Consentimiento marketing por alcance
                  title: Autorización de tratamiento
                  text: 'Autorizo el tratamiento de mis datos según {{ privacy_policy }}'
                  data_subject: customer
                  duration_type: fixed
                  duration: P12M
                  data_requirements:
                    - key: email
                      data_uses:
                        - marketing.email
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 3
              migrate_legacy_to_scopes:
                summary: Migrar input legado a scopes en nueva versión
                value:
                  name: Consentimiento legado migrado
                  title: Consentimiento
                  text: Acepto los términos del consentimiento
                  data_subject: customer
                  duration_type: fixed
                  duration: P6M
                  data_requirements:
                    - key: email
                      data_uses:
                        - essential.service.authentication
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: 'Nueva versión del template de consentimiento, con los cambios realizados.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/consent_templates/{id}/action_tokens':
    post:
      tags:
        - Consent templates
      summary: Crea un action token
      description: 'Crea un token de acción de consentimiento para un template específico. Requerido en el flujo de creación de [Consent Commits](/docs/api/resources/schemas/consentcommit) y/o [Consent Actions](/docs/api/resources/schemas/consentaction).'
      operationId: createActionToken
      parameters:
        - name: id
          in: path
          required: true
          description: Id del template de consentimiento
          schema:
            type: string
          example: constpl_wAspvmEr4ACDZaPUtfwjsA
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionTokenCreateInput'
            examples:
              full_template_scope:
                summary: Token para todos los scopes del template
                value:
                  context: web_signup
                  kind: grant
                  action_type: opt_in_click
                  timestamp: '2024-03-20T15:30:00Z'
                  action_data:
                    checkbox_id: cb_123
                  contextual_data:
                    ip: 192.168.1.1
                    user_agent: Mozilla/5.0
              partial_scope_selection:
                summary: Token para un subconjunto de scopes
                value:
                  context: web_signup
                  kind: grant
                  action_type: opt_in_click
                  timestamp: '2024-03-20T15:30:00Z'
                  selected_scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 2
                  action_data:
                    checkbox_id: cb_123
                  contextual_data:
                    ip: 192.168.1.1
                    user_agent: Mozilla/5.0
      responses:
        '201':
          description: Token de acción de consentimiento creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTokenResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.actions.write
          - consent.api.manage
      security:
        - api_key: []
  '/consent_templates/{id}/versions':
    get:
      tags:
        - Consent templates
      summary: Obtener todas las versiones de un template de consentimiento
      operationId: indexConsentTemplateVersions
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de consentimiento
          schema:
            type: string
          example: constpl_wAspvmEr4ACDZaPUtfwjsA
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Versiones del template de consentimiento encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplateList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/consent_templates/{id}/versions/{version_id}':
    get:
      tags:
        - Consent templates
      summary: Obtener una versión específica de un template de consentimiento
      operationId: getConsentTemplateVersion
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de consentimiento
          schema:
            $ref: '#/components/schemas/ConsentTemplate'
        - name: version_id
          in: path
          required: true
          description: Número de versión del template
          schema:
            $ref: '#/components/schemas/ConsentTemplate'
      responses:
        '200':
          description: Versión específica del template de consentimiento encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  /privacy_documents:
    get:
      tags:
        - Privacy documents
      summary: Obtener todos los documentos de privacidad
      operationId: indexPrivacyDocuments
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Documentos de privacidad encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacyDocumentList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - consent.dashboard.read
          - consent.dashboard.manage
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - consent.api.manage
          - disclosure.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Privacy documents
      summary: Crea un privacy document
      operationId: createPrivacyDocument
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - template_key
                - file
              properties:
                name:
                  type: string
                  description: 'Texto que aparecerá en el módulo embebible, al referenciarlo con el `template_key`.'
                  example: términos y condiciones
                template_key:
                  type: string
                  description: Llave única para referenciar el documento en templates.
                  example: terms_and_conditions
                file:
                  type: string
                  format: binary
                  description: Archivo del documento
      responses:
        '201':
          description: Documento de privacidad creado
          content:
            application/json:
              schema:
                type: object
                properties:
                  privacy_document:
                    $ref: '#/components/schemas/PrivacyDocument'
        '400':
          description: Error de solicitud - falta algún campo requerido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        example: invalid_request_error
                      title:
                        type: string
                        example: Missing parameter
                      status:
                        type: integer
                        example: 400
                      detail:
                        type: string
                        example: The required parameter file is missing
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Privacy documents is invalid
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - consent.dashboard.manage
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - consent.api.manage
          - disclosure.api.manage
      security:
        - api_key: []
  '/privacy_documents/{id}':
    get:
      tags:
        - Privacy documents
      summary: Obtener la última versión de un documento de privacidad específico
      operationId: getPrivacyDocument
      parameters:
        - name: id
          in: path
          description: ID del documento de privacidad
          required: true
          schema:
            type: string
          example: privdoc_jy21JCGqb-VHhHeUd2nmKw
      responses:
        '200':
          description: Última versión del documento de privacidad encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  privacy_document:
                    $ref: '#/components/schemas/PrivacyDocument'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - consent.dashboard.read
          - consent.dashboard.manage
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - consent.api.manage
          - disclosure.api.manage
      security:
        - api_key: []
  '/privacy_documents/{id}/versions':
    get:
      tags:
        - Privacy documents
      summary: Obtener todas las versiones de un documento de privacidad
      operationId: indexPrivacyDocumentVersions
      parameters:
        - name: id
          in: path
          required: true
          description: ID del documento de privacidad
          schema:
            type: string
          example: privdoc_jy21JCGqb-VHhHeUd2nmKw
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Versiones del documento de privacidad encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacyDocumentList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - consent.dashboard.read
          - consent.dashboard.manage
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - consent.api.manage
          - disclosure.api.manage
      security:
        - api_key: []
  '/privacy_documents/{id}/versions/{version_id}':
    get:
      tags:
        - Privacy documents
      summary: Obtener una versión específica de un documento de privacidad
      operationId: getPrivacyDocumentVersion
      parameters:
        - name: id
          in: path
          required: true
          description: ID del documento de privacidad
          schema:
            type: string
          example: privdoc_jy21JCGqb-VHhHeUd2nmKw
        - name: version_id
          in: path
          required: true
          description: Número de versión del documento
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Versión específica del documento de privacidad encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  privacy_document:
                    $ref: '#/components/schemas/PrivacyDocument'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - consent.dashboard.read
          - consent.dashboard.manage
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - consent.api.manage
          - disclosure.api.manage
      security:
        - api_key: []
  /disclosure_templates:
    get:
      tags:
        - Disclosure templates
      summary: Obtener todos los templates de divulgación
      operationId: indexDisclosureTemplates
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: |
            Filtros en formato JSON.
            Para `liveness_check` e `id_scan_check`, se considera el valor efectivo del template;
            si el template no define `validation_mode`, se usa la configuración de la compañía.
          required: false
          schema:
            type: string
          examples:
            liveness_check_enabled:
              summary: Filtrar templates con liveness habilitado
              value: '{"liveness_check":{"=":true}}'
            id_scan_check_disabled:
              summary: Filtrar templates sin escaneo de documento
              value: '{"id_scan_check":{"=":false}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Templates de divulgación encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureTemplateList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Disclosure templates
      summary: Crear un template de divulgación
      operationId: createDisclosureTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisclosureTemplateInput'
      responses:
        '201':
          description: Template de divulgación creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Validator type can't be blank
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
  '/disclosure_templates/{id}':
    get:
      tags:
        - Disclosure templates
      summary: Obtener un template de divulgación
      operationId: getDisclosureTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de divulgación
          schema:
            type: string
      responses:
        '200':
          description: Template de divulgación encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Disclosure templates
      summary: Actualizar un template de divulgación
      operationId: updateDisclosureTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de divulgación
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisclosureTemplateInput'
      responses:
        '200':
          description: Template de divulgación actualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
    delete:
      tags:
        - Disclosure templates
      summary: Eliminar un template de divulgación
      description: |
        Elimina un template de divulgación siempre que no existan disclosure requests que lo utilicen.
        Si el template está asociado a disclosures ya creados, la operación retornará un error de validación.
      operationId: deleteDisclosureTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de divulgación
          schema:
            type: string
      responses:
        '204':
          description: Template de divulgación eliminado
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: No es posible eliminar el template de divulgación.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Cannot delete a disclosure template with associated disclosure requests
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
  /disclosure_requests:
    get:
      tags:
        - Disclosure requests
      summary: Obtener todos los disclosure requests
      operationId: indexDisclosureRequests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"pending"}}'
            date_filter:
              summary: Filtrar por fecha de creación
              value: '{"created_at":{">":"2024-01-01T00:00:00.000Z"}}'
            combined_filter:
              summary: Filtros combinados
              value: '{"status":{"=":"pending"},"created_at":{">":"2024-01-01T00:00:00.000Z"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Disclosure requests encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureRequestList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Disclosure requests
      summary: Crear un disclosure request
      operationId: createDisclosureRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - disclosure_template_id
                - user_reference
                - user_email
              properties:
                disclosure_template_id:
                  type: string
                  description: Identificador del disclosure template.
                  example: dtpl_3D4O4A0CuiVriCnA9RjEhi
                user_reference:
                  type: string
                  description: Referencia de usuario de tu sistema para el disclosure request.
                  example: user_123
                user_email:
                  type: string
                  description: Correo electrónico del usuario para el disclosure request.
                  example: walter@white.com
                entity_id:
                  type: string
                  description: Identificador de entidad previamente creada.
                  example: ent_3D4O4A0CuiVriCnA9RjEhi
                matchers:
                  type: array
                  description: Matchers del disclosure request. Campo opcional.
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Clave del matcher.
                        example: cl_carnet_rut
                        enum:
                          - cl_carnet_rut
                          - name
                          - last_name
                          - date_of_birth
                      value:
                        type: string
                        description: Valor del matcher.
                        example: 12345678-9
                force_validation:
                  type: boolean
                  description: 'Cuando se establece en `true`, obliga a ejecutar una nueva validación aunque exista un disclosure request previo activo para la misma referencia y template.'
                  example: true
                  default: false
      responses:
        '201':
          description: Disclosure request creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  disclosure_request:
                    $ref: '#/components/schemas/DisclosureRequest'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Disclosure template is required
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
  '/disclosure_requests/{id}':
    get:
      tags:
        - Disclosure requests
      summary: Obtener un disclosure request específico
      operationId: getDisclosureRequest
      parameters:
        - name: id
          in: path
          description: Identificador único del disclosure request
          required: true
          explode: true
          schema:
            type: string
          example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Disclosure request encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  disclosure_request:
                    $ref: '#/components/schemas/DisclosureRequest'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /auth_requests:
    post:
      tags:
        - Auth requests
      summary: Crear un request de autenticación
      description: |
        Crea un nuevo request de autenticación para una identidad específica.
        El tipo de autenticación dependerá de si el usuario tiene un dispositivo registrado (passkey_validation)
        o no (facial_validation).
      operationId: createAuthRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identity_id:
                  type: string
                  description: Identificador único de la identidad que realizará el intento de autenticación.
                  example: id_ma21KLsmaslopask912Aa2
              required:
                - identity_id
      responses:
        '201':
          description: Request de autenticación creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_attempt:
                    $ref: '#/components/schemas/AuthAttempt'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Invalid identity_id
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
    get:
      tags:
        - Auth requests
      summary: Obtener todos los auth requests
      operationId: indexAuthRequests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"awaiting_authentication"}}'
            identity_filter:
              summary: Filtrar por identidad
              value: '{"identity_id":{"=":"id_ma21KLsmaslopask912Aa2"}}'
            combined_filter:
              summary: Filtros combinados
              value: '{"status":{"=":"awaiting_authentication"},"identity_id":{"=":"id_ma21KLsmaslopask912Aa2"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Auth requests encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthRequestList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  '/auth_requests/{id}':
    get:
      tags:
        - Auth requests
      summary: Obtener un auth request específico
      operationId: getAuthRequest
      parameters:
        - name: id
          in: path
          description: ID del auth request a buscar
          required: true
          schema:
            type: string
          example: authreq_Kop19_kEe23i7hSw8QG4-a
      responses:
        '200':
          description: Auth request encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_request:
                    $ref: '#/components/schemas/AuthRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /data_subject_requests:
    post:
      tags:
        - Data subject requests
      summary: |
        Crea un data subject request.
      description: |
        :::info[Ojo]
        Dependiendo del tipo de request `kind`, se requerirá un `request_detail` diferente:
        - `access`, `portability`: `request_detail` es un objeto con las categorías de datos a solicitar.
        - `rectification`, `opposition`, `suppression`: `request_detail` es un arreglo con objetos que contienen los campos a modificar/eliminar.
        :::
      operationId: createDataSubjectRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSubjectRequestCreate'
      responses:
        '201':
          description: Data subject request creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - 'Kind is not a valid value. Allowed values are: revoke, change'
                          - Description can't be blank
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.write
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.write
          - dsr.api.manage
      security:
        - api_key: []
    get:
      tags:
        - Data subject requests
      summary: Obtener todos los data subject requests
      operationId: indexDataSubjectRequests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Data subject requests encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequestList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.read
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.read
          - dsr.api.manage
      security:
        - api_key: []
  '/data_subject_requests/{id}':
    get:
      tags:
        - Data subject requests
      summary: Obtener un data subject request específico
      operationId: getDataSubjectRequest
      parameters:
        - name: id
          in: path
          description: ID del data subject request a buscar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Data subject request encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.read
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.read
          - dsr.api.manage
      security:
        - api_key: []
    put:
      tags:
        - Data subject requests
      summary: Actualizar el estado de un data subject request
      description: |
        Actualiza el estado de una solicitud de ejercicio de derechos.

        Si `terminal_state` es `rejected` o `partially_approved` (o `approved` es `false`), el campo
        `rejection_reason` es **obligatorio**.
        Cuando ambos están presentes, `terminal_state` tiene precedencia.
      operationId: updateDataSubjectRequest
      parameters:
        - name: id
          in: path
          description: ID del data subject request a actualizar
          required: true
          explode: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSubjectRequestUpdate'
            examples:
              approve_request:
                summary: Aceptar solicitud
                value:
                  status: resolved
                  terminal_state: approved
              reject_request:
                summary: Rechazar solicitud
                value:
                  status: resolved
                  terminal_state: rejected
                  rejection_reason: Documentación insuficiente para procesar la solicitud
              partially_approve_request:
                summary: Aceptar solicitud parcialmente
                value:
                  status: resolved
                  terminal_state: partially_approved
                  rejection_reason: Algunos datos no pudieron ser procesados
              approve_request_legacy:
                summary: Aceptar solicitud (legacy)
                value:
                  status: resolved
                  approved: true
              reject_request_legacy:
                summary: Rechazar solicitud (legacy)
                value:
                  status: resolved
                  approved: false
                  rejection_reason: Documentación insuficiente para procesar la solicitud
      responses:
        '200':
          description: Data subject request actualizado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                invalid_status:
                  summary: Estado inválido
                  value:
                    type: validation_error
                    title: Validation error
                    status: 422
                    errors:
                      - Invalid status
                missing_rejection_reason:
                  summary: Falta razón de rechazo
                  value:
                    type: validation_error
                    title: Validation error
                    status: 422
                    errors:
                      - rejection_reason is required when status is rejected
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.write
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.write
          - dsr.api.manage
      security:
        - api_key: []
  '/data_subject_requests/by_identifier/{identifier}':
    get:
      tags:
        - Data subject requests
      summary: Obtener un data subject request por identificador humanizado
      operationId: getDataSubjectRequestByIdentifier
      parameters:
        - name: identifier
          in: path
          description: Identificador humanizado de la solicitud
          required: true
          explode: true
          schema:
            type: string
          example: FME4607
      responses:
        '200':
          description: Data subject request encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequest'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /data_subject_requests/recovery_email:
    post:
      tags:
        - Data subject requests
      summary: Enviar correo de recuperación del identificador de la solicitud
      description: |
        Envía un correo electrónico con el identificador de la última solicitud del titular de datos, si existe una solicitud asociada al correo proporcionado.
        Si la configuración de la compañía tiene deshabilitados los correos funcionales, no se enviará el correo, pero la respuesta será exitosa igualmente.
      operationId: sendDataSubjectRequestRecoveryEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email del usuario asociado a la solicitud
                  example: user@example.com
      responses:
        '200':
          description: Solicitud procesada
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'If a data subject request exists for this email, a recovery email has been sent.'
  /identities:
    get:
      tags:
        - Identities
      summary: Obtener todas las identidades
      operationId: indexIdentities
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            email_filter:
              summary: Filtrar por email
              value: '{"email":{"like":"@example.com"}}'
            data_filter:
              summary: Filtrar por datos personales
              value: '{"data":{"name":{"=":"John"}}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Identidades encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.read
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.read
          - dsr.api.manage
      security:
        - api_key: []
  '/identities/{id}':
    get:
      tags:
        - Identities
      summary: Obtener una identidad específica
      operationId: getIdentity
      parameters:
        - name: id
          in: path
          description: ID de la identidad a buscar
          required: true
          explode: true
          schema:
            type: string
        - name: filtered_by_agreement
          in: query
          description: 'Cuando se establece en `true`, retorna solo los datos permitidos por el `agreement` entre la identidad y la compañía. Por defecto retorna todos los datos del vault sin filtrar.'
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Operación exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  identity:
                    $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.read
          - dsr.dashboard.manage
        api_any_of:
          - dsr.api.read
          - dsr.api.manage
      security:
        - api_key: []
    delete:
      tags:
        - Identities
      summary: Eliminar una identidad
      description: |
        Elimina una identidad específica.
        :::info[Ojo]
        **Esta acción solo está disponible en entorno de sandbox.**
        :::
      operationId: deleteIdentity
      parameters:
        - name: id
          in: path
          description: ID de la identidad a eliminar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '204':
          description: Identidad eliminada exitosamente
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - api_key: []
  /validation_attempts:
    get:
      tags:
        - Validation attempts
      summary: Obtener todos los intentos de validación
      operationId: indexValidationAttempts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"successful"}}'
            date_range:
              summary: Filtrar por rango de fechas
              value: '{"created_at":{">":"2024-01-01T00:00:00","<":"2024-12-31T00:00:00"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Intentos de validación encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationAttemptList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  '/validation_attempts/{id}':
    get:
      tags:
        - Validation attempts
      summary: Obtener un flujo de validación específico
      description: Retorna un flujo de validación dado su ID.
      operationId: getValidationAttempt
      parameters:
        - name: id
          in: path
          description: ID del flujo de validación a buscar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Flujo de validación encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  validation_attempt:
                    $ref: '#/components/schemas/ValidationAttempt'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /auth_attempts:
    get:
      tags:
        - Auth attempts
      summary: Obtener todos los intentos de autenticación
      operationId: indexAuthAttempts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"successful"}}'
            type_filter:
              summary: Filtrar por tipo de autenticación
              value: '{"auth_type":{"=":"passkey_validation"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Intentos de autenticación encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthAttemptList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  '/auth_attempts/{id}':
    get:
      tags:
        - Auth attempts
      summary: Obtener un intento de autenticación específico
      description: Retorna un intento de autenticación dado su ID.
      operationId: getAuthAttempt
      parameters:
        - name: id
          in: path
          description: ID del intento de autenticación a buscar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Intento de autenticación encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_attempt:
                    $ref: '#/components/schemas/AuthAttempt'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /signature_attempts:
    post:
      tags:
        - Signature attempts
      summary: Crear un intento de firma
      description: |
        Crea un nuevo intento de firma para un documento basado en un template específico.
        Se deben proporcionar variables clave-valor dinámicas necesarias para el proceso de firma.
      operationId: createSignatureAttempt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identity_id:
                  type: string
                  description: Identificador único de la identidad que realiza el intento de firma.
                  example: id_ma21KLsmaslopask912Aa2
                template_id:
                  type: string
                  description: Identificador del template de firma a utilizar.
                  example: st_9F42D8L0JQ7p82H
                variables:
                  type: array
                  description: Array de pares clave-valor que serán utilizados en el documento a firmar.
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Nombre de la variable que se utilizará en el template de firma.
                      value:
                        type: string
                        description: Valor asociado a la clave especificada.
                  examples:
                    - - key: first_variable_key
                        value: first_variable_value
                      - key: second_variable_key
                        value: second_variable_value
              required:
                - identity_id
                - template_id
                - variables
      responses:
        '201':
          description: Intento de firma creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature_attempt:
                    $ref: '#/components/schemas/SignatureAttempt'
        '400':
          description: 'Datos de entrada inválidos, ya sea porque faltan variables, o se entregaron variables extra.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: Lista de mensajes de error describiendo los problemas con la solicitud.
                    items:
                      type: array
                      items:
                        type: string
                    examples:
                      - - 'Missing key: <missing_example_key>'
                        - 'Missing key: <another_missing_example_key>'
                        - Key <extra_key> does not exist in the signature template
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.write
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.write
          - disclosure.api.manage
      security:
        - api_key: []
    get:
      tags:
        - Signature attempts
      summary: Obtener todos los intentos de firma
      operationId: indexSignatureAttempts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"successful"}}'
            identity_filter:
              summary: Filtrar por identidad
              value: '{"identity_id":{"=":"id_ma21KLsmaslopask912Aa2"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Intentos de firma encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureAttemptList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  '/signature_attempts/{id}':
    get:
      tags:
        - Signature attempts
      summary: Obtener un intento de firma específico
      description: Retorna un intento de firma dado su ID.
      operationId: getSignatureAttempt
      parameters:
        - name: id
          in: path
          description: ID del intento de firma a buscar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Intento de firma encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature_attempt:
                    $ref: '#/components/schemas/SignatureAttempt'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /events:
    get:
      tags:
        - Events
      summary: Obtener todos los eventos
      operationId: indexEvents
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            event_name:
              summary: Filtrar por nombre del evento
              value: '{"name":{"=":"disclosure_request.granted"}}'
            date_range:
              summary: Filtrar por rango de fechas
              value: '{"created_at":{">":"2024-01-01T00:00:00","<":"2024-12-31T00:00:00"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Eventos encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/events/{id}':
    get:
      tags:
        - Events
      summary: Obtener un evento específico
      description: Obtiene los detalles de un evento existente.
      operationId: getEvent
      parameters:
        - name: id
          in: path
          description: ID del evento a buscar
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Evento encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/events/{id}/broadcast':
    post:
      tags:
        - Events
      summary: Reenviar un evento a los webhooks suscritos
      description: |
        Permite reenviar manualmente un evento a todos los webhooks suscritos de la compañía.
        Este endpoint es útil cuando necesitas retransmitir un evento específico, por ejemplo,
        si hubo problemas en la recepción original del webhook.
      operationId: broadcastEvent
      parameters:
        - name: id
          in: path
          description: Id del evento
          required: true
          schema:
            type: string
          example: evt_jy21JCGqb-VHhHeUd2nmKw
      responses:
        '204':
          description: El evento fue enviado exitosamente a la cola de webhooks
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  /signed_documents:
    get:
      tags:
        - Signed documents
      summary: Obtener todos los documentos firmados.
      description: 'Retorna una lista de documentos firmados. Los documentos se encuentran ordenados por defecto por la fecha de creación, donde los más recientes aparecerán primero.'
      operationId: indexSignedDocuments
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            identity_filter:
              summary: Filtrar por identidad
              value: '{"identity_id":{"=":"id_ma21KLsmaslopask912Aa2"}}'
            date_filter:
              summary: Filtrar por fecha de firma
              value: '{"created_at":{">":"2024-01-01T00:00:00"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Documentos firmados encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedDocumentList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  '/signed_documents/{id}':
    get:
      tags:
        - Signed documents
      summary: Obtener un documento firmado.
      description: Obtiene los detalles de un documento firmado.
      operationId: getSignedDocument
      parameters:
        - name: id
          in: path
          description: ID del documento firmado
          required: true
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Document firmado encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/SignedDocument'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /evidences:
    get:
      tags:
        - Agreements
      summary: Obtener todas las evidencias
      description: Retorna la lista completa de evidencias de todos los acuerdos de la compañía. Útil para auditorías o gestión centralizada de evidencias.
      operationId: getAllEvidences
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
        - name: where
          in: query
          description: 'Filtros en formato JSON. Permite combinar condiciones como `id`, `legal_basis` o rangos de `created_at`.'
          required: false
          schema:
            type: string
          examples:
            id_filter:
              summary: Filtrar por ID de evidencia
              value: '{"id":{"=":"evd_pNMroI2OEfrDNdi8xT6kOQ"}}'
            legal_basis_filter:
              summary: Filtrar por base legal
              value: '{"legal_basis":{"=":"consent"}}'
            date_filter:
              summary: Filtrar por fecha de creación
              value: '{"created_at":{">":"2024-01-01T00:00:00"}}'
      responses:
        '200':
          description: Evidencias encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  /agreements:
    get:
      tags:
        - Agreements
      summary: Obtener todos los acuerdos
      description: Retorna la lista de todos los acuerdos en su última versión.
      operationId: indexAgreements
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            user_reference_filter:
              summary: Filtrar por `user_reference`
              value: '{"user_reference":{"=":"user_123"}}'
            entity_filter:
              summary: Filtrar por entidad
              value: '{"entity_id":{"=":"ent_cYTjMLgWE3MvUa3RKwgXEg"}}'
            identity_filter:
              summary: Filtrar por identidad
              value: '{"identity_id":{"=":"id_ma21KLsmaslopask912Aa2"}}'
            data_use_filter:
              summary: |
                Filtrar por finalidad del dato. Retorna los agreements que incluyen al menos uno de los valores proporcionados.
                Si se proporciona una categoría general (e.g. `essential`), se incluyen los casos más específicos (e.g. `essential.service`).
              value: '{"data_uses":{"in":["analytics", "marketing"]}}'
            data_category:
              summary: |
                Filtrar por categoría del dato. Retorna los agreements que incluyen al menos uno de los valores proporcionados.
                Si se proporciona una categoría general (e.g. `user.name`), se incluyen los casos más específicos (e.g. `user.name.first`).
              value: '{"data_categories":{"in":["user.name", "user.contact.email"]}}'
            date_filter:
              summary: Filtrar por fecha de creación
              value: '{"created_at":{">":"2024-01-01T00:00:00"}}'
            combined_filter:
              summary: Filtros combinados
              value: '{"status":{"=":"active"},"created_at":{">":"2024-01-01T00:00:00"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Acuerdos encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgreementList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}':
    get:
      tags:
        - Agreements
      summary: Obtener un acuerdo específico
      description: Retorna los detalles de un acuerdo en su última versión.
      operationId: getAgreement
      parameters:
        - name: id
          in: path
          description: ID del acuerdo a buscar
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Acuerdo encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  agreement:
                    $ref: '#/components/schemas/Agreement'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/evidences':
    get:
      tags:
        - Agreements
      summary: Obtener todas las evidencias de un acuerdo
      description: Retorna la lista de evidencias asociadas a un acuerdo específico.
      operationId: getAgreementEvidences
      parameters:
        - name: id
          in: path
          description: ID del acuerdo
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Evidencias encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/evidences/{evidenceId}':
    get:
      tags:
        - Agreements
      summary: Obtener una evidencia específica de un acuerdo
      description: Retorna los detalles de una evidencia específica asociada a un acuerdo.
      operationId: getAgreementEvidence
      parameters:
        - name: id
          in: path
          description: ID del acuerdo
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - name: evidenceId
          in: path
          description: ID de la evidencia
          required: true
          schema:
            type: string
          example: ev_2C3N3Z9BthUqhBnZ8QiDgj
      responses:
        '200':
          description: Evidencia encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  evidence:
                    $ref: '#/components/schemas/Evidence'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/evidences/{evidenceId}/download':
    get:
      tags:
        - Agreements
      summary: Descargar el archivo de una evidencia específica
      description: Permite descargar el archivo asociado a una evidencia específica de un acuerdo. Es útil en caso de auditoría o querer demostrar en formato PDF que el acuerdo tuvo un cambio.
      operationId: downloadAgreementEvidence
      parameters:
        - name: id
          in: path
          description: ID del agreement
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - name: evidenceId
          in: path
          description: ID de la evidencia
          required: true
          schema:
            type: string
          example: ev_2C3N3Z9BthUqhBnZ8QiDgj
      responses:
        '200':
          description: Archivo en formato PDF de evidencia
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="name.pdf"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/versions':
    get:
      tags:
        - Agreements
      summary: Obtener todas las versiones de un acuerdo
      description: Retorna la lista de versiones asociadas a un acuerdo específico.
      operationId: getAgreementVersions
      parameters:
        - name: id
          in: path
          description: ID del acuerdo
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Versiones encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgreementList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/versions/{versionNumber}':
    get:
      tags:
        - Agreements
      summary: Obtener una versión específica de un acuerdo
      description: Retorna los detalles de una versión específica de un acuerdo.
      operationId: getAgreementVersion
      parameters:
        - name: id
          in: path
          description: ID del acuerdo
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - name: versionNumber
          in: path
          description: Número de versión
          required: true
          schema:
            type: string
          example: '1'
      responses:
        '200':
          description: Versión encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    $ref: '#/components/schemas/Agreement'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/agreements/{id}/versions/{versionNumber}/evidence':
    get:
      tags:
        - Agreements
      summary: Obtener la evidencia de una versión específica
      description: Retorna la evidencia asociada a una versión específica de un acuerdo.
      operationId: getAgreementVersionEvidence
      parameters:
        - name: id
          in: path
          description: ID del acuerdo
          required: true
          schema:
            type: string
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        - name: versionNumber
          in: path
          description: Número de versión
          required: true
          schema:
            type: string
          example: '1'
      responses:
        '200':
          description: Evidencia encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  evidence:
                    $ref: '#/components/schemas/Evidence'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  /consent_actions:
    post:
      tags:
        - Consent actions
      summary: Crear un consent action
      description: |
        Crea un nuevo consent action. Debes proporcionar al menos uno de los siguientes parámetros: `user_reference` o `entity_id`.
        - Si solo envías `user_reference`, se intentará buscar una entidad con dicho identificador y si no, se creará una.
        - Si solo envías `entity_id`, se usará la entidad existente.
        - Si envías ambos, se prioriza el `entity_id`. El `user_reference` solo se utiliza si no se entrega `entity_id`.

        El alcance efectivo de la acción se define en el `action_token`:
        - si el token incluye `selected_scopes`, se aplica solo a ese subconjunto
        - si no incluye `selected_scopes`, se aplica a todos los scopes del template
      operationId: createConsentAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action_token
              properties:
                action_token:
                  type: string
                  description: Token JWT de la acción de consentimiento
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                user_reference:
                  type: string
                  description: 'Referencia del usuario. Requerido si no se proporciona `entity_id`. Si se envía junto a `entity_id`, este último se prioriza.'
                  example: '1234567890'
                entity_id:
                  type: string
                  description: 'ID de la entidad existente. Requerido si no se proporciona `user_reference`. Si se envía junto a `user_reference`, se usará el `entity_id` para resolver la entidad.'
                  example: ent_1234567890
                consent_method:
                  $ref: '#/components/schemas/EvidenceConsentMethod'
      responses:
        '201':
          description: Consent action creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAction'
        '400':
          description: 'Error de solicitud: falta la información mínima o los identificadores no coinciden con una entidad válida'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        example: invalid_request_error
                      title:
                        type: string
                        example: Bad Request
                      status:
                        type: integer
                        example: 400
                      detail:
                        type: string
                        examples:
                          - Either user_reference or entity_id is required
                          - Entity not found or does not belong to company
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.actions.write
          - consent.api.manage
      security:
        - api_key: []
    get:
      tags:
        - Consent actions
      summary: Listar consent actions
      operationId: indexConsentActions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
        - $ref: '#/components/parameters/ExpandParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            entity_filter:
              summary: Filtrar por entidad
              value: '{"entity_id":{"=":"ent_cYTjMLgWE3MvUa3RKwgXEg"}}'
            consent_template_filter:
              summary: Filtrar por template de consentimiento
              value: '{"consent_template_id":{"=":"ctmpl_cYTjMLgWE3MvUa3RKwgXEg"}}'
      responses:
        '200':
          description: Lista de consent actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_actions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsentAction'
                  metadata:
                    $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
            text/csv:
              schema:
                type: string
                description: 'Datos de consent actions en formato CSV con campos básicos como ID, versión del template y relaciones expandidas si se solicitan'
                example: |
                  id,user_reference,consent_template_token,consent_template_name,consent_template_version,created_at,updated_at
                  consact_abc123,user_456,ctmpl_def789,Consentimiento de marketing,2,2024-01-15T10:30:00Z,2024-01-15T10:30:00Z
                  consact_xyz987,user_654,ctmpl_ghi321,Consentimiento de análisis,1,2024-01-14T09:15:00Z,2024-01-14T09:15:00Z
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '413':
          description: Exportación CSV sincrónica demasiado grande
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: CSV export too large
                  status:
                    type: integer
                    example: 413
                  detail:
                    type: string
                    example: Synchronous CSV exports support up to 5000 records. Use /exports for larger exports.
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.actions.read
          - consent.api.manage
      security:
        - api_key: []
  '/consent_actions/{id}':
    get:
      tags:
        - Consent actions
      summary: Obtener un consent action
      operationId: showConsentAction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Id del consent action
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
        - $ref: '#/components/parameters/ExpandParam'
      responses:
        '200':
          description: Consent action encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_action:
                    $ref: '#/components/schemas/ConsentAction'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.actions.read
          - consent.api.manage
      security:
        - api_key: []
  /consent_revocations:
    post:
      tags:
        - Consent revocations
      summary: Crear una revocación de consentimiento iniciada por la empresa
      description: |
        Revoca permisos de consentimiento por lógica de negocio de la empresa (por ejemplo, fin de contrato u obligación).
        Esta operación no representa un clic del usuario y crea un registro `CompanyConsentRevocation` como fuente de versión.

        Reglas principales:
        - El `consent_template` debe tener `duration_type=conditional`.
        - El template debe tener `revocable_data_uses` configurado.
        - `selected_scopes`, si se envía, debe ser subconjunto de los scopes del template.
        - Si no hay permisos efectivamente revocables, responde exitosamente con estado `no_changes`.
      operationId: createConsentRevocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRevocationCreateInput'
      responses:
        '200':
          description: Evento idempotente ya procesado previamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_revocation:
                    $ref: '#/components/schemas/CompanyConsentRevocation'
        '201':
          description: Revocación creada y procesada
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_revocation:
                    $ref: '#/components/schemas/CompanyConsentRevocation'
        '400':
          description: Error de parámetros del request
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Invalid parameter
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: 'Either identity_id, entity_id or user_reference is required'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación de guardrails de revocación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  '/consent_revocations/{id}':
    get:
      tags:
        - Consent revocations
      summary: Obtener una revocación de consentimiento iniciada por la empresa
      operationId: showConsentRevocation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Identificador de revocación
          example: ccrev_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Revocación encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_revocation:
                    $ref: '#/components/schemas/CompanyConsentRevocation'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - api_key: []
  /consent_commits:
    get:
      tags:
        - Consent commits
      summary: Listar commits de consentimiento
      operationId: indexConsentCommits
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Número de página
          example: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
          description: Elementos por página
          example: 20
        - name: order_by
          in: query
          required: false
          schema:
            type: string
          description: Campo y dirección de ordenamiento
          example: created_at DESC
      responses:
        '200':
          description: Lista de consent commits
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_commits:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsentCommit'
                  metadata:
                    $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '413':
          description: Exportación CSV sincrónica demasiado grande
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: CSV export too large
                  status:
                    type: integer
                    example: 413
                  detail:
                    type: string
                    example: Synchronous CSV exports support up to 5000 records. Use /exports for larger exports.
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.commits.read
          - consent.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Consent commits
      summary: Crear un commit de consentimiento
      description: |
        Crea un nuevo commit de consentimiento basado en los actions tokens. Cada action token representa una checkbox de
        consentimiento específico que el usuario ha marcado a través de nuestro módulo de consentimiento.

        Debes proporcionar **al menos uno** de los siguientes parámetros: `user_reference` o `entity_id`.
        - Si solo envías `user_reference`, buscaremos la entidad asociada y, si no existe, la crearemos automáticamente.
        - Si solo envías `entity_id`, usaremos la entidad existente y leeremos su `user_reference`.
        - Si envías ambos, se prioriza el `entity_id`. El `user_reference` solo se usa cuando no se proporciona `entity_id`.

        Cada `action_token` puede incluir `selected_scopes` para otorgar/revocar solo parte de los scopes del template.
      operationId: createConsentCommit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - consent_actions
              properties:
                user_reference:
                  type: string
                  description: 'Referencia para identificar al usuario en tu sistema. Requerido si no se proporciona `entity_id`. Si se envía junto a `entity_id`, este último se prioriza.'
                  example: user_123
                consent_actions:
                  type: array
                  description: Array de tokens que representan las acciones de consentimiento realizadas por el usuario
                  items:
                    type: object
                    properties:
                      action_token:
                        type: string
                        description: Token JWT de la acción de consentimiento
                        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zZW50X2lkIjoiY3RwbF8xMjM0NTY3ODkwIiwiZW50aXR5X2lkIjoiZW50XzVGNlE2QzJFd2tYdGtFcEIxVGxHamsiLCJpYXQiOjE1MTYyMzkwMjJ9.4p3gYtKmXkHWDyEA9L4ywJRBpVFWxG7pdq8LHbJhxvE
                  example:
                    - action_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zZW50X2lkIjoiY3RwbF8xMjM0NTY3ODkwIiwiZW50aXR5X2lkIjoiZW50XzVGNlE2QzJFd2tYdGtFcEIxVGxHamsiLCJpYXQiOjE1MTYyMzkwMjJ9.4p3gYtKmXkHWDyEA9L4ywJRBpVFWxG7pdq8LHbJhxvE
                    - action_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zZW50X2lkIjoiY3RwbF85ODc2NTQzMjEwIiwiZW50aXR5X2lkIjoiZW50XzVGNlE2QzJFd2tYdGtFcEIxVGxHamsiLCJpYXQiOjE1MTYyMzkwMjJ9.8vkoM1VO5Kp6Udz9ISFnU7YD7HcGYt9yCUuZGrYPe2s
                entity_id:
                  type: string
                  description: 'ID de la entidad existente. Requerido si no se proporciona `user_reference`. Si se envía junto a `user_reference`, la entidad se resuelve usando este `entity_id`.'
                  example: ent_5F6Q6C2EwkXtkEpB1TlGjk
                consent_method:
                  $ref: '#/components/schemas/EvidenceConsentMethod'
      responses:
        '201':
          description: Commit de consentimiento creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_commit:
                    $ref: '#/components/schemas/ConsentCommit'
        '400':
          description: Error de solicitud - validación XOR fallida o entidad no encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        example: invalid_request_error
                      title:
                        type: string
                        example: Bad Request
                      status:
                        type: integer
                        example: 400
                      detail:
                        type: string
                        examples:
                          - 'Provide either user_reference or entity_id, not both'
                          - Either user_reference or entity_id is required
                          - Entity not found or does not belong to company
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.commits.write
          - consent.api.manage
      security:
        - api_key: []
  '/consent_commits/{id}':
    get:
      tags:
        - Consent commits
      summary: Obtener un commit de consentimiento
      operationId: showConsentCommit
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Id del commit de consentimiento
          example: ccom_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Commit de consentimiento encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_commit:
                    $ref: '#/components/schemas/ConsentCommit'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.commits.read
          - consent.api.manage
      security:
        - api_key: []
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: Obtener todos los webhooks
      operationId: indexWebhooks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Webhooks encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.read
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.read
      security:
        - api_key: []
    post:
      tags:
        - Webhooks
      summary: Crear un webhook
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - url
                - subscriptions
              properties:
                name:
                  type: string
                  description: Nombre del webhook
                  example: My Webhook
                url:
                  type: string
                  description: URL donde se enviarán los eventos
                  example: 'https://company.com/your-webhook-endpoint'
                subscriptions:
                  type: array
                  description: |
                    Lista de eventos a los que se suscribirá el webhook. Usa '*' para suscribirse a todos los eventos. También puedes suscribirte a eventos específicos de un recurso usando el patrón de wildcard, por ejemplo: `identity.*` suscribirá a todos los eventos del recurso identity.
                  items:
                    type: string
                  example:
                    - '*'
                    - auth_attempt.*
                    - validation_attempt.*
                enabled_modes:
                  type: array
                  description: 'Lista de modos en los que el webhook estará habilitado. Si no se especifica, se usará el modo actual.'
                  items:
                    type: string
                  example:
                    - production
                    - sandbox
                enabled:
                  type: boolean
                  description: Indica si el webhook está habilitado o no
                  default: true
                  example: true
                secret_key:
                  type: string
                  description: 'Llave secreta para el webhook. Se utiliza para verificar la autenticidad del webhook a través de nuestros headers de seguridad. En caso de que no estar presente, se genera una llave aleatoria.'
                  default: 32 char autgenerated string
                  example: my_secret_key
      responses:
        '201':
          description: Webhook creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.write
      security:
        - api_key: []
  '/webhooks/{id}':
    get:
      tags:
        - Webhooks
      summary: Obtener un webhook específico
      operationId: getWebhook
      parameters:
        - name: id
          in: path
          description: Id del webhook
          required: true
          schema:
            type: string
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Webhook encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.read
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.read
      security:
        - api_key: []
    patch:
      tags:
        - Webhooks
      summary: Actualizar un webhook
      operationId: updateWebhook
      parameters:
        - name: id
          in: path
          description: Id del webhook
          required: true
          schema:
            type: string
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: URL donde se enviarán los eventos
                  example: 'https://company.com/your-webhook-endpoint'
                subscriptions:
                  type: array
                  description: |
                    Lista de eventos a los que se suscribirá el webhook. Usa '*' para suscribirse a todos los eventos. También puedes suscribirte a eventos específicos de un recurso usando el patrón de wildcard, por ejemplo: `identity.*` suscribirá a todos los eventos del recurso identity.
                  items:
                    type: string
                  example:
                    - '*'
                    - identity.created
                    - validation_attempt.*
                enabled_modes:
                  type: array
                  description: Lista de modos en los que el webhook estará habilitado
                  items:
                    type: string
                  example:
                    - production
                    - sandbox
                enabled:
                  type: boolean
                  description: Indica si el webhook está habilitado o no
                  example: true
                secret_key:
                  type: string
                  description: 'Llave secreta para el webhook. Se utiliza para verificar la autenticidad del webhook a través de nuestros headers de seguridad. En caso de que no estar presente, se genera una llave aleatoria.'
                  default: 32 char autgenerated string
                  example: my_secret_key
      responses:
        '200':
          description: Webhook actualizado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.write
      security:
        - api_key: []
    delete:
      tags:
        - Webhooks
      summary: Eliminar un webhook
      operationId: deleteWebhook
      parameters:
        - name: id
          in: path
          description: Id del webhook
          required: true
          schema:
            type: string
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '204':
          description: Webhook eliminado exitosamente
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.write
      security:
        - api_key: []
  '/webhooks/{webhook_id}/transactions':
    get:
      tags:
        - Webhooks
      summary: Obtener todas las transacciones de un webhook específico
      operationId: indexWebhookTransactions
      parameters:
        - name: webhook_id
          in: path
          description: ID del webhook
          required: true
          schema:
            type: string
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Transacciones del webhook encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTransactionList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.read
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.read
      security:
        - api_key: []
  '/webhooks/{webhook_id}/transactions/{id}':
    get:
      tags:
        - Webhooks
      summary: Obtener una transacción específica de un webhook
      operationId: getWebhookTransaction
      parameters:
        - name: webhook_id
          in: path
          description: ID del webhook
          required: true
          schema:
            type: string
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
        - name: id
          in: path
          description: ID de la transacción del webhook
          required: true
          schema:
            type: string
          example: whtx_1B2M2Y8AsgTpgAmY7PhCde
      responses:
        '200':
          description: Transacción del webhook encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_transaction:
                    $ref: '#/components/schemas/WebhookTransaction'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - webhooks.dashboard.read
          - webhooks.dashboard.write
        api_any_of:
          - webhooks.api.read
      security:
        - api_key: []
  /products:
    get:
      tags:
        - Products
      summary: Obtener todos los productos
      operationId: indexProducts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Productos encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Products
      summary: Crear un producto
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Nombre del producto
                  example: Mi Producto
                display_name:
                  type: string
                  description: Nombre comercial visible del producto.
                  example: Cuenta Corriente Plus
                branch_id:
                  type: string
                  description: Identificador único de la branch
                  example: branch_1B2M2Y8AsgTpgAmY7PhCfg
                redec_kind:
                  type: string
                  description: Objetivo de REDEC del producto
                  enum:
                    - commercial_credits
                    - consumer_credits
                    - housing_credits
                    - financial_operations
                    - acquired_debt_instruments
                    - contingent_credits
                    - freely_available_credit_line_limits
      responses:
        '201':
          description: Producto creado
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/products/{id}':
    get:
      tags:
        - Products
      summary: Obtener la última versión de un producto específico
      operationId: getProduct
      parameters:
        - name: id
          in: path
          description: Id del producto
          required: true
          schema:
            type: string
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Última versión del producto encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Products
      summary: Actualizar un producto
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Nombre del producto
                  example: Nuevo nombre de producto
                branch_id:
                  type: string
                  nullable: true
                  description: Identificador único de la branch. Enviar `null` para desasociar la branch.
                  example: branch_1B2M2Y8AsgTpgAmY7PhCfg
                redec_kind:
                  type: string
                  description: Objetivo de REDEC del producto
                  enum:
                    - commercial_credits
                    - consumer_credits
                    - housing_credits
                    - financial_operations
                    - acquired_debt_instruments
                    - contingent_credits
                    - freely_available_credit_line_limits
      responses:
        '200':
          description: Producto actualizado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/products/{id}/versions':
    get:
      tags:
        - Products
      summary: Obtener todas las versiones de un producto
      operationId: indexProductVersions
      parameters:
        - name: id
          in: path
          required: true
          description: ID del producto
          schema:
            type: string
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Versiones del producto encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/products/{id}/versions/{version_id}':
    get:
      tags:
        - Products
      summary: Obtener una versión específica de un producto
      operationId: getProductVersion
      parameters:
        - name: id
          in: path
          required: true
          description: ID del producto
          schema:
            type: string
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        - name: version_id
          in: path
          required: true
          description: Número de versión del producto
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Versión específica del producto encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  /entities:
    get:
      tags:
        - Entities
      summary: Obtener todas las entidades
      description: Retorna la lista de todas las entidades de tu empresa.
      operationId: indexEntities
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            user_reference_filter:
              summary: Filtrar por user_reference exacto
              value: '{"user_reference":{"=":"user_123"}}'
            user_reference_in_filter:
              summary: Filtrar por múltiples user_reference
              value: '{"user_reference":{"in":["user_123", "user_456"]}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Entidades encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Entities
      summary: Crear una entidad
      description: Crea una nueva entidad asociada a tu empresa
      operationId: createEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_reference:
                  type: string
                  description: Identificador único del usuario en tu sistema.
                  example: user_123
      responses:
        '201':
          description: Entidad creada
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/entities/{id}':
    get:
      tags:
        - Entities
      summary: Obtener una entidad específica
      description: Retorna los detalles de una entidad específica.
      operationId: getEntity
      parameters:
        - name: id
          in: path
          description: ID de la entidad a buscar
          required: true
          schema:
            type: string
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Entidad encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/entities/{id}/agreement/compliance_statuses':
    get:
      tags:
        - Entities
      summary: Obtener los estados de cumplimiento de la entidad
      description: |
        Retorna una lista de estados de cumplimiento de la entidad respecto a los templates de consentimiento que tienes en tu empresa. Utiliza el último estado del agreement para evaluar si es que cumple o no cumple.
      operationId: getEntityAgreementComplianceStatuses
      parameters:
        - name: id
          in: path
          description: ID de la entidad
          required: true
          schema:
            type: string
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        - name: where
          in: query
          description: 'Filtros en formato JSON. Por ahora, damos soporte para filtros de igualdad con `consent_template_id`, `consent_template_version` y `data_subject`. Cuando envíes `consent_template_version`, también debes enviar `consent_template_id`, y el valor debe ser mayor a 0.'
          required: false
          schema:
            type: string
          examples:
            consent_template_id_filter:
              summary: Filtrar por `consent_template_id`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"}}'
            consent_template_version_filter:
              summary: Filtrar por `consent_template_id` y `consent_template_version`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"},"consent_template_version":{"=":2}}'
            data_subject_filter:
              summary: Filtrar por `data_subject`
              value: '{"data_subject":{"=":"prospect"}}'
            consent_template_id_and_data_subject_filter:
              summary: Filtrar por `consent_template_id` y `data_subject`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"},"data_subject":{"=":"prospect"}}'
      responses:
        '200':
          description: Todos los estados de cumplimiento de la entidad.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityComplianceStatusesResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'Recurso no encontrado. Se puede dar cuando no existe un agreement entre tu empresa y la entidad en cuestión, o cuando la entidad no existe.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorSchema'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/entities/reference/{user_reference}/agreement/compliance_statuses':
    get:
      tags:
        - Entities
      summary: Obtener los estados de cumplimiento de una entidad usando user_reference
      description: |
        Retorna la misma información que el endpoint basado en el `id` de la entidad, pero permite identificar a la entidad
        utilizando el `user_reference` con el que fue registrada para tu empresa.

        Este endpoint **no crea** entidades nuevas. Si el `user_reference` no corresponde a una entidad existente en tu empresa,
        devolverá un error 404.
      operationId: getEntityAgreementComplianceStatusesByReference
      parameters:
        - name: user_reference
          in: path
          description: user_reference asociado a la entidad dentro de tu empresa
          required: true
          schema:
            type: string
          example: external-user-123
        - name: where
          in: query
          description: 'Filtros en formato JSON. Por ahora, damos soporte para filtros de igualdad con `consent_template_id`, `consent_template_version` y `data_subject`. Cuando envíes `consent_template_version`, también debes enviar `consent_template_id`, y el valor debe ser mayor a 0.'
          required: false
          schema:
            type: string
          examples:
            consent_template_id_filter:
              summary: Filtrar por `consent_template_id`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"}}'
            consent_template_version_filter:
              summary: Filtrar por `consent_template_id` y `consent_template_version`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"},"consent_template_version":{"=":2}}'
            data_subject_filter:
              summary: Filtrar por `data_subject`
              value: '{"data_subject":{"=":"prospect"}}'
            consent_template_id_and_data_subject_filter:
              summary: Filtrar por `consent_template_id` y `data_subject`
              value: '{"consent_template_id":{"=":"constpl_7vH0nGSOnP9inT-1EsBP0g"},"data_subject":{"=":"prospect"}}'
      responses:
        '200':
          description: Todos los estados de cumplimiento del sujeto encontrado por user_reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityComplianceStatusesResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'Recurso no encontrado. Se puede dar cuando no existe un agreement entre tu empresa y la entidad encontrada por user_reference, cuando no existe la entidad, o cuando el user_reference no pertenece a tu empresa.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorSchema'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/entities/reference/{user_reference}/session_token':
    get:
      tags:
        - Entities
      summary: Obtener un token de sesión usando el user_reference de la entidad
      description: |
        Igual que el endpoint anterior, pero identificando la entidad por su `user_reference` registrado en tu empresa.

        Si no existe una entidad con ese `user_reference`, crearemos automáticamente una entidad para tu empresa antes de generar el token.
      operationId: getEntitySessionTokenByReference
      parameters:
        - name: user_reference
          in: path
          description: user_reference asociado a la entidad dentro de tu empresa
          required: true
          schema:
            type: string
          example: external-user-123
      responses:
        '200':
          description: Token generado exitosamente (se reutiliza la entidad existente o se crea una nueva si no existía)
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Token JWT para acceder a endpoints con alcance de entidad
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55X2lkIjoiY29tcF8xMjM0NTY3ODkwIiwiZW50aXR5X2lkIjoiZW50XzFCMk0yWThBc2dUcGdBbVk3UGhDZmciLCJzY29wZSI6WyIvZW50aXRpZXMvKiJdLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTUxNjI0MDAyMn0.example
        '400':
          description: Error de solicitud - falta la información requerida
          content:
            application/json:
              schema:
                $ref: '#/components/responses/NotFoundError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - api_key: []
  '/entities/{token}/session_token':
    get:
      tags:
        - Entities
      summary: Obtener un token de sesión usando el ID de la entidad
      description: |
        Genera un token JWT con alcance de entidad especificando el `token` de la entidad. El comportamiento es equivalente
        al endpoint basado en `user_reference`, pero en este caso **no** se crean entidades nuevas: si el `token` no existe
        o no pertenece a tu empresa, devolveremos un error 404.
      operationId: getEntitySessionTokenById
      parameters:
        - name: token
          in: path
          description: ID de la entidad para la cual se generará el token
          required: true
          schema:
            type: string
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Token generado exitosamente para la entidad indicada
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Token JWT para acceder a endpoints con alcance de entidad
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Recurso no encontrado. Se puede dar cuando el ID de la entidad no existe o no pertenece a tu empresa.
          content:
            application/json:
              schema:
                $ref: '#/components/responses/NotFoundError'
      security:
        - api_key: []
  /entities/data_subject_requests:
    get:
      tags:
        - Entities
      summary: Obtener todas las solicitudes de ejercicio de derechos de una entidad
      description: |
        Retorna una lista de todas las solicitudes de ejercicio de derechos (data subject requests) que pertenecen a la entidad autenticada.
      operationId: indexEntityDataSubjectRequests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Data subject requests encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequestList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - entity_session_token: []
  '/entities/data_subject_requests/{token}':
    get:
      tags:
        - Entities
      summary: Obtener una solicitud de ejercicio de derechos específica de una entidad
      description: |
        Retorna los detalles de una solicitud de ejercicio de derechos específica que pertenece a la entidad autenticada.
      operationId: getEntityDataSubjectRequest
      parameters:
        - name: token
          in: path
          description: Token del data subject request a buscar
          required: true
          explode: true
          schema:
            type: string
          example: dsreq_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Data subject request encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSubjectRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - entity_session_token: []
  /config:
    get:
      tags:
        - Configuration
      summary: Obtener la configuración de la empresa
      description: |
        Retorna los parámetros configurables de la empresa, como los canales de contacto para que tus usuarios puedan ejercer sus derechos.
      operationId: getCompanyConfig
      responses:
        '200':
          description: Configuración obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    $ref: '#/components/schemas/Configuration'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar la configuración de la empresa
      operationId: updateCompanyConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        '200':
          description: Configuración actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    $ref: '#/components/schemas/Configuration'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /ui_config:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de UI
      description: |
        Retorna la configuración mínima necesaria para renderizar elementos visuales del dashboard.
        Este endpoint es de solo lectura y está disponible para usuarios autenticados del dashboard.
      operationId: getUiConfig
      responses:
        '200':
          description: Configuración de UI obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  ui_config:
                    $ref: '#/components/schemas/UIConfiguration'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      security:
        - api_key: []
  /config/general:
    get:
      tags:
        - Configuration
      summary: Obtener configuración general
      operationId: getGeneralConfig
      responses:
        '200':
          description: Configuración general obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
                    properties:
                      alert_notification_email:
                        type: string
                      icon_variant:
                        type: string
                        enum:
                          - duotone
                          - outline
                          - solid
                      default_color:
                        type: string
                        nullable: true
                      whitelisted_domains:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración general
      operationId: updateGeneralConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alert_notification_email:
                  type: string
                icon_variant:
                  type: string
                default_color:
                  type: string
                  nullable: true
                whitelisted_domains:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Configuración general actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
                    properties:
                      alert_notification_email:
                        type: string
                      icon_variant:
                        type: string
                        enum:
                          - duotone
                          - outline
                          - solid
                      default_color:
                        type: string
                        nullable: true
                      whitelisted_domains:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /config/dashboard:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de dashboard
      operationId: getDashboardConfig
      responses:
        '200':
          description: Configuración de dashboard obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
                    properties:
                      auth_methods:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de dashboard
      operationId: updateDashboardConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                auth_methods:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Configuración de dashboard actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
                    properties:
                      auth_methods:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /config/validation:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de validación
      operationId: getValidationConfig
      responses:
        '200':
          description: Configuración de validación obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de validación
      operationId: updateValidationConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                liveness_check:
                  type: boolean
                id_scan_check:
                  type: boolean
                government_check:
                  type: boolean
                ephemeral_transaction_data:
                  type: boolean
      responses:
        '200':
          description: Configuración de validación actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /config/disclosure:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de disclosure
      operationId: getDisclosureConfig
      responses:
        '200':
          description: Configuración de disclosure obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.write
          - disclosure.dashboard.config
          - disclosure.dashboard.manage
          - config.manage
        api_any_of:
          - disclosure.api.config
          - disclosure.api.manage
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de disclosure
      operationId: updateDisclosureConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                liveness_check:
                  type: boolean
                id_scan_check:
                  type: boolean
                government_check:
                  type: boolean
                skip_passkey_registration:
                  type: boolean
      responses:
        '200':
          description: Configuración de disclosure actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.config
          - disclosure.dashboard.manage
          - config.manage
        api_any_of:
          - disclosure.api.config
          - disclosure.api.manage
          - config.api.manage
      security:
        - api_key: []
  /config/consent:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de consent
      operationId: getConsentConfig
      responses:
        '200':
          description: Configuración de consent obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.write
          - consent.dashboard.config
          - consent.dashboard.manage
          - config.manage
        api_any_of:
          - consent.api.config
          - consent.api.manage
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de consent
      operationId: updateConsentConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                whitelisted_domains:
                  type: array
                  items:
                    type: string
                label_display:
                  type: string
                mandatory_label_text:
                  type: string
                redec_enabled:
                  type: boolean
                redec_automatic_rdc30:
                  type: boolean
      responses:
        '200':
          description: Configuración de consent actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.config
          - consent.dashboard.manage
          - config.manage
        api_any_of:
          - consent.api.config
          - consent.api.manage
          - config.api.manage
      security:
        - api_key: []
  /config/privacy_center:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de Privacy Center
      operationId: getPrivacyCenterConfig
      responses:
        '200':
          description: Configuración de Privacy Center obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de Privacy Center
      operationId: updatePrivacyCenterConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_email:
                  type: string
                public_url:
                  type: string
                private_url:
                  type: string
      responses:
        '200':
          description: Configuración de Privacy Center actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /config/data_subject_request:
    get:
      tags:
        - Configuration
      summary: Obtener configuración de data subject request
      operationId: getDataSubjectRequestConfig
      responses:
        '200':
          description: Configuración de data subject request obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.read
          - dsr.dashboard.write
          - dsr.dashboard.config
          - dsr.dashboard.manage
          - config.manage
        api_any_of:
          - dsr.api.config
          - dsr.api.manage
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Configuration
      summary: Actualizar configuración de data subject request
      operationId: updateDataSubjectRequestConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mandatory_validation:
                  type: boolean
                disable_informative_emails:
                  type: boolean
                disable_functional_emails:
                  type: boolean
                redec_automatic_rdc40:
                  type: boolean
                liveness_check:
                  type: boolean
                id_scan_check:
                  type: boolean
                government_check:
                  type: boolean
                validation_timeout_period:
                  type: string
                allow_many_data_categories_mutations:
                  type: boolean
                contact_field_configs:
                  type: array
                  items:
                    type: object
                blacklisted_data_categories:
                  type: array
                  items:
                    type: string
                appliable_scopes:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Configuración de data subject request actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      x-permissions:
        dashboard_any_of:
          - dsr.dashboard.config
          - dsr.dashboard.manage
          - config.manage
        api_any_of:
          - dsr.api.config
          - dsr.api.manage
          - config.api.manage
      security:
        - api_key: []
  /branches:
    get:
      tags:
        - Branches
      summary: Obtener todas las branches
      description: |
        Cada branch representa una unidad de negocio dentro de tu empresa. Puede ser una sucursal, un área de negocio, etc.
      operationId: indexBranches
      responses:
        '200':
          description: Branches encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Branches
      summary: Crear una branch
      operationId: createBranch
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                tin:
                  type: string
                  description: Número de identificación tributaria de la branch.
                  example: 12.345.678-9
                legal_company_name:
                  type: string
                  description: Nombre legal de la branch.
                  example: Sucursal de la empresa
                display_name:
                  type: string
                  description: Nombre comercial visible de la branch.
                  example: Sucursal Centro
      responses:
        '201':
          description: Branch creada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_branch:
                    $ref: '#/components/schemas/Branch'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/branches/{id}':
    get:
      tags:
        - Branches
      summary: Obtener una branch específica
      operationId: getBranch
      parameters:
        - name: id
          in: path
          description: ID de la _branch_
          required: true
          schema:
            type: string
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Branch encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_branch:
                    $ref: '#/components/schemas/Branch'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Branches
      summary: Actualizar una branch
      operationId: updateBranch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tin:
                  type: string
                  description: Número de identificación tributaria de la branch
                  example: 12.345.678-9
                legal_company_name:
                  type: string
                  description: Nombre legal de la branch
                  example: Sucursal de la empresa
                display_name:
                  type: string
                  description: Nombre comercial visible de la branch.
                  example: Sucursal Centro
      responses:
        '200':
          description: Branch actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_branch:
                    $ref: '#/components/schemas/Branch'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  /api_keys:
    get:
      tags:
        - API Keys
      summary: Obtener todas las claves API
      operationId: indexApiKeys
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Claves API encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.read
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.read
          - api_keys.api.write
      security:
        - api_key: []
    post:
      tags:
        - API Keys
      summary: Crear una nueva API key
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_key:
                  $ref: '#/components/schemas/ApiKeyInput'
      responses:
        '201':
          description: API key creada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - Label can't be blank
                          - Label is too long (maximum is 100 characters)
                          - Expires in days must be greater than 0
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.write
      security:
        - api_key: []
  /roles:
    get:
      tags:
        - Roles
      summary: Obtener roles de la compañía
      operationId: indexRoles
      responses:
        '200':
          description: Roles encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.read
          - users.dashboard.manage
        api_any_of:
          - roles.api.read
          - roles.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Roles
      summary: Crear un rol
      operationId: createRole
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  $ref: '#/components/schemas/RoleInput'
      responses:
        '201':
          description: Rol creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - roles.api.write
          - roles.api.manage
      security:
        - api_key: []
  '/roles/{token}':
    get:
      tags:
        - Roles
      summary: Obtener un rol
      operationId: getRole
      parameters:
        - name: token
          in: path
          required: true
          description: Token del rol
          schema:
            type: string
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Rol encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.read
          - users.dashboard.manage
        api_any_of:
          - roles.api.read
          - roles.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Roles
      summary: Actualizar un rol
      operationId: updateRole
      parameters:
        - name: token
          in: path
          required: true
          description: Token del rol
          schema:
            type: string
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  $ref: '#/components/schemas/RoleInput'
      responses:
        '200':
          description: Rol actualizado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - roles.api.write
          - roles.api.manage
      security:
        - api_key: []
    delete:
      tags:
        - Roles
      summary: Eliminar un rol
      operationId: deleteRole
      parameters:
        - name: token
          in: path
          required: true
          description: Token del rol
          schema:
            type: string
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Rol eliminado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - roles.api.delete
          - roles.api.manage
      security:
        - api_key: []
  /company_users:
    get:
      tags:
        - Company users
      summary: Obtener usuarios de la compañía
      operationId: indexCompanyUsers
      responses:
        '200':
          description: Usuarios encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyUserList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.read
          - users.dashboard.manage
        api_any_of:
          - users.api.read
          - users.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Company users
      summary: Crear un usuario de compañía
      operationId: createCompanyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - company_user
              properties:
                company_user:
                  $ref: '#/components/schemas/CompanyUserCreateInput'
      responses:
        '201':
          description: Usuario creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_user:
                    $ref: '#/components/schemas/CompanyUser'
        '400':
          description: Error de parámetros inválidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Invalid parameter
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: role_id is invalid
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - users.api.write
          - users.api.manage
      security:
        - api_key: []
  '/company_users/{token}':
    get:
      tags:
        - Company users
      summary: Obtener un usuario de compañía
      operationId: getCompanyUser
      parameters:
        - name: token
          in: path
          required: true
          description: Token del usuario de compañía
          schema:
            type: string
          example: cusr_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Usuario encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_user:
                    $ref: '#/components/schemas/CompanyUser'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.read
          - users.dashboard.manage
        api_any_of:
          - users.api.read
          - users.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Company users
      summary: Actualizar rol de un usuario de compañía
      description: Reemplaza el rol actual por el rol indicado en `role_id`.
      operationId: updateCompanyUser
      parameters:
        - name: token
          in: path
          required: true
          description: Token del usuario de compañía
          schema:
            type: string
          example: cusr_1B2M2Y8AsgTpgAmY7PhCfg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - company_user
              properties:
                company_user:
                  $ref: '#/components/schemas/CompanyUserUpdateInput'
      responses:
        '200':
          description: Usuario actualizado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_user:
                    $ref: '#/components/schemas/CompanyUser'
        '400':
          description: Error de parámetros inválidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Invalid parameter
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: role_id is invalid
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - users.api.write
          - users.api.manage
      security:
        - api_key: []
    delete:
      tags:
        - Company users
      summary: Eliminar un usuario de compañía
      operationId: deleteCompanyUser
      parameters:
        - name: token
          in: path
          required: true
          description: Token del usuario de compañía
          schema:
            type: string
          example: cusr_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Usuario eliminado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_user:
                    $ref: '#/components/schemas/CompanyUser'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - users.dashboard.manage
        api_any_of:
          - users.api.manage
      security:
        - api_key: []
  '/api_keys/{id}':
    get:
      tags:
        - API Keys
      summary: Obtener una API key específica
      operationId: getApiKey
      parameters:
        - name: id
          in: path
          required: true
          description: Token de la API key
          schema:
            type: string
          example: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: API key encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.read
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.read
          - api_keys.api.write
      security:
        - api_key: []
    patch:
      tags:
        - API Keys
      summary: Actualizar una API key
      operationId: updateApiKey
      parameters:
        - name: id
          in: path
          required: true
          description: Token de la API key
          schema:
            type: string
          example: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_key:
                  $ref: '#/components/schemas/ApiKeyUpdateInput'
      responses:
        '200':
          description: API key actualizada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.write
      security:
        - api_key: []
    delete:
      tags:
        - API Keys
      summary: Revocar una API key
      operationId: deleteApiKey
      parameters:
        - name: id
          in: path
          required: true
          description: Token de la API key
          schema:
            type: string
          example: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: API key revocada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación - API key ya revocada
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - API key is already revoked
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.write
      security:
        - api_key: []
  '/api_keys/{id}/refresh':
    patch:
      tags:
        - API Keys
      summary: Renovar una API key
      description: Renueva una API key extendiendo su fecha de expiración y generando un nuevo refresh token. Requiere el refresh token actual para autorizar la operación.
      operationId: refreshApiKey
      parameters:
        - name: id
          in: path
          required: true
          description: Token de la API key
          schema:
            type: string
          example: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
              properties:
                api_key:
                  type: object
                  required:
                    - refresh_token
                  properties:
                    refresh_token:
                      type: string
                      description: Token de actualización actual
                      example: akrt_abc123xyz
                    expires_in_days:
                      type: integer
                      description: Número de días hasta que expire la API key (por defecto 30 días)
                      example: 60
                      minimum: 1
      responses:
        '200':
          description: API key renovada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    allOf:
                      - $ref: '#/components/schemas/ApiKey'
                      - type: object
                        properties:
                          secret:
                            type: string
                            description: Nuevo JWT de autenticación
                            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                          refresh_token:
                            type: string
                            description: Nuevo refresh token emitido para la API key
                            example: akrt_abc123xyz98172j9saa
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Token de actualización inválido o API key revocada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - api_keys.dashboard.write
        api_any_of:
          - api_keys.api.write
      security:
        - api_key: []
  /privacy_center/session_token:
    get:
      tags:
        - Privacy center
      summary: Obtener un token de sesión para el centro de privacidad
      description: |
        Genera un token JWT que permite acceder a los endpoints del centro de privacidad para una entidad específica.
        El token tiene una duración de 15 minutos y permite acceder a los endpoints de entidades, acciones de consentimiento,
        commits de consentimiento y templates de consentimiento.
      operationId: getPrivacyCenterSessionToken
      parameters:
        - name: entity_id
          in: query
          description: ID de la entidad para la cual se generará el token
          required: true
          schema:
            type: string
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Token generado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Token JWT para acceder al centro de privacidad
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55X2lkIjoiY29tcF8xMjM0NTY3ODkwIiwiZW50aXR5X2lkIjoiZW50XzFCMk0yWThBc2dUcGdBbVk3UGhDZmciLCJzY29wZSI6WyIvZW50aXRpZXMvKiIsIi9jb25zZW50X2FjdGlvbnMvKiIsIi9jb25zZW50X2NvbW1pdHMvKiIsIi9jb25zZW50X3RlbXBsYXRlcy8qIl0sImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE2MjQwMDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        '400':
          description: Error de solicitud - falta el parámetro entity_id
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Bad Request
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: The required parameter entity_id is missing
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.manage
      security:
        - api_key: []
  '/consent_actions/stats.{format}':
    get:
      tags:
        - Consent actions
      summary: Obtener estadísticas de conversión de las acciones de consentimiento
      description: |
        Obtiene estadísticas agregadas de las acciones de consentimiento, incluyendo conteos totales,
        tasas de aceptación por template y número de entidades únicas.
      operationId: getConsentActionsStats
      parameters:
        - $ref: '#/components/parameters/FormatParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Estadísticas de acciones de consentimiento
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    $ref: '#/components/schemas/ConsentActionStatus'
            text/csv:
              schema:
                type: string
                description: Datos de estadísticas en formato CSV
                example: |
                  actions_count,ratio,entities_count,consent_template_token,consent_template_name,consent_template_is_optional,consent_template_version
                  75,0.5,25,ct_abc123,Consentimiento de marketing,true,1
                  75,0.5,20,ct_def456,Consentimiento de análisis,false,2
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.actions.read
          - consent.api.manage
      security:
        - api_key: []
  '/consent_commits/stats.{format}':
    get:
      tags:
        - Consent commits
      summary: Obtener estadísticas de conversión de commits de consentimiento
      description: |
        Obtiene estadísticas agregadas de los commits de consentimiento, incluyendo conteos totales,
        combinaciones de templates utilizadas y tasas de aceptación.
      operationId: getConsentCommitsStats
      parameters:
        - $ref: '#/components/parameters/FormatParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Estadísticas de commits de consentimiento
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    $ref: '#/components/schemas/ConsentCommitStats'
            text/csv:
              schema:
                type: string
                description: Datos de estadísticas en formato CSV
                example: |
                  commits_count,acceptance_rate,entities_count,consent_template_names,consent_template_tokens
                  50,0.5,20,"Consentimiento de marketing,Consentimiento de análisis","ct_abc123,ct_def456"
                  30,0.3,15,Consentimiento básico,ct_ghi789
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.read
          - consent.api.commits.read
          - consent.api.manage
      security:
        - api_key: []
  '/disclosure_requests/stats.{format}':
    get:
      tags:
        - Disclosure requests
      summary: Obtener estadísticas de disclosure requests
      description: |
        Obtiene estadísticas agregadas de los diclosures requests, incluyendo conteos totales,
        tasas de conversión, distribución por estado y promedio de solicitudes por usuario.
      operationId: getDisclosureRequestsStats
      parameters:
        - $ref: '#/components/parameters/FormatParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Estadísticas de diclosures
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    $ref: '#/components/schemas/DisclosureRequestStats'
            text/csv:
              schema:
                type: string
                description: Datos de estadísticas en formato CSV
                example: |
                  commits_count,strict_conversion_rate,conversion_rate,average_disclosure_per_user
                  200,0.75,0.8,1.5
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - disclosure.dashboard.read
          - disclosure.dashboard.manage
        api_any_of:
          - disclosure.api.read
          - disclosure.api.manage
      security:
        - api_key: []
  /company_info:
    get:
      tags:
        - Company
      summary: Obtener información de la empresa
      description: Retorna la información básica de la empresa actual.
      operationId: getCompanyInfo
      responses:
        '200':
          description: Información de la empresa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
    patch:
      tags:
        - Company
      summary: Actualizar información de la empresa
      description: Actualiza la información básica de la empresa.
      operationId: updateCompanyInfo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Nombre de la empresa
                  example: Mi Nueva Empresa
                site_url:
                  type: string
                  description: URL del sitio web
                  example: 'https://minuevaempresa.com'
                redec_code:
                  type: integer
                  nullable: true
                  description: Código REDEC asociado a la empresa
                  example: 1234
      responses:
        '200':
          description: Información de la empresa actualizada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - config.manage
        api_any_of:
          - config.api.manage
      security:
        - api_key: []
  /redec/consent_actions:
    post:
      tags:
        - REDEC
      summary: Crear un consent action para REDEC
      description: |
        Crea un nuevo consent action a través del endpoint REDEC. Este endpoint está diseñado
        específicamente para registrar consentimientos en el contexto del cumplimiento normativo REDEC.

        Debe proporcionar ya sea `entity_id` (para una entidad existente) o `user_reference` (para crear/encontrar una entidad).
      operationId: createRedecConsentAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentActionRedecInput'
      responses:
        '201':
          description: Consent action creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_action:
                    $ref: '#/components/schemas/ConsentAction'
        '400':
          description: Error en la solicitud (parámetros faltantes o inválidos)
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Bad Request
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: The required parameter entity_nin is missing
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.actions.write
          - consent.api.manage
      security:
        - api_key: []
  '/redec/consent_actions/{id}':
    get:
      tags:
        - REDEC
      summary: Obtener un consent action REDEC
      description: Obtiene los detalles de una acción de consentimiento REDEC específica
      operationId: showRedecConsentAction
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la acción de consentimiento
          schema:
            type: string
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Consent action encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_action:
                    allOf:
                      - $ref: '#/components/schemas/ConsentAction'
                      - type: object
                        properties:
                          redec_receipt_pdf:
                            type: string
                            format: uri
                            nullable: true
                            description: URL del PDF del recibo REDEC. Disponible una vez generado el recibo.
                            example: 'https://storage.example.com/receipts/redec_receipt_123.pdf'
                          redec_pdf_hash:
                            type: string
                            nullable: true
                            description: Hash SHA256 del PDF del recibo REDEC para verificación de integridad.
                            example: a1b2c3d4e5f6...
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.actions.read
          - consent.api.manage
      security:
        - api_key: []
  '/redec/consent_actions/{token}/download_receipt':
    get:
      tags:
        - REDEC
      summary: Descargar recibo PDF REDEC
      description: |
        Descarga el recibo PDF de una acción de consentimiento REDEC.
        El PDF incluye verificación de integridad mediante hash SHA256.
      operationId: downloadRedecConsentActionReceipt
      parameters:
        - name: token
          in: path
          required: true
          description: Token del consent action
          schema:
            type: string
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: PDF del recibo REDEC
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Recibo no disponible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorSchema'
              example:
                type: invalid_request_error
                title: Resource not found
                status: 404
                detail: Receipt PDF not available yet
        '422':
          description: Fallo en verificación de integridad
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Unprocessable entity
                  status:
                    type: integer
                    example: 422
                  detail:
                    type: string
                    example: PDF integrity check failed
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
        api_any_of:
          - consent.api.actions.read
          - consent.api.manage
      security:
        - api_key: []
  /redec/consent_commits:
    post:
      tags:
        - REDEC
      summary: Crear un consent commit para REDEC
      description: |
        Crea un nuevo consent commit (múltiples acciones de consentimiento) a través del endpoint REDEC.
        Este endpoint está diseñado específicamente para registrar múltiples consentimientos simultáneamente
        en el contexto del cumplimiento normativo REDEC.

        **Características:**
        - Permite procesar múltiples action tokens en una sola solicitud
        - Soporta tokens de cualquier tipo de template de consentimiento, pero al menos uno de ellos debe provenir de un template compatible con el REDEC

        Debe proporcionar ya sea `entity_id` (para una entidad existente) o `user_reference` (para crear/encontrar una entidad).
      operationId: createRedecConsentCommit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentCommitRedecInput'
      responses:
        '201':
          description: Consent commit creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent_commit:
                    $ref: '#/components/schemas/ConsentCommit'
        '400':
          description: Error en la solicitud (parámetros faltantes o inválidos)
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Bad Request
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    example: must include at least one redec compatible action token
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Funcionalidad REDEC no habilitada
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: authentication_error
                  title:
                    type: string
                    example: Forbidden
                  status:
                    type: integer
                    example: 403
                  detail:
                    type: string
                    example: company is not configured for redec
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.commits.write
          - consent.api.manage
      security:
        - api_key: []
  /redec/consent_templates:
    post:
      tags:
        - REDEC
      summary: Crear un template de consentimiento para REDEC
      description: |
        Crea un nuevo template de consentimiento a través del endpoint REDEC. Este endpoint está diseñado
        específicamente para templates de consentimiento en el contexto del cumplimiento normativo REDEC.

        **Validaciones específicas de REDEC:**
        - El template debe tener exactamente un data use
        - El data use debe ser compatible con REDEC (`finance.commercial_risk_assessment` o `finance.credit_risk_assessment`)
        - El template debe tener un producto asociado
        - El producto debe tener un `redec_kind` configurado
        - La funcionalidad REDEC debe estar habilitada para la compañía
      operationId: createRedecConsentTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedecConsentTemplateInput'
            examples:
              redec_with_legacy_product_id:
                summary: REDEC con producto legado
                value:
                  name: Consentimiento REDEC comercial
                  title: Autorización REDEC
                  text: Autorizo consulta para evaluación comercial
                  data_subject: customer
                  duration_type: fixed
                  duration: P12M
                  product_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                  data_requirements:
                    - key: cl_carnet_rut
                      data_uses:
                        - finance.commercial_risk_assessment
              redec_with_scopes:
                summary: REDEC con scope explícito de producto
                value:
                  name: Consentimiento REDEC crediticio
                  title: Autorización REDEC
                  text: Autorizo consulta para evaluación crediticia
                  data_subject: customer
                  duration_type: fixed
                  duration: P6M
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 2
                  data_requirements:
                    - key: cl_carnet_rut
                      data_uses:
                        - finance.credit_risk_assessment
      responses:
        '201':
          description: Template de consentimiento REDEC creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Funcionalidad REDEC no habilitada
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: REDEC functionality is not enabled for this company
        '404':
          description: Producto no encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Product not found
        '422':
          description: Error de validación REDEC
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                examples:
                  single_data_use:
                    value:
                      error: REDEC templates must have exactly one data use
                    summary: Debe tener exactamente un data use
                  redec_compatible_use:
                    value:
                      error: 'Data use must be one of: finance.commercial_risk_assessment, finance.credit_risk_assessment'
                    summary: Data use no compatible con REDEC
                  product_required:
                    value:
                      error: REDEC templates must have a product
                    summary: Producto requerido
                  redec_kind_required:
                    value:
                      error: Product must have a REDEC kind
                    summary: Producto sin REDEC kind
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  '/redec/consent_templates/{id}':
    patch:
      tags:
        - REDEC
      summary: Actualizar un template de consentimiento para REDEC
      description: |
        Actualiza un template de consentimiento existente a través del endpoint REDEC.
        El modelo de template de consentimiento es versionado, por lo que cada cambio realizado no modifica la versión actual,
        sino que genera una nueva versión, dejando trazable el historial de cambios.

        **Validaciones específicas de REDEC:**
        - El template debe tener exactamente un data use
        - El data use debe ser compatible con REDEC (`finance.commercial_risk_assessment` o `finance.credit_risk_assessment`)
        - El template debe tener un producto asociado
        - El producto debe tener un `redec_kind` configurado
        - La funcionalidad REDEC debe estar habilitada para la compañía
      operationId: updateRedecConsentTemplate
      parameters:
        - name: id
          in: path
          required: true
          description: ID del template de consentimiento
          schema:
            type: string
          example: constpl_wAspvmEr4ACDZaPUtfwjsA
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentTemplateInput'
            examples:
              redec_update_with_scoped_product:
                summary: Actualizar REDEC fijando versión de producto
                value:
                  name: Consentimiento REDEC crediticio
                  title: Autorización REDEC
                  text: Autorizo consulta para evaluación crediticia
                  data_subject: customer
                  duration_type: fixed
                  duration: P12M
                  scopes:
                    - scope_type: product
                      scope_id: prod_1B2M2Y8AsgTpgAmY7PhCfg
                      scope_version: 3
                  data_requirements:
                    - key: cl_carnet_rut
                      data_uses:
                        - finance.credit_risk_assessment
      responses:
        '200':
          description: 'Nueva versión del template de consentimiento REDEC, con los cambios realizados.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Funcionalidad REDEC no habilitada
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: REDEC functionality is not enabled for this company
        '404':
          description: Template o producto no encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                examples:
                  template_not_found:
                    value:
                      error: Template not found
                    summary: Template no encontrado
                  product_not_found:
                    value:
                      error: Product not found
                    summary: Producto no encontrado
        '422':
          description: Error de validación REDEC
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                examples:
                  single_data_use:
                    value:
                      error: REDEC templates must have exactly one data use
                    summary: Debe tener exactamente un data use
                  redec_compatible_use:
                    value:
                      error: 'Data use must be one of: finance.commercial_risk_assessment, finance.credit_risk_assessment'
                    summary: Data use no compatible con REDEC
                  product_required:
                    value:
                      error: REDEC templates must have a product
                    summary: Producto requerido
                  redec_kind_required:
                    value:
                      error: Product must have a REDEC kind
                    summary: Producto sin REDEC kind
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
        api_any_of:
          - consent.api.write
          - consent.api.manage
      security:
        - api_key: []
  /reports:
    get:
      tags:
        - Reports
      summary: Obtener todos los reportes
      description: |
        Retorna una lista paginada de todos los reportes generados para la empresa autenticada.
        Los reportes pueden ser filtrados y ordenados usando los parámetros de consulta estándar.
      operationId: indexReports
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          example: '{"kind":{"=":"redec"}}'
      responses:
        '200':
          description: Reportes encontrados exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportIndexList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.read
          - consent.dashboard.manage
          - dsr.dashboard.read
          - dsr.dashboard.manage
        api_any_of:
          - consent.api.actions.read
          - consent.api.manage
          - dsr.api.read
          - dsr.api.manage
      security:
        - api_key: []
    post:
      tags:
        - Reports
      summary: Crear un nuevo reporte
      description: |
        Genera un nuevo reporte del tipo especificado para el período de tiempo indicado.

        Tipos de reportes disponibles:
        - `rdc30`: Reporte de consentimientos REDEC (RDC30) que incluye todas las acciones de consentimiento
          registradas en el período especificado que cumplen con los requisitos normativos REDEC.
        - `rdc40`: Reporte de solicitudes REDEC (RDC40) que incluye eventos de ingreso, procesamiento y cierre
          registrados en el período especificado para solicitudes de deudores.
      operationId: createReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportInput'
      responses:
        '201':
          description: Reporte creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    $ref: '#/components/schemas/Report'
        '400':
          description: 'Error en la solicitud (parámetros faltantes, tipo de reporte inválido, o error en la generación)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: invalid_request_error
                  title:
                    type: string
                    example: Bad Request
                  status:
                    type: integer
                    example: 400
                  detail:
                    type: string
                    examples:
                      - The required parameter starts_at is missing
                      - 'Unknown report kind: invalid_kind'
                      - not all consent actions are redec compliant
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      x-permissions:
        dashboard_any_of:
          - consent.dashboard.write
          - consent.dashboard.manage
          - dsr.dashboard.write
          - dsr.dashboard.manage
        api_any_of:
          - consent.api.actions.write
          - consent.api.manage
          - dsr.api.write
          - dsr.api.manage
      security:
        - api_key: []
  /exports:
    get:
      tags:
        - Exports
      summary: Listar exportaciones
      description: |
        Retorna una lista paginada de exportaciones creadas para la empresa autenticada.
        Permite filtrar por estado, recurso o formato mediante `where`.
      operationId: indexExports
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/OrderByParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"completed"}}'
            resource_filter:
              summary: Filtrar por recurso
              value: '{"resource_kind":{"=":"consent_actions"}}'
      responses:
        '200':
          description: Exportaciones encontradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportIndexList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - api_key: []
    post:
      tags:
        - Exports
      summary: Crear una exportación asíncrona
      description: |
        Crea una exportación asíncrona para recursos de alto volumen.
        La respuesta retorna el estado inicial del proceso y un identificador para consultar su progreso.
      operationId: createExport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportInput'
      responses:
        '202':
          description: Exportación encolada
          content:
            application/json:
              schema:
                type: object
                properties:
                  export:
                    $ref: '#/components/schemas/Export'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  '/exports/{id}':
    get:
      tags:
        - Exports
      summary: Obtener estado de exportación
      description: |
        Retorna el estado actual de una exportación asíncrona.
        Cuando la exportación está completa, incluye `download_url` para descargar el archivo generado.
      operationId: showExport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Identificador de la exportación
          example: exp_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Estado de exportación
          content:
            application/json:
              schema:
                type: object
                properties:
                  export:
                    $ref: '#/components/schemas/Export'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - api_key: []
  /government_check_requests:
    post:
      tags:
        - Government check requests
      summary: Crear un government check request
      description: |
        Crea un nuevo government check request para verificar datos de identidad contra el registro civil.
        Se debe proporcionar `subject_id` o `user_reference` (mutuamente exclusivos).
      operationId: createGovernmentCheckRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GovernmentCheckRequestInput'
      responses:
        '201':
          description: Government check request creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  government_check_request:
                    $ref: '#/components/schemas/GovernmentCheckRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Error de validación
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      errors:
                        example:
                          - 'Provide either subject_id or user_reference, not both'
                          - Either subject_id or user_reference is required
                          - nin is required
                          - document_number is required
                          - nin has an invalid format. Must be a valid Chilean RUT
      security:
        - api_key: []
    get:
      tags:
        - Government check requests
      summary: Obtener todos los government check requests
      operationId: indexGovernmentCheckRequests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: where
          in: query
          description: Filtros en formato JSON
          required: false
          schema:
            type: string
          examples:
            status_filter:
              summary: Filtrar por estado
              value: '{"status":{"=":"pending"}}'
        - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Government check requests encontrados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernmentCheckRequestList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - api_key: []
  '/government_check_requests/{id}':
    get:
      tags:
        - Government check requests
      summary: Obtener un government check request específico
      operationId: getGovernmentCheckRequest
      parameters:
        - name: id
          in: path
          description: ID del government check request
          required: true
          schema:
            type: string
          example: govcheck_1B2M2Y8AsgTpgAmY7PhCfg
      responses:
        '200':
          description: Government check request encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  government_check_request:
                    $ref: '#/components/schemas/GovernmentCheckRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - api_key: []
components:
  parameters:
    PageParam:
      name: page
      in: query
      description: Número de página
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    PerPageParam:
      name: per_page
      in: query
      description: Número de entradas por página
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    OrderByParam:
      name: order_by
      in: query
      description: Orden de los resultados (ej. "created_at DESC")
      required: false
      schema:
        type: string
      example: created_at DESC
    FormatParam:
      name: format
      in: path
      description: Formato de respuesta para estadísticas
      required: true
      schema:
        type: string
        enum:
          - json
          - csv
        default: json
      example: json
    ExpandParam:
      name: expand
      in: query
      description: Lista de campos relacionados a incluir en la respuesta
      required: false
      schema:
        type: array
        items:
          type: string
        uniqueItems: true
      style: form
      explode: false
      examples:
        expand_template:
          summary: Expandir template de consentimiento
          value:
            - consent_template
  responses:
    SuccessResponse:
      description: Respuesta exitosa
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: true
              data:
                type: object
                description: Los datos de la respuesta exitosa
    UnauthorizedError:
      description: Error de autenticación
      content:
        application/json:
          schema:
            type: object
            required:
              - type
              - title
              - status
              - detail
            properties:
              type:
                type: string
                example: authentication_error
              title:
                type: string
                example: Unauthorized
              status:
                type: integer
                example: 401
              detail:
                type: string
                example: 'We could not authenticate your credentials. Please check the documentation at https://docs.soyio.id'
    NotFoundError:
      description: Recurso no encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundErrorSchema'
    ForbiddenError:
      description: Acceso prohibido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    ValidationError:
      description: Error de validación
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  schemas:
    CompanyInfo:
      type: object
      description: Información básica de la empresa.
      properties:
        id:
          type: string
          description: Token identificador único de la empresa.
          example: com_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre de la empresa.
          example: Mi Empresa
        legal_company_name:
          type: string
          description: Nombre legal de la empresa.
          example: Mi Empresa S.A.S.
        tin:
          type: string
          description: Número de identificación tributaria de la empresa.
          example: 12345678-9
        site_url:
          type: string
          description: URL del sitio web de la empresa.
          example: 'https://miempresa.com'
        redec_code:
          type: integer
          nullable: true
          description: Código REDEC asociado a la empresa.
          example: 1234
        is_live_mode:
          type: boolean
          description: Indica si la empresa está en modo live.
          example: true
    FilterOrderAndPaginationMetadata:
      type: object
      properties:
        page:
          type: integer
          description: Página actual
          example: 1
        per_page:
          type: integer
          description: Entradas por página
          example: 20
        total:
          type: integer
          description: Total de entradas
          example: 45
        order_by:
          type: string
          description: Orden de los resultados (ej. "created_at DESC")
          example: created_at DESC
        filters:
          type: object
          description: Filtros aplicados a la consulta
          example:
            status:
              '=': pending
    DashboardPermission:
      type: string
      description: Permisos disponibles para usuarios de dashboard.
      enum:
        - dashboard.read
        - dashboard.write
        - dashboard.manage
        - consent.dashboard.read
        - consent.dashboard.write
        - consent.dashboard.config
        - consent.dashboard.manage
        - dsr.dashboard.read
        - dsr.dashboard.write
        - dsr.dashboard.config
        - dsr.dashboard.manage
        - disclosure.dashboard.read
        - disclosure.dashboard.write
        - disclosure.dashboard.config
        - disclosure.dashboard.manage
        - users.dashboard.read
        - users.dashboard.manage
        - api_keys.dashboard.read
        - api_keys.dashboard.write
        - webhooks.dashboard.read
        - webhooks.dashboard.write
        - config.manage
        - data.dashboard.pii.read
    ApiPermission:
      type: string
      description: Permisos disponibles para API keys.
      enum:
        - api.read
        - api.write
        - api.manage
        - consent.api.read
        - consent.api.write
        - consent.api.config
        - consent.api.actions.write
        - consent.api.actions.read
        - consent.api.manage
        - consent.api.commits.write
        - consent.api.commits.read
        - dsr.api.read
        - dsr.api.write
        - dsr.api.config
        - dsr.api.manage
        - disclosure.api.read
        - disclosure.api.write
        - disclosure.api.config
        - disclosure.api.manage
        - users.api.read
        - users.api.write
        - users.api.manage
        - roles.api.read
        - roles.api.write
        - roles.api.delete
        - roles.api.manage
        - api_keys.api.read
        - api_keys.api.write
        - config.api.manage
        - webhooks.api.write
        - webhooks.api.read
    Permission:
      type: string
      description: Permiso válido para autorización de endpoints.
      enum:
        - dashboard.read
        - dashboard.write
        - dashboard.manage
        - consent.dashboard.read
        - consent.dashboard.write
        - consent.dashboard.config
        - consent.dashboard.manage
        - dsr.dashboard.read
        - dsr.dashboard.write
        - dsr.dashboard.config
        - dsr.dashboard.manage
        - disclosure.dashboard.read
        - disclosure.dashboard.write
        - disclosure.dashboard.config
        - disclosure.dashboard.manage
        - users.dashboard.read
        - users.dashboard.manage
        - api_keys.dashboard.read
        - api_keys.dashboard.write
        - webhooks.dashboard.read
        - webhooks.dashboard.write
        - config.manage
        - data.dashboard.pii.read
        - api.read
        - api.write
        - api.manage
        - consent.api.read
        - consent.api.write
        - consent.api.config
        - consent.api.actions.write
        - consent.api.actions.read
        - consent.api.manage
        - consent.api.commits.write
        - consent.api.commits.read
        - dsr.api.read
        - dsr.api.write
        - dsr.api.config
        - dsr.api.manage
        - disclosure.api.read
        - disclosure.api.write
        - disclosure.api.config
        - disclosure.api.manage
        - users.api.read
        - users.api.write
        - users.api.manage
        - roles.api.read
        - roles.api.write
        - roles.api.delete
        - roles.api.manage
        - api_keys.api.read
        - api_keys.api.write
        - config.api.manage
        - webhooks.api.write
        - webhooks.api.read
    PermissionRequirement:
      type: object
      description: |-
        Documenta permisos requeridos para el endpoint. Se usa solo en la extensión `x-permissions`
        y no forma parte del request.
      additionalProperties: false
      properties:
        dashboard_any_of:
          type: array
          description: Permisos que autorizan el endpoint cuando la autenticación es dashboard.
          items:
            $ref: '#/components/schemas/DashboardPermission'
        api_any_of:
          type: array
          description: Permisos que autorizan el endpoint cuando la autenticación es API key.
          items:
            $ref: '#/components/schemas/ApiPermission'
    ConsentTemplateInput:
      type: object
      required:
        - name
        - title
        - text
        - data_requirements
        - data_subject
      properties:
        name:
          type: string
          description: Nombre del template
          example: Mi template de consentimiento
        duration:
          type: string
          nullable: true
          description: 'Período de disponibilidad en [formato ISO](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm). Esto determina por cuánto tiempo puedes solicitar los datos del usuario desde que te dio su consentimiento.'
          example: P2M
        duration_type:
          type: string
          description: 'Tipo de duración del consentimiento. `fixed` usa `duration` en formato ISO, `conditional` usa una cláusula legal.'
          enum:
            - fixed
            - conditional
          default: fixed
          example: fixed
        duration_clause_type:
          type: string
          nullable: true
          description: |
            Cláusula legal para duración condicional.
            Requerida cuando `duration_type` es `conditional`.
          enum:
            - while_contractual_relationship
            - while_legal_obligation
            - until_purpose_fulfilled
            - until_revoked
            - custom
          example: while_contractual_relationship
        duration_clause_text:
          type: string
          nullable: true
          description: Texto libre de cláusula legal. Requerido cuando `duration_clause_type` es `custom`.
          example: Mientras dure la relación contractual.
        title:
          type: string
          description: Titulo que aparecerá en el checkbox del módulo de consentimiento
          example: Consentimiento general
        text:
          type: string
          description: |
            Texto del template de consentimiento. Permite referenciar [documentos de privacidad](/docs/api/resources/schemas/privacydocument).
          example: 'De acuerdo a los {{ terms_and_conditions }} y {{ privacy_policy }} de Soyio.'
        data_requirements:
          type: array
          description: Lista de requerimientos de datos
          items:
            $ref: '#/components/schemas/DataRequirementInput'
        data_subject:
          type: string
          description: |
            Tipo de sujeto de datos para el cual se aplica este template de consentimiento.
            Define la categoría de persona o entidad cuyos datos personales serán procesados.
          enum:
            - anonymous_user
            - citizen_voter
            - commuter
            - consultant
            - customer
            - employee
            - job_applicant
            - next_of_kin
            - passenger
            - patient
            - prospect
            - shareholder
            - supplier_vendor
            - trainee
            - visitor
          example: customer
        product_id:
          type: string
          description: |
            Identificador único del producto.
            Campo legado compatible: si se envía, se convierte internamente a `scopes` con `scope_type=product`.
            Si también se envía `scopes`, prevalece `scopes`.
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        branch_id:
          type: string
          description: |
            Identificador único de la branch.
            Campo legado compatible: si se envía, se convierte internamente a `scopes` con `scope_type=branch`.
            Si también se envía `scopes`, prevalece `scopes`.
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
        scopes:
          type: array
          description: |
            Lista de ámbitos de aplicación del consentimiento. Permite uno o múltiples scopes.
            Si `scope_version` se omite, el API resuelve la versión `latest` al momento de crear/actualizar y la persiste en la versión del template.
            El template no sigue automáticamente nuevas versiones del scope después de guardado.
          items:
            $ref: '#/components/schemas/ConsentTemplateScopeInput'
        revocable_data_uses:
          type: array
          description: |
            Lista de data uses permitidos para revocación iniciada por la empresa vía `/consent_revocations`.
            Cada valor puede ser exacto (por ejemplo `third_party_sharing.intra_company`) o prefijo raíz
            (por ejemplo `third_party_sharing`).
          items:
            type: string
          example:
            - third_party_sharing
        optional:
          type: boolean
          description: Indica si el template de consentimiento es opcional.
          example: false
        enabled:
          type: boolean
          description: Indica si la plantilla de consentimiento se muestra en el centro de privacidad.
          example: true
          default: true
    RedecConsentTemplateInput:
      allOf:
        - $ref: '#/components/schemas/ConsentTemplateInput'
        - type: object
          description: |
            Input para templates REDEC.
            Debe incluir un alcance de producto, ya sea vía `product_id` (legado) o en `scopes` con `scope_type=product`.
          properties:
            product_id:
              type: string
              description: Identificador único del producto (campo legado compatible para REDEC).
              example: prod_1B2M2Y8AsgTpgAmY7PhCfg
    ConsentTemplate:
      description: |
        Una _consent template_ (template de consentimiento) es una configuración necesaria para el módulo de [_consent_](/docs/integration-guide/consent/introduction).
        Este modelo es versionado, por lo que cada cambio realizado genera una nueva versión, dejando trazable el historial de cambios.
      x-tags:
        - Consent templates
      allOf:
        - $ref: '#/components/schemas/ConsentTemplateIndex'
        - type: object
          required:
            - event_logs
          properties:
            event_logs:
              type: array
              description: Registro de eventos relacionados con el template de consentimiento (creación y actualización)
              items:
                $ref: '#/components/schemas/EventLog'
    ConsentTemplateIndex:
      description: |
        Versión simplificada del template de consentimiento para listados.
        No incluye `event_logs` para optimizar el tamaño de la respuesta.
      type: object
      required:
        - id
        - name
        - title
        - text
        - version
        - duration_type
        - data_requirements
        - data_subject
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Identificador único. Debe empezar con `constpl_`
          example: constpl_wAspvmEr4ACDZaPUtfwjsA
        name:
          type: string
          description: Nombre descriptivo de la template
          example: Consentimiento básico
        version:
          type: integer
          description: Versión del template de consentimiento
          example: 1
        duration:
          type: string
          nullable: true
          description: 'Periodo de retención de datos en [formato ISO](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm)'
          example: P12M3H
        duration_type:
          type: string
          description: Tipo de duración del consentimiento.
          enum:
            - fixed
            - conditional
          example: fixed
        duration_clause_type:
          type: string
          nullable: true
          description: Cláusula legal para duración condicional.
          enum:
            - while_contractual_relationship
            - while_legal_obligation
            - until_purpose_fulfilled
            - until_revoked
            - custom
          example: while_contractual_relationship
        duration_clause_text:
          type: string
          nullable: true
          description: Texto libre de cláusula legal cuando la cláusula es custom.
          example: Mientras dure la relación contractual.
        title:
          type: string
          description: Titulo que aparecerá en el checkbox del módulo de consentimiento
          example: Consentimiento general
        text:
          type: string
          description: |
            Texto del consentimiento. Permite referenciar [documentos de privacidad](/docs/api/resources/schemas/privacydocument).
          example: 'De acuerdo a los {{ terms_and_conditions }} y {{ privacy_policy }} de Soyio.'
        data_requirements:
          type: array
          description: 'Lista de requerimientos de datos con información adicional. Ver [recurso](/docs/api/resources/schemas/datarequirement) para más información.'
          minItems: 1
          items:
            $ref: '#/components/schemas/DataRequirement'
        data_subject:
          type: string
          description: |
            Sujeto de derecho para el cual se aplica este template de consentimiento.
            Define la categoría de persona o entidad cuyos datos personales serán procesados.
          enum:
            - anonymous_user
            - citizen_voter
            - commuter
            - consultant
            - customer
            - employee
            - job_applicant
            - next_of_kin
            - passenger
            - patient
            - prospect
            - shareholder
            - supplier_vendor
            - trainee
            - visitor
          example: customer
        product_id:
          type: string
          description: Identificador único del producto cuando existe un único scope de tipo product (campo legado compatible).
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        branch_id:
          type: string
          description: Identificador único de la branch cuando existe un único scope de tipo branch (campo legado compatible).
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
        scopes:
          type: array
          description: |
            Lista de ámbitos de aplicación del consentimiento ya resueltos y versionados.
            Estos scopes son snapshot del momento de creación/actualización de esta versión del template.
          items:
            $ref: '#/components/schemas/ConsentTemplateScope'
        revocable_data_uses:
          type: array
          description: Data uses permitidos para revocaciones iniciadas por la empresa.
          items:
            type: string
          example:
            - third_party_sharing
        optional:
          type: boolean
          description: Indica si el template de consentimiento es opcional.
          example: false
        enabled:
          type: boolean
          description: Indica si la plantilla de consentimiento se muestra en el centro de privacidad.
          example: true
          default: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del template de consentimiento
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización del template de consentimiento
          example: '2024-03-21T10:15:00Z'
    ConsentTemplateIndexList:
      type: object
      properties:
        consent_templates:
          type: array
          items:
            $ref: '#/components/schemas/ConsentTemplateIndex'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ConsentTemplateScopeInput:
      type: object
      required:
        - scope_type
        - scope_id
      properties:
        scope_type:
          type: string
          enum:
            - product
            - branch
          description: Tipo de ámbito.
          example: product
        scope_id:
          type: string
          description: Identificador público tokenizado del recurso scope.
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        scope_version:
          type: integer
          nullable: true
          description: |
            Versión del recurso scope.
            Si se omite, el API resuelve la versión `latest` al momento del write y persiste ese valor.
          example: 1
    ConsentTemplateScope:
      type: object
      required:
        - scope_type
        - scope_id
        - scope_version
      properties:
        scope_type:
          type: string
          enum:
            - product
            - branch
          description: Tipo de ámbito.
          example: product
        scope_id:
          type: string
          description: Identificador público tokenizado del recurso scope.
          example: prod_1B2M2Y8AsgTpgAmY7PhCfg
        scope_version:
          type: integer
          description: |
            Versión del recurso scope persistida en esta versión del template.
            Este valor queda fijado al guardar y no se actualiza automáticamente cuando aparecen nuevas versiones del scope.
          example: 1
    ConsentTemplateList:
      type: object
      properties:
        consent_templates:
          type: array
          items:
            $ref: '#/components/schemas/ConsentTemplate'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    DisclosureTemplateInput:
      type: object
      required:
        - name
        - duration
        - data_subject
        - data_requirements
      properties:
        name:
          type: string
          description: Nombre descriptivo del template de disclosure.
          example: Validación estándar
        duration:
          type: string
          description: |
            Período de disponibilidad en [formato ISO 8601](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm).
            Determina durante cuánto tiempo puede ejecutarse el proceso de divulgación una vez iniciado.
          example: P3M
        data_subject:
          type: string
          description: Tipo de sujeto de datos para el cual se aplica este template.
          enum:
            - anonymous_user
            - citizen_voter
            - commuter
            - consultant
            - customer
            - employee
            - job_applicant
            - next_of_kin
            - passenger
            - patient
            - prospect
            - shareholder
            - supplier_vendor
            - trainee
            - visitor
          example: customer
        data_requirements:
          type: array
          description: Lista de requerimientos de datos que se solicitarán durante el proceso.
          items:
            $ref: '#/components/schemas/DataRequirementInput'
        privacy_document_ids:
          type: array
          description: Identificadores de documentos de privacidad asociados a este template.
          items:
            type: string
          example:
            - privdoc_jy21JCGqb-VHhHeUd2nmKw
        mobile_nfc_enabled:
          type: boolean
          description: |
            Indica si este template tiene habilitada lectura NFC. Solo aplica en el SDK móvil React Native; el flujo a través del SDK web continúa sin NFC.
        skip_consent:
          type: boolean
          description: 'Indica si se debe saltar el paso de consentimiento durante el proceso de disclosure request. En caso de ser `true`, la pantalla en donde se solicita el consentimiento no se mostrará. Además, el `agreement` que se crea al final del proceso no tendrá permisos de acceso a los datos solicitados.'
          default: false
          example: false
        skip_account_creation:
          type: boolean
          description: |
            Indica si se debe saltar el paso de creación de cuenta durante el proceso de disclosure request.
            Cuando es `true`, no se mostrará la pantalla que invita al usuario a crear una cuenta reutilizable en Soyio.
          default: false
          example: false
        force_validation:
          type: boolean
          description: |
            Indica si los disclosure requests creados con este template deben forzar validación biométrica por defecto.
            Cuando es `true`, los usuarios deberán completar el proceso de validación biométrica incluso si ya tienen
            datos validados previamente. Este valor puede ser sobrescrito por el parámetro `forceValidation` en el
            widget al crear un disclosure request específico.
          default: false
          example: false
    DisclosureTemplate:
      description: |
        Un template de disclosure define la configuración necesaria para solicitar datos e iniciar procesos de verificación de
        identidad en un disclosure request. Contiene los datos requeridos, el validador a utilizar y los documentos de
        privacidad asociados. Los templates con disclosure requests existentes no pueden ser eliminados para mantener la
        trazabilidad de los procesos ejecutados.
      x-tags:
        - Disclosure templates
      type: object
      required:
        - id
        - name
        - duration
        - data_subject
        - data_requirements
        - privacy_document_ids
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Identificador único. Debe empezar con `dtpl_`.
          example: dtpl_3D4O4A0CuiVriCnA9RjEhi
        name:
          type: string
          description: Nombre descriptivo del template de divulgación.
          example: Validación estándar
        duration:
          type: string
          description: Duración del consentimiento en formato ISO 8601.
          example: P3M
        data_subject:
          type: string
          description: Tipo de sujeto de datos al que aplica el template.
          enum:
            - anonymous_user
            - citizen_voter
            - commuter
            - consultant
            - customer
            - employee
            - job_applicant
            - next_of_kin
            - passenger
            - patient
            - prospect
            - shareholder
            - supplier_vendor
            - trainee
            - visitor
          example: customer
        data_requirements:
          type: array
          description: Datos requeridos para completar el proceso de divulgación.
          items:
            $ref: '#/components/schemas/DataRequirement'
        privacy_document_ids:
          type: array
          description: Identificadores de documentos de privacidad asociados.
          items:
            type: string
          example:
            - privdoc_jy21JCGqb-VHhHeUd2nmKw
        skip_consent:
          type: boolean
          description: Indica si se debe saltar el paso de consentimiento durante el proceso de disclosure request.
          default: false
          example: false
        skip_account_creation:
          type: boolean
          description: Indica si se debe saltar el paso de creación de cuenta durante el proceso de disclosure request.
          default: false
          example: false
        force_validation:
          type: boolean
          description: |
            Indica si los disclosure requests creados con este template deben forzar validación biométrica por defecto.
            Este valor puede ser sobrescrito por el parámetro `forceValidation` del widget.
          default: false
          example: false
        liveness_check:
          type: boolean
          description: |
            Indica si se requiere validación de liveness (prueba de vida). No puede ser `true` si `id_scan_check` es `false`.
          example: true
        id_scan_check:
          type: boolean
          description: |
            Indica si se requiere escaneo del documento de identidad. Cuando se combina con `liveness_check`, se verifica que la persona que hizo el liveness corresponda la persona del documento de identidad.
          example: true
        government_check:
          type: boolean
          default: false
          description: Indica si se debe hacer un cruce con la base de datos del gobierno durante la validación de identidad en disclosure requests creados con este template.
        created_at:
          type: string
          format: date-time
          description: Fecha de creación del template.
          example: '2024-02-01T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha de la última actualización del template.
          example: '2024-02-10T18:45:00Z'
        mobile_nfc_enabled:
          type: boolean
          description: |
            Indica si este template tiene habilitada lectura NFC. Solo aplica en el SDK móvil React Native; el flujo a través del SDK web continúa sin NFC.
          example: false
    DisclosureTemplateList:
      type: object
      properties:
        disclosure_templates:
          type: array
          items:
            $ref: '#/components/schemas/DisclosureTemplate'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    EventLog:
      type: object
      description: Registro de un evento en el sistema
      properties:
        timestamp:
          type: string
          format: date-time
          description: Fecha y hora del evento
          example: '2024-03-20T15:30:00Z'
        type:
          type: string
          description: Tipo de evento
          example: created
        description:
          type: string
          description: Descripción del evento
          example: Consent template created
        payload:
          type: object
          description: Datos adicionales del evento
          example:
            version: 1
            created_by: cusr_123
    DataRequirementInput:
      type: object
      required:
        - key
        - data_uses
      properties:
        key:
          type: string
          description: Clave del dato. Es un texto libre que identifica específicamente el dato involucrado en el consentimiento.
          example: first_name
        data_category:
          type: string
          description: |
            Categoría del dato personal. Debe seguir la [taxonomía de categorías de datos](/docs/integration-guide/taxonomy).

            Las siguientes llaves (`key`) infieren la categoría del dato personal:

            --------------------

              - `name`: Primer nombre (**Name > First**)
              - `last_name`: Apellido (**Name > Last**)
              - `date_of_birth`: Fecha de nacimiento (**Demographic > Birth date**)
              - `cl_carnet_rut`: RUT (**Government Id > National Identification Number**)
              - `cl_carnet_doc_number`: Número de documento (**Government Id**)
              - `cl_carnet_expiration_date`: Fecha de expiración del documento (**Government Id**)
              - `cl_carnet_issue_date`: Fecha de emisión del documento (**Government Id**)
              - `gender`: Género (**Demographic > Gender**)
              - `nationality`: Nacionalidad (**Demographic**)
              - `email`: Correo electrónico (**Contact > Email**)
              - `phone_number`: Teléfono (**Contact > Phone number**)
              - `national_id_front_photo`: Foto frontal del documento de identidad (**Government Id**)
              - `national_id_back_photo`: Foto trasera del documento de identidad (**Government Id**)

            --------------------

            Esto significa que si se utiliza alguna de estas llaves, no es necesario especificar la categoría del dato.

            Si se especifica una de estas llaves y además se especifica la categoría del dato, la categoría dada tendrá prioridad sobre la predefinida.
          example: user.name.first
        data_uses:
          type: array
          description: 'Lista de usos permitidos para el dato, parte de la taxonomía de usos de datos'
          items:
            type: string
    DataRequirement:
      type: object
      properties:
        key:
          type: string
          description: Clave del dato. Es un texto libre que identifica específicamente el dato involucrado en el consentimiento.
          example: first_name
        data_category:
          type: string
          description: 'Categoría del dato según nuestra taxonomía. Revisa [taxonomía](/docs/integration-guide/taxonomy) para más información.'
          example: user.name.first
        data_uses:
          type: array
          description: 'Lista de finalidades de tratamiento según nuestra taxonomía. Revisa [taxonomía](/docs/integration-guide/taxonomy) para más información.'
          items:
            type: string
    DisclosureRequestList:
      type: object
      properties:
        disclosure_requests:
          type: array
          items:
            $ref: '#/components/schemas/DisclosureRequest'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    IdentityList:
      type: object
      properties:
        identities:
          type: array
          items:
            $ref: '#/components/schemas/Identity'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ValidationAttemptList:
      type: object
      properties:
        validation_attempts:
          type: array
          items:
            $ref: '#/components/schemas/ValidationAttempt'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    AuthAttemptList:
      type: object
      properties:
        auth_attempts:
          type: array
          items:
            $ref: '#/components/schemas/AuthAttempt'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    SignatureAttemptList:
      type: object
      properties:
        signature_attempts:
          type: array
          items:
            $ref: '#/components/schemas/SignatureAttempt'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    EventList:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    SignedDocumentList:
      type: object
      properties:
        signed_documents:
          type: array
          items:
            $ref: '#/components/schemas/SignedDocument'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    DisclosureRequest:
      description: |
        Representa el disclosure request de datos en el sistema. Este proceso integral incluye:
        - Verificación de identidad del usuario
        - Registro del consentimiento
        - Revelación de datos hacia la empresa solicitante

        El proceso comienza con la entrega de consentimiento, donde el usuario verá los datos solicitados y deberá confirmar
        su consentimiento. Luego, verificará su identidad y al completar este paso, se creará una identidad con los datos
        verificados.

        ### Guias relacionadas
        - [Verificación de identidad](/docs/integration-guide/disclosure/introduction)
      x-tags:
        - Disclosure requests
      type: object
      properties:
        id:
          type: string
          description: Identificador único del disclosure request.
          example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
        disclosure_template_id:
          type: string
          description: Identificador del template de disclosure.
          example: dtpl_3D4O4A0CuiVriCnA9RjEhi
        identity_id:
          type: string
          description: Identificador únicode la identidad.
          example: id_ma21KLsmaslopask912Aa2
        status:
          type: string
          description: Estado del disclosure request.
          enum:
            - pending
            - initialized
            - authenticating
            - validating
            - verifying_identity
            - awaiting_permissions
            - awaiting_missing_data
            - timed_out
            - granted
            - failed
          example: pending
        matchers:
          type: array
          description: Matchers del disclosure request.
          items:
            type: object
            properties:
              key:
                type: string
                description: Clave del matcher.
                example: cl_carnet_rut
              value:
                type: string
                description: Valor del matcher.
                example: 12345678-9
        sdk:
          type: string
          description: SDK utilizado para iniciar la solicitud.
          example: web
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema para el disclosure request.
          example: user_123
        identity_email:
          type: string
          description: Correo electrónico proveído por el comercio a la hora de crear el disclosure request.
          example: walter@white.com
        performed_nfc_scan:
          type:
            - boolean
            - 'null'
          description: Indica si el flujo incluyó paso de lectura NFC (solo disponible vía React Native SDK).
          example: true
        force_validation:
          type: boolean
          description: 'Indica si se creará el disclosure request incluso si ya existía uno previo. Cuando es `true`, el usuario debe realizar una nueva validación incluso si ya existía uno previo para el mismo template y referencia.'
          example: true
          default: false
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se creó el disclosure request.
          example: '2024-03-20T15:30:00Z'
    AuthRequest:
      x-tags:
        - Auth requests
      type: object
      description: |
        Los auth requests son una forma de autenticar a identidades previamente validadas a través de un `disclosure_request`.

        ### Guias relacionadas
        - [Conceptos Generales](/docs/integration-guide/general-concepts)
      properties:
        id:
          type: string
          description: Identificador único del request de autenticación.
          example: authreq_Kop19_kEe23i7hSw8QG4-a
        identity_id:
          type: string
          description: Identificador de la identidad que realiza el intento.
          example: id_ma21KLsmaslopask912Aa2
        status:
          type: string
          enum:
            - awaiting_authentication
            - successful
            - timed_out
          description: Estado actual del request de autenticación.
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema para el request de autenticación.
          example: user_123
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se creó el registro del intento de autenticación.
    AuthRequestList:
      type: object
      properties:
        auth_requests:
          type: array
          items:
            $ref: '#/components/schemas/AuthRequest'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    IdentityInformation:
      type: object
      description: Información detallada de un atributo específico de una identidad.
      properties:
        key:
          type: string
          description: Clave o nombre del atributo de la identidad.
          example: cl_carnet_rut
        value:
          type: string
          description: Valor asociado a la clave del atributo.
          example: 11.988.320-5
      xml:
        name: tag
    Identity:
      x-tags:
        - Identities
      type: object
      description: |
        Los objetos de identidad permiten gestionar los datos de identidad de tus usuarios.
        Una identidad representa a un usuario verificado en el sistema y contiene toda la información
        validada sobre esa persona.

        ### Guias relacionadas
        - [Conceptos Generales](/docs/integration-guide/general-concepts)
      properties:
        id:
          type: string
          description: Identificador único de la identidad.
          example: id_ma21KLsmaslopask912Aa2
        email:
          type: string
          description: Correo electrónico asociado a la identidad.
          example: hari.seldon@trantor.empire
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema para esta identidad en el contexto de la compañía autenticada.
          example: user_123
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la identidad.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización de la identidad.
          example: '2024-03-20T15:30:00Z'
        data:
          type: array
          description: Colección de información adicional sobre la identidad en forma de pares clave-valor.
          items:
            $ref: '#/components/schemas/IdentityInformation'
          example:
            - key: name
              value: Hari
            - key: last_name
              value: Seldon
            - key: date_of_birth
              value: 11988-03-20
            - key: cl_carnet_rut
              value: 11.988.320-5
            - key: cl_carnet_doc_number
              value: '11988320'
            - key: cl_carnet_expiration_date
              value: 12050-12-31
            - key: cl_carnet_issue_date
              value: 12020-01-15
            - key: gender
              value: male
            - key: nationality
              value: Trantorian
            - key: phone_number
              value: '+569119883205'
        signed_documents:
          type: array
          description: Lista de todos los `ids` de los documentos firmados por la identidad.
          items:
            type: string
            description: Identificador único del documento firmado.
            example: sd_1B2M2Y8AsgTpgAmY7PhCfg
          example:
            - sd_1B2M2Y8AsgTpgAmY7PhCfg
            - sd_2C3N3Z9BtgQqhDnB0SkFhg
        attestations:
          type: array
          description: |
            Lista de attestations que documentan las validaciones realizadas sobre esta identidad.
          items:
            $ref: '#/components/schemas/Attestation'
          example:
            - kind: liveness
              validated_at: '2026-01-19T12:00:00Z'
            - kind: id_scan
              validated_at: '2026-01-19T12:00:00Z'
            - kind: id_match
              validated_at: '2026-01-19T12:00:00Z'
            - kind: government_check
              validated_at: '2026-01-19T12:05:00Z'
    AuthAttempt:
      x-tags:
        - Auth attempts
      type: object
      description: |
        Los intentos de autenticación representan movimientos de una identidad al intentar autenticarse con tu sistema.

        El tipo de autenticación dependerá del registro del dispositivo de autenticación del usuario. En el caso de que un usuario
        no tenga su dispositivo de autenticación registrado, el tipo de validación será facial. En ese momento se le pedirá
        registrar el dispositivo.

        **Guias relacionadas**:
        - [Autenticación de usuarios](/docs/integration-guide/authentication/introduction)
        - [Verificación de identidad](/docs/integration-guide/disclosure/introduction)
      properties:
        id:
          type: string
          description: Identificador único del intento de autenticación.
          example: aa_Kop19_kEe23i7hSw8QG4-a
        identity_id:
          type: string
          description: Identificador de la identidad que realiza el intento.
          example: id_ma21KLsmaslopask912Aa2
        requestable_id:
          type: string
          description: Identificador del recurso asociado al intento de autenticación.
          example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
        requestable_type:
          type: string
          description: Tipo del recurso asociado al intento de autenticación.
          enum:
            - DisclosureRequest
            - SignatureAttempt
            - AuthRequest
          example: DisclosureRequest
        status:
          type: string
          enum:
            - awaiting_authentication
            - authenticating_by_video
            - failed
            - successful
          description: 'Estado actual del intento de autenticación (por ejemplo, "exitoso", "fallido").'
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema para el intento de autenticación.
          example: user_123
        kind:
          type: string
          enum:
            - facial_validation
            - passkey_validation
          description: Tipo de validación utilizada en el intento de autenticación. `passkey_validation` corresponde a cuando un usuario validó a través de un dispositivo registrado.
        error_reason:
          type:
            - 'null'
            - string
          description: Razón del error en caso de que el intento haya fallado. Campo opcional.
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se creó el registro del intento de autenticación.
    SignatureAttempt:
      x-tags:
        - Signature attempts
      type: object
      description: |
        Representan los intentos de los usuarios para firmar ciertos documentos, los cuales dependen del SignatureAttemptTemplate.
        La firma puede realizarse por medio de llaves de acceso para cuando el usuario haya registrado una, o por medio de video
        facial cuando el usuario por alguna razón no puede usar la llave de acceso.

        ### Guias relacionadas
        - [Firma de documentos](/docs/integration-guide/signature/introduction)
      properties:
        id:
          type: string
          description: Identificador único del intento de firma.
          example: sa_1B2M2Y8AsgTpgAmY7PhCfg
        identity_id:
          type: string
          description: Identificador de la identidad que realiza el intento.
          example: id_ma21KLsmaslopask912Aa2
        status:
          type: string
          enum:
            - pending
            - authenticating
            - creating_signed_documents
            - successful
          description: Estado actual del intento de firma.
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema para el intento de firma.
          example: user_123
        auth_type:
          type: string
          enum:
            - passkey_validation
            - facial_validation
          description: Tipo de autenticación utilizada en el intento de firma. `passkey_validation` corresponde a cuando un usuario validó a través de una llave de acceso.
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se creó el registro del intento de autenticación.
    ValidationAttempt:
      x-tags:
        - Validation attempts
      type: object
      description: |
        Los intentos de validación representan los procesos de validación de identidades de los usuarios.
        Estos obedecen a una serie de reglas de validación representadas por un template de validación.

        ### Guias relacionadas
        - [Verificación de identidad](/docs/integration-guide/disclosure/introduction)
      properties:
        id:
          type: string
          description: Identificador único del flujo de validación.
          example: va_1B2M2Y8AsgTpgAmY7PhCfg
        identity_email:
          type: string
          description: Correo electrónico de la identidad asociada al flujo.
          example: gus@polloshermanos.com
        status:
          type: string
          enum:
            - pending
            - in_progress
            - successful
            - canceled
          description: Estado actual del flujo de validación.
        failed_count:
          type: integer
          description: Cantidad de veces que el flujo de validación ha fallado.
          example: 1
        user_reference:
          type:
            - string
            - 'null'
          description: Referencia de usuario de tu sistema para el flujo de validación.
          example: user_123
        performed_nfc_scan:
          type:
            - boolean
            - 'null'
          description: Indica si el flujo incluyó paso de lectura NFC (solo disponible vía React Native SDK).
          example: true
        nfc_detail:
          type: string
          enum:
            - not_requested
            - failed
            - success
          description: Resultado detallado de la lectura NFC cuando aplica.
          example: success
        requestable_id:
          type: string
          description: 'ID del objeto asociado al intento de validación (ej. DataSubjectRequest, DisclosureRequest).'
          example: dsreq_1B2M2Y8AsgTpgAmY7PhCfg
        requestable_type:
          type: string
          description: Tipo de objeto asociado al intento de validación.
          example: DataSubjectRequest
        errors_array:
          type: array
          description: Lista de errores detallados asociados al flujo de validación.
          items:
            type: object
            properties:
              code:
                type: string
                description: Código interno del error.
                example: auth-002
              type:
                type: string
                description: 'Categoría del error (document, facial u otro).'
                example: document
              message:
                type: string
                description: Clave del error reportado.
                example: document_validation_error
              detail:
                type: string
                description: Mensaje listo para mostrar relacionado al error.
                example: No pudimos validar el documento con la información enviada.
        error_reason:
          type:
            - 'null'
            - string
          enum:
            - unknown_error
            - document_validation_error
            - facial_validation_error
            - expiration_error
          description: 'Motivo del error, si el flujo no fue exitoso. Campo opcional.'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del flujo de validación.
    ConsentCommitIndex:
      type: object
      description: Versión simplificada del commit de consentimiento para listados. No incluye campos show-only para optimizar el tamaño de la respuesta.
      properties:
        id:
          type: string
          description: Identificador único del consent commit
          example: ccom_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente
          example: user_123
        entity_id:
          type: string
          description: Identificador de la entidad asociada
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        context:
          type: string
          description: Contexto adicional asociado al commit de consentimiento. Referencia al contexto de la primera acción de consentimiento
          example: web_signup
          nullable: true
        contextual_data:
          $ref: '#/components/schemas/ContextualData'
        data_uses:
          type: array
          description: Lista de usos de datos cubiertos por las acciones de consentimiento asociadas
          items:
            type: string
          example:
            - essential
            - marketing
        consent_actions:
          type: array
          description: Acciones de consentimiento asociadas al commit (versión simplificada)
          items:
            $ref: '#/components/schemas/ConsentActionIndex'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del consent commit
          example: '2024-03-20T15:30:00Z'
    ConsentCommit:
      x-tags:
        - Consent commits
      description: Agrupa una serie de acciones de consentimiento realizadas por un usuario
      allOf:
        - $ref: '#/components/schemas/ConsentCommitIndex'
        - type: object
          properties:
            evidence_id:
              type: string
              description: Identificador de la evidencia generada por el acuerdo creado a partir del commit de consentimiento
              example: evd_wCntp5aXB5q7fKSthevwrw
            agreement_id:
              type: string
              description: Identificador del acuerdo generado por este commit de consentimiento
              example: agr_wCntp5aXB5q7fKSthevwrw
              nullable: true
            agreement_version:
              type: integer
              description: Versión del acuerdo generado por este commit de consentimiento
              example: 1
              nullable: true
            consent_actions:
              type: array
              description: Acciones de consentimiento asociadas al commit (versión completa)
              items:
                $ref: '#/components/schemas/ConsentAction'
    ConsentActionIndex:
      type: object
      description: Versión simplificada de la acción de consentimiento para listados. No incluye campos show-only para optimizar el tamaño de la respuesta.
      properties:
        id:
          type: string
          description: Identificador único de la acción de consentimiento
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
        entity_id:
          type: string
          description: Identificador de la entidad asociada. Puede ser nulo.
          example: ent_5F6Q6C2EwkXtkEpB1TlGjk
          nullable: true
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente
          example: user_123
        consent_template_id:
          type: string
          description: Identificador del template de consentimiento asociado.
          example: ctmpl_1B2M2Y8AsgTpgAmY7PhCfg
        consent_commit_id:
          type: string
          description: 'Identificador del commit de consentimiento asociado a este recurso, en caso de se haya originado a través de un commit. De lo contrario, es nulo.'
          example: ccmt_1B2M2Y8AsgTpgAmY7PhCfg
          nullable: true
        consent_template_name:
          type: string
          description: Nombre de la plantilla de consentimiento asociado cuando no se expande la relación.
          example: Essential Services Template
        consent_template_version:
          type: integer
          description: Versión de la plantilla de consentimiento asociada cuando no se expande la relación.
          example: 1
        context:
          type: string
          description: Contexto adicional asociado a la acción de consentimiento
          example: web_signup
          nullable: true
        kind:
          type: string
          description: Tipo de acción realizada.
          enum:
            - grant
            - revoke
          example: grant
        data_use:
          type: string
          description: Uso principal de datos asociado a la acción de consentimiento.
          example: essential
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la acción de consentimiento
          example: '2024-03-20T15:30:00Z'
        action_type:
          type: string
          description: Tipo específico de acción
          enum:
            - opt_in_click
            - voice_confirmation
            - physical_confirmation
          example: opt_in_click
        scope_selection_behavior:
          type: string
          description: |
            Semántica de selección de scopes para acciones de tipo `grant`.
            `replace` aplica intención final (puede revocar scopes no seleccionados).
            `additive` agrega solo los scopes seleccionados sin revocar los no seleccionados.
          enum:
            - replace
            - additive
          example: replace
        action_data:
          type: object
          description: Datos adicionales de la acción (máximo 4KB de tamaño serializado en JSON)
          example:
            checkbox_id: cb_123
        selected_scopes:
          type: array
          description: |
            Scopes seleccionados para esta acción.
            Si está vacío en templates sin scopes, la acción aplica de forma global.
          items:
            $ref: '#/components/schemas/ConsentTemplateScope'
        contextual_data:
          $ref: '#/components/schemas/ContextualData'
    ConsentAction:
      x-tags:
        - Consent actions
      description: Representa una acción de consentimiento realizada por un usuario
      allOf:
        - $ref: '#/components/schemas/ConsentActionIndex'
        - type: object
          properties:
            evidence_id:
              type: string
              description: Identificador de la evidencia asociada al acuerdo generado por esta acción de consentimiento
              example: evd_wCntp5aXB5q7fKSthevwrw
              nullable: true
            agreement_id:
              type: string
              description: Identificador del acuerdo generado por esta acción de consentimiento
              example: agr_wCntp5aXB5q7fKSthevwrw
              nullable: true
            agreement_version:
              type: integer
              description: Versión del acuerdo generado por esta acción de consentimiento
              example: 1
              nullable: true
            data_categories:
              type: array
              description: Lista de categorías de datos únicas cubiertas por el template de consentimiento asociado
              items:
                type: string
              example:
                - user.name.first
                - user.contact.email
    ContextualData:
      type: object
      description: 'Datos contextuales como IP, user agent, etc.'
      properties:
        ip:
          type: string
          example: 192.168.1.1
        user_agent:
          type: string
          example: Mozilla/5.0
        url:
          type: string
          example: 'https://example.com'
        phone_number:
          type: string
          example: '+56912345678'
    Event:
      x-tags:
        - Events
      type: object
      description: |
        Los eventos nos permiten comunicarte cambios relevantes en el sistema. Cuando ocurre un evento interesante,
        se crea un objeto evento. Por ejemplo, cuando se valida una identidad, se crea un evento `validation_attempt.succeeded`;
        cuando una validación falla, se crea un objeto `validation_attempt.failed`.

        :::info
        Una llamada a la API **puede generar 1 o más eventos**.
        :::

        Los eventos pueden ser enviados directamente a tu servidor a través de la utilización de webhooks.

        ### Guias relacionadas
        - [Webhooks](/docs/api/webhooks)
      properties:
        id:
          type: string
          description: Identificador único del evento.
          example: evt_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre descriptivo del evento.
          example: disclosure_request.granted
        payload:
          type: object
          description: Datos adicionales asociados al evento.
          example:
            disclosure_request_id: dreq_1B2M2Y8AsgTpgAmY7PhCfg
            identity_id: id_ma21KLsmaslopask912Aa2
            user_reference: user_123
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se registró el evento.
          example: '2024-03-20T15:30:00Z'
    SignedDocument:
      x-tags:
        - Signed documents
      type: object
      description: |
        Los documentos firmados son documentos digitales que han sido autenticados por los usuarios mediante su firma electrónica.
        Estos documentos pueden incluir contratos, acuerdos legales, y otros documentos importantes que requieren confirmación
        de identidad y consentimiento explícito del usuario.

        La firma de estos documentos se gestiona a través del modelo `SignatureAttempt`, que verifica la identidad del usuario
        y asegura que la firma sea válida y segura.

        ### Guias relacionadas
        - [Firma de documentos](/docs/integration-guide/signature/introduction)
      properties:
        id:
          type: string
          description: Identificador único del documento firmado.
          example: sd_1B2M2Y8AsgTpgAmY7PhCfg
        identity_id:
          type: string
          description: Identificador de la identidad participante en la firma.
          example: id_ma21KLsmaslopask912Aa2
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se registró el documento firmado.
          example: '2024-03-20T15:30:00Z'
    Agreement:
      x-tags:
        - Agreements
      type: object
      title: Agreement
      description: |
        Representa el estado actual de los permisos de un usuario para utilizar datos de acuerdo a la taxonomía de datos y usos de datos.
        Puede ser actualizado a través de distintas acciones del usuario y empresa en el tiempo.

        :::info[Más información]
        Para más detalles, revisa nuestra sección de [Conceptos generales](/docs/integration-guide/general-concepts).
        :::
      properties:
        id:
          type: string
          description: Identificador único del acuerdo.
          example: agr_IdBeyWCa1ENLUYnPRLpCUg
        version:
          type: integer
          description: Versión del acuerdo
          example: 1
        user_reference:
          type: string
          description: Referencia de usuario proporcionada por el cliente.
          example: user_123
        subject_id:
          type: string
          description: Identificador único del usuario del acuerdo. Puede corresponder al identificador de un `Identity` o `Entity`. El `subject_type` indica el tipo del usuario en cuestión.
          example: ent_ma21KLsmaslopask912Aa2
        subject_type:
          type: string
          description: Tipo de sujeto del acuerdo. Puede ser `Identity` o `Entity`.
          example: Entity
        version_source_type:
          type: string
          description: 'Tipo de fuente de la versión del acuerdo. Puede ser `DisclosureRequest`, `ConsentAction` o `ConsentCommit`.'
          example: ConsentCommit
        version_source_id:
          type: string
          description: 'Identificador único de la fuente de la versión del acuerdo. Puede ser el identificador de un `DisclosureRequest`, `ConsentAction` o `ConsentCommit`.'
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
        data_permissions:
          type: array
          description: Datos procesados del agreement de acuerdo a la taxonomía de datos
          items:
            $ref: '#/components/schemas/DataPermission'
        previous_evidence_ids:
          type: array
          description: IDs de evidencias anteriores relacionadas con este acuerdo
          items:
            type: string
          example:
            - evd_pNMroI2OEfrDNdi8xT6kOQ
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del acuerdo.
          example: '2024-11-21T14:54:57.167Z'
    AgreementList:
      type: object
      properties:
        agreements:
          type: array
          items:
            $ref: '#/components/schemas/Agreement'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    Evidence:
      x-tags:
        - Agreements
      type: object
      description: Representa una evidencia que respalda un consentimiento o acuerdo.
      properties:
        id:
          type: string
          description: Identificador único de la evidencia.
          example: evd_wCntp5aXB5q7fKSthevwrw
        integrity_hash:
          type: string
          description: Hash criptográfico que garantiza la integridad de la evidencia.
          example: 28b0f934...
        legal_basis:
          type: enum
          description: Base legal del acuerdo.
          enum:
            - consent
          example: consent
        consent_method:
          type: object
          description: Información sobre el método de consentimiento utilizado.
          properties:
            channel:
              type: string
              description: Canal a través del cual se obtuvo el consentimiento.
              example: website
            capture_facilitator:
              type: string
              description: Entidad que facilitó el proceso de consentimiento.
              example: Soyio
            capture_source:
              type: string
              description: Entidad que fue responsable de capturar el consentimiento
              example: Salesforce
            metadata:
              type: object
              description: 'Metadatos adicionales de la forma de captura del consentimiento. Pueden ser referencias a flujos completos (identificadores de chats, urls de tickets, etc.) o descripciones de la forma de captura.'
              nullable: true
              example:
                details: se le mostró al usuario el texto de consentimiento en un chatbot de whatsapp
                chat_id: 13928
            actions:
              type: array
              description: Lista de acciones realizadas por el usuario para consentimiento.
              items:
                type: object
                properties:
                  kind:
                    type: enum
                    description: Tipo de acción ("grant" o "revoke")
                    enum:
                      - grant
                      - revoke
                    example: grant
                  action_type:
                    type: enum
                    description: Tipo específico de acción
                    enum:
                      - opt_in_click
                      - voice_confirmation
                      - physical_confirmation
                    example: opt_in_click
                  action_data:
                    type: object
                    description: Datos adicionales de la acción (máximo 4KB de tamaño serializado en JSON)
                    example:
                      checkbox_id: cb_123
                    nullable: true
                  action_id:
                    type: string
                    description: Identificador único de la acción de consentimiento
                    example: consact_1B2M2Y8AsgTpgAmY7PhCfg
                  template_id:
                    type: string
                    description: Identificador del template de consentimiento asociado.
                    example: ctmpl_1B2M2Y8AsgTpgAmY7PhCfg
                  template_version:
                    type: integer
                    description: Versión del template de consentimiento asociado.
                    example: 1
                  scope_selection_behavior:
                    type: string
                    description: Semántica de selección de scopes (`replace` o `additive`).
                    enum:
                      - replace
                      - additive
                    example: replace
                  selected_scopes:
                    type: array
                    description: Scopes seleccionados para esta acción.
                    items:
                      $ref: '#/components/schemas/ConsentTemplateScope'
                  timestamp:
                    type: string
                    format: date-time
                    description: Fecha y hora de la acción
                    example: '2024-03-20T15:30:00Z'
                  contextual_data:
                    $ref: '#/components/schemas/ContextualData'
        identification_method:
          type: object
          description: Información sobre el método de identificación utilizado.
          properties:
            data_subject_id:
              type: string
              description: ID del sujeto de datos identificado.
              example: id_ftKAfJCmbmGe1t2X1Kt3gw
            type:
              type: string
              description: Tipo de método de identificación utilizado.
              example: soyio.validation
            type_reference:
              type: string
              description: Referencia al proceso de identificación específico.
              example: va_Pwj5xTQYQ4vciUZPqnVTdg
        event_logs:
          type: array
          description: Registro cronológico de eventos relacionados con la evidencia.
          items:
            type: object
            properties:
              description:
                type: string
                description: Descripción del evento.
                example: Disclosure request was created
              timestamp:
                type: string
                format: date-time
                description: Fecha y hora del evento.
                example: '2024-11-21T14:54:29.802Z'
              type:
                type: string
                description: Tipo de evento.
                example: disclosure_created
              metadata:
                type: object
                description: Metadatos adicionales al evento
                nullable: true
                example:
                  details: se le mostró al usuario el texto de consentimiento en un chatbot de whatsapp
                  chat_id: 13928
        data_permissions_diff:
          type: object
          description: 'Diferencia de permisos de datos entre la versión anterior y actual del acuerdo. Muestra los permisos creados, removidos y extendidos.'
          nullable: true
          properties:
            created:
              type: array
              description: Permisos de datos que fueron creados en esta versión del acuerdo
              items:
                $ref: '#/components/schemas/DataPermission'
            removed:
              type: array
              description: Permisos de datos que fueron removidos en esta versión del acuerdo
              items:
                $ref: '#/components/schemas/DataPermission'
            extended:
              type: array
              description: Permisos de datos cuya fecha de expiración fue extendida en esta versión del acuerdo
              items:
                $ref: '#/components/schemas/DataPermission'
          example:
            created:
              - data_category: user.contact.email
                data_label: email
                data_use: marketing
                expires_at: '2025-11-21'
            removed:
              - data_category: user.name.first
                data_label: name
                data_use: essential
                expires_at: '2024-11-21'
            extended:
              - data_category: user.contact.phone
                data_label: phone
                data_use: essential
                expires_at: '2026-11-21'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la evidencia.
          example: '2024-11-21T14:54:57.202Z'
    DataPermission:
      type: object
      description: Representa un dato procesado de acuerdo a la taxonomía de datos.
      properties:
        data_category:
          type: string
          description: 'Categoría del dato personal. Sigue la taxonomía de datos. Revisa [taxonomía](/docs/integration-guide/taxonomy) para más información.'
          example: user.name.first
        data_label:
          type: string
          description: Identificador del dato
          example: name
        data_use:
          type: string
          description: 'Propósito específico del uso del dato. Sigue la taxonomía de usos de datos. Revisa [taxonomía](/docs/integration-guide/taxonomy) para más información.'
          example: essential.service.authentication
        data_subject:
          type: string
          description: |
            Sujeto de derecho para el cual se aplica este permiso de datos.
            El valor se hereda del template de consentimiento que originó el permiso.
          enum:
            - anonymous_user
            - citizen_voter
            - commuter
            - consultant
            - customer
            - employee
            - job_applicant
            - next_of_kin
            - passenger
            - patient
            - prospect
            - shareholder
            - supplier_vendor
            - trainee
            - visitor
          example: customer
        scope_type:
          type: string
          enum:
            - product
            - branch
          description: 'Tipo de alcance del uso del dato. Un dato puede estar dentro del contexto de un [producto](/docs/api/resources/schemas/product) o de una [branch](/docs/api/resources/schemas/branch)'
          nullable: true
        scope_id:
          type: string
          description: Identificador del producto o filial para la cual está vigente el uso del dato.
          nullable: true
        scope_version:
          type: integer
          description: Versión del producto o filial para la cual está vigente el uso del dato.
          nullable: true
        expires_at:
          type: string
          format: date
          description: Fecha de expiración del permiso de uso
          nullable: true
    DataUse:
      type: object
      description: Representa el uso específico de un dato.
      properties:
        use:
          type: string
          description: 'Propósito específico del uso del dato. Sigue la taxonomía de usos de datos. Revisa [taxonomía](/docs/integration-guide/taxonomy) para más información.'
          example: essential.service.authentication
        expires_at:
          type: string
          format: date
          description: Fecha de expiración del permiso de uso
          example: '2034-12-06'
        document_references:
          type: array
          description: Referencias a documentos relacionados
          items:
            type: string
          example:
            - 669823ed4c91e6af2537f984
            - 66b103a5d2e10ef171a9004b
    EvidenceList:
      type: object
      properties:
        evidences:
          type: array
          items:
            $ref: '#/components/schemas/Evidence'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    PrivacyDocument:
      type: object
      x-tags:
        - Privacy documents
      description: |
        Los documentos de privacidad son configuraciones que permiten gestionar documentos legales como términos y condiciones o políticas de privacidad. Estos documentos pueden ser referenciados desde distintos templates usando su `template_key`.

        Este modelo es versionado, por lo que cada cambio realizado genera una nueva versión, dejando trazable el historial de cambios.
      properties:
        id:
          type: string
          description: Identificador único. Debe empezar con `privdoc_`
          example: privdoc_jy21JCGqb-VHhHeUd2nmKw
        name:
          type: string
          description: Texto que se mostrará al usuario
          example: términos y condiciones
        template_key:
          type: string
          description: Identificador para referenciar el documento
          example: terms_and_conditions
        version:
          type: integer
          description: Versión del documento de privacidad
          example: 1
        url:
          type: string
          description: URL para acceder al documento
          example: /download_url
    PrivacyDocumentList:
      type: object
      properties:
        privacy_documents:
          type: array
          items:
            $ref: '#/components/schemas/PrivacyDocument'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    Branch:
      type: object
      x-tags:
        - Branches
      description: |
        Las branches representan divisiones o unidades de negocio específicas dentro de tu compañía.
      properties:
        id:
          type: string
          description: Identificador único de la sucursal.
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
        tin:
          type: string
          description: Número de identificación tributaria de la sucursal.
          example: 12.345.678-9
        legal_company_name:
          type: string
          description: Nombre legal de la sucursal.
          example: Sucursal de la empresa
        display_name:
          type: string
          description: Nombre comercial visible de la sucursal.
          example: Sucursal Centro
        version:
          type: integer
          description: Versión de la sucursal.
          example: 1
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la sucursal
          example: '2024-03-20T15:30:00Z'
        redec_code:
          type: integer
          description: |
            Código único REDEC asignado a esta sucursal para cumplimiento normativo.
            Este código identifica a la sucursal en el sistema REDEC (Registro de Deudores de Créditos) de Chile.
          example: 123456
          nullable: true
    BranchList:
      type: object
      properties:
        company_branches:
          type: array
          items:
            $ref: '#/components/schemas/Branch'
    ApiResponse:
      type: object
      description: Respuesta estándar para las operaciones de la API que incluyen código y mensaje de estado.
      properties:
        code:
          type: integer
          format: int32
          description: Código numérico que representa el estado de la respuesta.
          example: 200
        type:
          type: string
          description: 'Tipo de mensaje de la respuesta, por ejemplo, "error" o "success".'
          example: success
        message:
          type: string
          description: Mensaje descriptivo acerca del resultado de la operación.
          example: Operación completada exitosamente
      xml:
        name: '##default'
    Webhook:
      x-tags:
        - Webhooks
      type: object
      description: |
        Los webhooks son endpoints HTTP que reciben notificaciones cuando ocurren eventos en el sistema.
        Cada webhook puede estar suscrito a uno o más tipos de eventos.
      properties:
        id:
          type: string
          description: Identificador único del webhook
          example: wh_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre del webhook
          example: My Webhook
        status:
          type: string
          enum:
            - ok
            - failing
          description: 'Estado del webhook. Si el webhook ha fallado en las últimas 24 horas, el estado será `failing`.'
          example: ok
        last_failure_at:
          type: string
          format: date-time
          description: Fecha y hora de la última falla del webhook.
          example: '2024-03-20T15:30:00Z'
        url:
          type: string
          description: URL donde se enviarán los eventos
          example: 'https://company.com/your-webhook-endpoint'
        secret_key:
          type: string
          description: Clave secreta para verificar la integridad del webhook.
          example: WHzBRgmn6jC1lm377I70mxiCmyRTON+QeH739YF/oXs=
        subscriptions:
          type: array
          description: |
            Lista de eventos a los que está suscrito el webhook. Los eventos disponibles están detallados junto a cada recurso bajo la etiqueta `EVENT`.

            **TIP**:
            Puedes suscribirte a todos los eventos de un recurso específico usando el wildcard `*`.
            Por ejemplo, para suscribirte a todos los eventos de los `disclosure_request`, puedes suscribirte a `disclosure_request.*`.
          items:
            type: string
          example:
            - '*'
            - auth_attempt.*
            - validation_attempt.*
        enabled_modes:
          type: array
          description: Lista de modos en los que el webhook está habilitado
          items:
            type: string
          example:
            - production
            - sandbox
        enabled:
          type: boolean
          description: Indica si el webhook está habilitado o no
          example: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del webhook
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización del webhook
          example: '2024-03-20T15:30:00Z'
    WebhookList:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    WebhookTransaction:
      x-tags:
        - Webhooks
      type: object
      description: Representa una transacción o intento de entrega de un evento a un webhook.
      properties:
        id:
          type: string
          description: Identificador único de la transacción del webhook (token).
          example: whtx_1B2M2Y8AsgTpgAmY7PhCde
        event_id:
          type: string
          description: Identificador único del evento que generó esta transacción.
          example: evt_1B2M2Y8AsgTpgAmY7PhCgf
        event_name:
          type: string
          description: Nombre del evento que generó esta transacción.
          example: agreement.created
        response_code:
          type: integer
          description: Código de respuesta HTTP recibido del endpoint del webhook.
          example: 200
        response_body:
          type: string
          description: Cuerpo de la respuesta recibida del endpoint del webhook.
          example: '{"status": "received"}'
        response_headers:
          type: object
          description: Cabeceras de la respuesta recibida del endpoint del webhook.
          additionalProperties:
            type: string
          example:
            Content-Type: application/json
            X-Request-ID: 12345f-abc-6789
        successful:
          type: boolean
          description: Indica si la entrega del evento fue exitosa.
          example: true
        error_message:
          type: string
          nullable: true
          description: Mensaje de error en caso de que la entrega haya fallado.
          example: Connection timed out
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la transacción del webhook.
          example: '2024-03-21T10:00:00Z'
    WebhookTransactionList:
      type: object
      properties:
        webhook_transactions:
          type: array
          items:
            $ref: '#/components/schemas/WebhookTransaction'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    Product:
      x-tags:
        - Products
      type: object
      description: |
        Diferentes productos o servicios que ofrece tu compañía.

        Este modelo es versionado, por lo que cada cambio realizado genera una nueva versión, dejando trazable el historial de cambios.
      properties:
        id:
          type: string
          description: ID único del producto.
          example: product_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre del producto
          example: Mi Producto
        display_name:
          type: string
          description: Nombre comercial visible del producto.
          example: Cuenta Corriente Plus
        branch_id:
          type: string
          description: Identificador único de la branch
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
        version:
          type: integer
          description: Versión del producto
          example: 1
        redec_kind:
          type: string
          description: Objetivo de REDEC del producto
          enum:
            - commercial_credits
            - consumer_credits
            - housing_credits
            - financial_operations
            - acquired_debt_instruments
            - contingent_credits
            - freely_available_credit_line_limits
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del producto
          example: '2024-03-20T15:30:00Z'
    ProductList:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    DSRQueryRequestDetail:
      type: object
      description: 'Detalle de solicitud para consultas (access, portability)'
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - all
            - specific
          description: Tipo de solicitud de consulta.
          example: all
        data_categories:
          type: array
          items:
            type: string
          description: |
            Categorías de datos a solicitar. Requerido cuando kind es 'specific'.
            Debe ser una categoría válida de la taxonomía o 'other'.
          example:
            - user.name
            - user.contact.email
        detail:
          type: string
          description: Detalle adicional de la solicitud.
          example: Solicitud de acceso a datos personales
    DSRMutationRequestDetail:
      type: object
      description: 'Detalle de solicitud para modificaciones (rectification, opposition, suppression)'
      required:
        - requested_fields
      properties:
        requested_fields:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DSRRequestedField'
          description: Campos específicos que se solicita modificar
    DSRRedecRequestDetail:
      type: object
      description: 'Detalle de solicitud para REDEC (update, rectification, complementation, cancellation)'
      required:
        - reason_code
        - detail
        - operation_id
      properties:
        redec_id:
          type: string
          description: Identificador del caso en REDEC.
          example: redec_123
        reason_code:
          type: integer
          description: Código de razón definido por REDEC. Debe ser válido para el tipo de solicitud REDEC.
          example: 2
        entry_channel_code:
          type: integer
          description: Código de la vía de ingreso de la solicitud.
          example: 11
        reason:
          type: string
          description: Texto asociado al código de razón. Solo de respuesta.
          readOnly: true
          example: Diferencias en la morosidad informada de la deuda objetada
        detail:
          type: string
          description: Detalle adicional de la solicitud.
          example: Actualización de monto informado
        operation_id:
          type: string
          description: Código de la operación crediticia asociada a la solicitud.
          example: op_123456
        file_url:
          type: string
          nullable: true
          description: 'URL del archivo adjunto (PDF), si aplica.'
          readOnly: true
    DSRRequestedField:
      type: object
      required:
        - data_category
        - detail
      properties:
        data_category:
          type: string
          description: |
            Categoría de datos según taxonomía válida o 'all'.
            Debe ser una categoría válida de la taxonomía.
          example: user.name
        detail:
          type: string
          description: Detalle específico del campo solicitado.
          example: Corrección de fecha de nacimiento
        file_data:
          type: object
          description: |
            Datos del archivo adjunto (si aplica). Los archivos deben enviarse en formato `data_uri`
            (`data:<mime>;base64,<payload>`) y pueden ser PDF o imágenes (JPG/PNG) con un tamaño máximo de 5 MB.
          additionalProperties: true
    DataSubjectRequest:
      x-tags:
        - Data subject requests
      type: object
      description: |
        Representan las solicitudes de ejercicio de derechos de los usuarios.

        ### Guías relacionadas

        - [Gestión de derechos](/docs/integration-guide/rights-management/introduction)
        - [Centro de privacidad](/docs/integration-guide/privacy-center/introduction)
      required:
        - kind
        - contact_information
      properties:
        id:
          type: string
          description: Identificador único del data subject request. Debe empezar con `dsreq_`
          example: dsreq_1B2M2Y8AsgTpgAmY7PhCfg
        humanized_identifier:
          type: string
          description: Identificador de la solicitud.
          example: FME4607
        subject_id:
          type: string
          description: Identificador único del sujeto de datos que se está modificando. Puede corresponder al identificador de un `Identity` o `Entity`.
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente.
          example: user_123
        request_reference:
          type: string
          description: Referencia opcional de la solicitud proporcionada por el cliente para correlacionar webhooks y eventos.
          example: ticket-12345
        company_branch_id:
          type: string
          description: Identificador de la sucursal a la que está asociada esta solicitud.
          example: branch_1B2M2Y8AsgTpgAmY7PhCfg
        government_only_mode:
          type: boolean
          description: |
            Indica si la solicitud fue creada con el modo *government-only* activo. Cuando es `true`, el solicitante debe
            ingresar manualmente su RUT y número de documento para iniciar la validación contra el Registro Civil.
            Este valor se deriva de `company.config.data_subject_request.government_only_mode` y no es editable al crear
            la solicitud.
          example: true
        kind:
          type: string
          enum:
            - access
            - rectification
            - opposition
            - suppression
            - portability
            - redec_update
            - redec_rectification
            - redec_complementation
            - redec_cancellation
          description: Tipo de solicitud.
          example: access
        status:
          type: string
          enum:
            - awaiting_verification
            - validating
            - processing
            - resolved
            - data_missmatch
            - timed_out
          description: Estado actual de la solicitud.
          example: awaiting_verification
        terminal_state:
          type: string
          enum:
            - approved
            - partially_approved
            - rejected
          description: |
            Estado terminal de la solicitud cuando `status` es `resolved`.
          example: approved
        approved:
          type: boolean
          deprecated: true
          description: |
            Indica si la resolución fue aprobada (true) o rechazada (false).
            Campo legacy derivado de `terminal_state` y puede ser `null` si la resolución es parcial.
          example: true
        data_usage_during_request:
          type: string
          enum:
            - block
            - allow
          description: 'Indica si el uso de datos durante la solicitud está permitido o no. Solo es requerido para las solicitudes de tipo `rectification`, `opposition` y `suppression`.'
          example: block
        rejection_reason:
          type: string
          description: |
            Razón de rechazo si la solicitud fue rechazada.
          example: Documentación insuficiente
        contact_information:
          type: object
          required:
            - nin
            - email
          description: |
            Información de contacto del titular. La visibilidad / obligatoriedad de alguno de estos campos es configurable.
          properties:
            nin:
              type: string
              description: Número de identificación del usuario. No configurable.
              example: '123456789'
            email:
              type: string
              format: email
              description: Email del usuario. Este email se usa para enviar confirmaciones. No configurable.
              example: user@example.com
            names:
              type: string
              description: Nombres del usuario. Configurable
              example: Juan Carlos
            last_names:
              type: string
              description: Apellidos del usuario. Configurable
              example: Pérez Gómez
            phone:
              type: string
              description: Número de teléfono del usuario. Configurable
              example: +56 9 1234 5678
        request_detail:
          nullable: true
          description: |
            Detalle de la solicitud. Puede ser `null` cuando la solicitud es creada directamente por la compañía
            (a través de la API). Cuando se crea a través del widget del centro de privacidad, este campo siempre estará presente.
          oneOf:
            - $ref: '#/components/schemas/DSRQueryRequestDetail'
            - $ref: '#/components/schemas/DSRMutationRequestDetail'
            - $ref: '#/components/schemas/DSRRedecRequestDetail'
        workflow_run_id:
          type: string
          description: ID del workflow run asociado a la solicitud.
          example: wfr_1B2M2Y8AsgTpgAmY7PhCfg
        expires_at:
          type: string
          format: date-time
          description: Fecha y hora de expiración de la solicitud.
          example: '2024-03-20T15:30:00Z'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la solicitud.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización de la solicitud.
          example: '2024-03-20T15:30:00Z'
      if:
        allOf:
          - properties:
              status:
                const: resolved
          - properties:
              terminal_state:
                enum:
                  - rejected
                  - partially_approved
      then:
        required:
          - rejection_reason
    DataSubjectRequestContactFieldConfig:
      type: object
      description: |
        Configura los campos adicionales de contacto (nombres, apellidos y teléfono) que se muestran al titular durante la creación de una solicitud.
      required:
        - field_name
        - visible
        - required
      properties:
        field_name:
          type: string
          enum:
            - names
            - last_names
            - phone
          description: Campo de contacto al que se aplica la configuración.
          example: phone
        visible:
          type: boolean
          description: |
            Determina si el campo se muestra en los formularios del Centro de Privacidad. Si es `false`, el titular no verá este campo.
          example: true
        required:
          type: boolean
          description: |
            Indica si el campo debe ser completado cuando es visible. No puede establecerse en `true` cuando `visible` es `false`.
          example: false
    DataSubjectRequestCreate:
      type: object
      description: |
        Datos para crear un data subject request.
      required:
        - kind
        - contact_information
        - request_detail
      properties:
        subject_id:
          type: string
          description: ID del sujeto de datos que se está modificando.
          example: subj_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente.
          example: user_123
        kind:
          type: string
          enum:
            - access
            - rectification
            - opposition
            - suppression
            - portability
            - redec_update
            - redec_rectification
            - redec_complementation
            - redec_cancellation
          description: Tipo de solicitud.
          example: access
        origin:
          type: string
          description: Origen de la solicitud. Texto libre otorgado al comercio para fines de conciliación en futuras revisiones y/o análisis
          example: portal-onboarding
        initial_status:
          type: string
          enum:
            - processing
          description: |
            Estado inicial opcional para la solicitud. Si se omite, la solicitud se crea con el estado por defecto `awaiting_verification`.
            Solo se permite el valor `processing` para crear solicitudes que salten la fase de verificación inicial.
          example: processing
        data_usage_during_request:
          type: string
          enum:
            - block
            - allow
          description: 'Solo es requerido para las solicitudes de tipo `rectification`, `opposition`, `suppression` y `redec_*`.'
          example: block
        contact_information:
          type: object
          description: Información de contacto del titular. La visibilidad / obligatoriedad de alguno de estos campos es configurable.
          properties:
            nin:
              type: string
              description: Número de identificación del usuario. No configurable.
              example: '123456789'
            email:
              type: string
              format: email
              description: Email del usuario. Este email se usa para enviar confirmaciones. No configurable.
              example: user@example.com
            names:
              type: string
              description: nombres del usuario. configurable
              example: juan carlos
            last_names:
              type: string
              description: apellidos del usuario. configurable
              example: pérez gómez
            phone:
              type: string
              description: número de teléfono del usuario. configurable
            example: +56 9 1234 5678
        request_detail:
          oneOf:
            - $ref: '#/components/schemas/DSRQueryRequestDetail'
            - $ref: '#/components/schemas/DSRMutationRequestDetail'
            - $ref: '#/components/schemas/DSRRedecRequestDetail'
    DataSubjectRequestList:
      type: object
      properties:
        data_subject_requests:
          type: array
          items:
            $ref: '#/components/schemas/DataSubjectRequest'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    DataSubjectRequestUpdate:
      type: object
      description: |
        Esquema para actualizar el estado de una solicitud de ejercicio de derechos.
        Solo se permite el estado terminal `resolved`.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - resolved
          description: |
            Estado terminal de la solicitud. Debe ser `resolved`.
          example: resolved
        terminal_state:
          type: string
          enum:
            - approved
            - partially_approved
            - rejected
          description: |
            Estado terminal de la solicitud. Si también se envía `approved`, `terminal_state` tiene precedencia.
          example: approved
        approved:
          type: boolean
          deprecated: true
          description: |
            Campo legacy para indicar si la solicitud fue aprobada o rechazada.
            - `true`: La solicitud ha sido completada exitosamente
            - `false`: La solicitud ha sido rechazada
          example: true
        rejection_reason:
          type: string
          description: |
            Razón del rechazo de la solicitud.
            **Requerido únicamente cuando `terminal_state` es `rejected` o `partially_approved`**.
          example: Documentación insuficiente para procesar la solicitud
    ValidationError:
      type: object
      required:
        - type
        - title
        - status
        - errors
      properties:
        type:
          type: string
          example: validation_error
        title:
          type: string
          example: Validation error
        status:
          type: integer
          example: 422
        errors:
          type: array
          items:
            type: string
    ForbiddenError:
      type: object
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          example: authentication_error
        title:
          type: string
          example: Forbidden
        status:
          type: integer
          example: 403
        detail:
          type: string
          example: You are not authorized to access this resource(s)
    Attestation:
      type: object
      description: |
        Los attestations representan validaciones específicas realizadas sobre una identidad o entidad.
        Cada attestation certifica que se realizó un tipo particular de verificación en un momento determinado.

        Los attestations se generan automáticamente al completar exitosamente un validation attempt y actualizan su timestamp si hay una revalidación.
      properties:
        kind:
          type: string
          enum:
            - liveness
            - id_scan
            - id_match
            - government_check
          description: |
            Tipo de attestation que certifica una validación específica:
            - `liveness`: Certifica que se realizó una prueba de vida (detección de persona real)
            - `id_scan`: Certifica que se escaneó y validó un documento de identidad
            - `id_match`: Certifica que se comparó la foto del documento con la imagen de la persona (coincidencia facial)
            - `government_check`: Certifica que se validó la información con registros gubernamentales
          example: liveness
        validated_at:
          type: string
          format: date-time
          description: Fecha y hora en que se realizó la validación certificada por este attestation
          example: '2026-01-19T12:00:00Z'
    Entity:
      x-tags:
        - Entities
      type: object
      description: |
        Los objetos de Entidad permiten asociar los consentimientos de tus usuarios a un objeto. Una entidad representa a un usuario **no verificado** en el sistema, a diferencia de una identidad.
      properties:
        id:
          type: string
          description: ID único de la entidad.
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        agreement_id:
          type: string
          description: ID del agreement asociado a la entidad.
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        identity_id:
          type: string
          nullable: true
          description: ID de la identidad asociada a la entidad. Solo presente cuando la entidad tiene una identidad asociada.
          example: id_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: 'Referencia del usuario en tu sistema, almacenada directamente en la entidad (no depende del último agreement).'
          example: user_123
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la entidad.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización de la entidad.
          example: '2024-03-20T15:30:00Z'
        attestations:
          type: array
          description: |
            Lista de attestations que documentan las validaciones realizadas sobre esta entidad.
          items:
            $ref: '#/components/schemas/Attestation'
          example:
            - kind: liveness
              validated_at: '2026-01-19T12:00:00Z'
            - kind: id_scan
              validated_at: '2026-01-19T12:00:00Z'
            - kind: government_check
              validated_at: '2026-01-19T12:05:00Z'
    EntityIndex:
      type: object
      description: |
        Lista de entidades.
      properties:
        id:
          type: string
          description: ID único de la entidad.
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: 'Referencia del usuario en tu sistema, almacenada directamente en la entidad (no depende del último agreement).'
          example: user_123
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la entidad.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización de la entidad.
          example: '2024-03-20T15:30:00Z'
        attestations:
          type: array
          description: |
            Lista de attestations que documentan las validaciones realizadas sobre este sujeto.
          items:
            $ref: '#/components/schemas/Attestation'
          example:
            - kind: liveness
              validated_at: '2026-01-19T12:00:00Z'
            - kind: id_scan
              validated_at: '2026-01-19T12:00:00Z'
            - kind: id_match
              validated_at: '2026-01-19T12:00:00Z'
            - kind: government_check
              validated_at: '2026-01-19T12:05:00Z'
    EntityList:
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityIndex'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ComplianceStatus:
      type: object
      description: Estado del cumplimiento de una entidad respecto a un template de consentimiento específico. Considera el último estado del agreement para evaluar si es que cumple o no cumple.
      properties:
        status:
          type: string
          enum:
            - compliant
            - non_compliant
            - partially_compliant
          description: |
            El cumplimiento en sí:
            - `compliant`: La entidad cumple con **todos** los `data_requirements`s del template de consentimiento.
            - `non_compliant`: La entidad no cumple con **ningún** `data_requirement`s del template de consentimiento.
            - `partially_compliant`: La entidad cumple **solo con algunos** de los `data_requirements`s del template de consentimiento.
          example: compliant
        consent_template_id:
          type: string
          description: ID del template de consentimiento al cuál corresponde el cumplimiento
          example: constpl_1B2M2Y8AsgTpgAmY7PhCfg
        last_consent_action_id:
          type: string
          description: ID de la última acción de consentimiento asociada al template y esa entidad.
          example: consact_1B2M2Y8AsgTpgAmY7PhCfg
        agreement_id:
          type: string
          description: 'ID del agreement, para ir a buscar más información sobre el cumplimiento.'
          example: agreement_1B2M2Y8AsgTpgAmY7PhCfg
        is_revokable:
          type: boolean
          description: Indica si el agreement es revocable o no.
          example: true
    EntityComplianceStatusesResponse:
      type: object
      description: Respuesta estándar para los endpoints de estados de cumplimiento de entidades.
      properties:
        compliance_statuses:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceStatus'
    NotFoundErrorSchema:
      type: object
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          example: invalid_request_error
        title:
          type: string
          example: Resource not found
        status:
          type: integer
          example: 404
        detail:
          type: string
          example: Couldn't find <resource> with id '<id>'. Please check your request and try again
    Configuration:
      type: object
      x-tags:
        - Configuration
      description: |
        Representa a los aspectos configurables de tu empresa, tales como canales de comunicación u otros datos relevantes.
      properties:
        alert_notification_email:
          type: string
          description: |
            Dirección de correo electrónico que recibirá alertas de eventos críticos en el sistema, por ejemplo, notificaciones sobre fallas de webhooks.
          example: alerts@example.com
        icon_variant:
          type: string
          enum:
            - duotone
            - outline
            - solid
          default: duotone
          description: Variante de íconos preferida.
        whitelisted_domains:
          type: array
          items:
            type: string
          description: Lista de dominios permitidos para el contenido de tu embed.
        validation:
          type: object
          description: |
            Configuración exclusiva para las validaciones de identidad.
          properties:
            liveness_check:
              type: boolean
              description: |
                Indica si se requiere validación de liveness (prueba de vida). No puede ser `true` si `id_scan_check` es `false`.
              example: true
            id_scan_check:
              type: boolean
              description: |
                Indica si se requiere escaneo del documento de identidad. Cuando se combina con `liveness_check`, se verifica que la persona que hizo el liveness corresponda la persona del documento de identidad.
              example: true
            government_check:
              type: boolean
              default: false
              description: Indica si se debe hacer un cruce con la base de datos del gobierno al validar una identidad.
            ephemeral_transaction_data:
              type: boolean
              default: true
              description: Indica si los datos de la transacción deben ser eliminados después de la validación.
        disclosure:
          type: object
          description: |
            Configuración exclusiva para el módulo de Disclosure Request.
          properties:
            liveness_check:
              type: boolean
              description: |
                Indica si se requiere validación de liveness (prueba de vida). No puede ser `true` si `id_scan_check` es `false`.
              example: true
            id_scan_check:
              type: boolean
              description: |
                Indica si se requiere escaneo del documento de identidad. Cuando se combina con `liveness_check`, se verifica que la persona que hizo el liveness corresponda la persona del documento de identidad.
              example: true
            government_check:
              type: boolean
              default: false
              description: Indica si se debe hacer un cruce con la base de datos del gobierno durante el disclosure request.
            skip_passkey_registration:
              type: boolean
              default: false
              description: 'Indica si se debe saltar el registro de llave de acceso para usuarios que no creen cuenta con Soyio. Si el usuario desea crear una cuenta, de todas maneras se le pedirá que registre su llave de acceso.'
        consent:
          type: object
          description: |
            Configuración exclusiva para el módulo de consentimiento.
          properties:
            whitelisted_domains:
              type: array
              items:
                type: string
              description: Lista de dominios permitidos para el contenido de tu embed. Los dominios especificados acá se agregarán a la lista de dominios permitidos para el contenido de tu embed.
            label_display:
              type: string
              enum:
                - optional_only
                - mandatory_only
              default: optional_only
              description: 'Los consentimientos pueden ser opcionales o obligatorios. Si el consentimiento es obligatorio y el `label_display` es `mandatory_only`, entonces sólo se mostrará el label de `Requerido` en los consentimietos. Por el contrario, si el consentimiento es opcional y el `label_display` es `optional_only`, entonces sólo se mostrará el label de `Opcional` en los consentimietos. Puedes ver un ejemplo [acá](/docs/integration-guide/consent/customization#configura-las-etiquetas-de-obligatoriedad-de-consentimientos).'
            mandatory_label_text:
              type: string
              enum:
                - required
                - mandatory
              default: required
              description: 'Texto del label de consentimiento cuando el `label_display` es `mandatory_only`. Si es `required`, entonces el label será `Requerido`. Si es `mandatory`, entonces el label será `Obligatorio`.'
            redec_enabled:
              type: boolean
              default: false
              description: |
                Habilita la funcionalidad REDEC (Registro de Deudores de Créditos) para el módulo de consentimiento.
                Cuando está habilitado, permite registrar y gestionar consentimientos de acuerdo con los requisitos
                normativos REDEC de Chile.
              example: true
            redec_automatic_rdc30:
              type: boolean
              default: false
              description: |
                Habilita la generación automática semanal de reportes RDC30 para cumplimiento REDEC.
                Cuando está habilitado, el sistema generará automáticamente reportes RDC30 de forma periódica
                sin necesidad de solicitud manual. Requiere que `redec_enabled` esté activado.
              example: false
        privacy_center:
          type: object
          description: |
            Configuración exclusiva para el módulo de Centro de Privacidad.
          properties:
            contact_email:
              type: string
              description: Email de contacto para el Centro de Privacidad.
              example: privacy@example.com
            public_url:
              type: string
              description: 'URL pública del Centro de Privacidad. Puedes encontrar más información sobre los modos de integración [acá](/docs/integration-guide/privacy-center/functionalities).'
              example: 'https://public-privacy.example.com'
            private_url:
              type: string
              description: 'URL privada del Centro de Privacidad. Revisa [funcionalidades y modos](/docs/integration-guide/privacy-center/functionalities) del Centro de Privacidad para más información.'
              example: 'https://private-privacy.example.com'
            whitelisted_domains:
              type: array
              items:
                type: string
              description: Lista de dominios permitidos para incrustar el Centro de Privacidad.
        data_subject_request:
          type: object
          description: |
            Configuración exclusiva para el Data Subject Request, módulo que se encuentra en el Centro de Privacidad.
          properties:
            liveness_check:
              type: boolean
              description: |
                Indica si se requiere validación de liveness (prueba de vida). No puede ser `true` si `id_scan_check` es `false`.
              example: true
            id_scan_check:
              type: boolean
              description: |
                Indica si se requiere escaneo del documento de identidad. Cuando se combina con `liveness_check`, se verifica que la persona que hizo el liveness corresponda la persona del documento de identidad.
              example: true
            government_check:
              type: boolean
              default: false
              description: Indica si se debe hacer un cruce con la base de datos del gobierno durante la validación de identidad en DSR.
            mandatory_validation:
              type: boolean
              default: false
              description: |
                Determina si la validación de identidad es obligatoria durante el proceso de solicitud de derechos del titular de datos (DSR).

                - `false` (por defecto): El usuario recibe confirmación de que su solicitud fue creada exitosamente y puede elegir validar su identidad inmediatamente o en un momento posterior.
                - `true`: El usuario debe completar el proceso de validación de identidad antes de poder proceder con su solicitud.
            disable_functional_emails:
              type: boolean
              default: false
              description: |
                Determina si se deben enviar correos electrónicos funcionales (recuperación de código de solicitud por ejemplo) al titular de datos.

                - `false` (por defecto): Se envían correos electrónicos funcionales.
                - `true`: No se envían correos electrónicos funcionales. Si eliges esta opción, debes manejar el envío de estos correos electrónicos por tu cuenta, o el usuario no recibirá ningún correo electrónico funcional.
            disable_informative_emails:
              type: boolean
              default: false
              description: |
                Determina si se deben enviar correos electrónicos informativos (confirmación de solicitud, etc.) al titular de datos.

                - `false` (por defecto): Se envían correos electrónicos informativos.
                - `true`: No se envían correos electrónicos informativos.
            validation_timeout_period:
              type: string
              nullable: true
              description: |
                Período de tiempo durante el cual el titular de datos puede validar su identidad después de crear una solicitud en [formato ISO 8601](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm).

                - Si no se especifica (`null`): La solicitud no expira y el usuario puede validar su identidad en cualquier momento.
                - Si se especifica: La solicitud expirará después del período indicado, y el usuario deberá crear una nueva solicitud.

                El período total debe ser mayor que 0.
              example: P1D
            allow_many_data_categories_mutations:
              type: boolean
              default: true
              description: |
                Determina si las solicitudes de mutación (rectificación, oposición, supresión) pueden especificar más de una categoría de datos.

                - `true` (por defecto): Las solicitudes de mutación pueden incluir múltiples categorías de datos.
                - `false`: Las solicitudes de mutación están limitadas a una sola categoría de datos por solicitud.
              example: true
            contact_field_configs:
              type: array
              description: |
                Configuración de los campos adicionales de contacto que puede completar el titular al crear su solicitud.

                Cada elemento permite controlar la visibilidad y obligatoriedad de los campos soportados (`names`, `last_names`, `phone`).
              items:
                $ref: '#/components/schemas/DataSubjectRequestContactFieldConfig'
            appliable_scopes:
              type: array
              items:
                type: string
                enum:
                  - branch
              default: []
              description: |
                Define si las solicitudes deben asociarse obligatoriamente a una sucursal de la empresa.

                - Si está vacío (por defecto): Las solicitudes son de alcance general (sin asociación a sucursal).
                - Si contiene `"branch"`: El solicitante debe seleccionar una sucursal al crear la solicitud.
              example:
                - branch
            government_only_mode:
              type: boolean
              default: false
              deprecated: true
              description: |
                **DEPRECATED**: Este campo ha sido reemplazado por `validation_mode` y `government_check`.
                Para obtener el comportamiento equivalente, usa `validation_mode: "none"` con `government_check: true`.

                Activa el modo de validación exclusiva con carnet ante el Registro Cívil: el usuario ingresa su RUT y número de documento y se omite la captura de selfies y liveness.

                - `false` (por defecto): El flujo utiliza captura biométrica tradicional.
                - `true`: el widget pide al usuario sus datos de número de documento para efectuar la validación gubernamental
              example: true
            redec_automatic_rdc40:
              type: boolean
              default: false
              description: |
                Habilita la generación automática diaria de reportes RDC40 para solicitudes REDEC.
                Cuando está habilitado, el sistema generará automáticamente reportes RDC40 de forma periódica (diaria)
                sin necesidad de solicitud manual. Requiere que `redec_enabled` esté activado.
              example: false
        dashboard:
          type: object
          description: |
            Configuración exclusiva para el dashboard de la empresa.
          properties:
            auth_methods:
              type: array
              items:
                type: string
                enum:
                  - password
                  - google
                  - azure
                  - passkeys
              default:
                - password
              description: |
                Lista de métodos de autenticación habilitados para el dashboard de la empresa.
                Los métodos disponibles son:
                - `password`: Autenticación con contraseña
                - `google`: Autenticación con Google OAuth
                - `azure`: Autenticación con Azure AD
                - `passkeys`: Autenticación con llaves de acceso (WebAuthn)
              example:
                - password
                - google
                - passkeys
    ApiKeyInput:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: Etiqueta descriptiva para la API Key
          example: Frontend Application
          maxLength: 100
        expires_in_days:
          type: integer
          description: |
            Número de días para la expiración de la API key. Debe ser un número positivo.
            Si no se especifica, se aplican los valores por defecto:
            - Production: 90 días desde la creación
            - Sandbox: sin expiración
          example: 30
          minimum: 1
        scopes:
          type: array
          description: Alcance de permisos para la API Key. Lista de patrones de endpoints permitidos.
          items:
            type: string
          example:
            - /v1/identities/*
            - /v1/disclosure_requests/*
    ApiKeyUpdateInput:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: Etiqueta descriptiva para la API Key
          example: Frontend Application - Updated
          maxLength: 100
    CompanyUserRole:
      type: object
      description: Rol asignado al usuario de compañía.
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Token del rol asignado.
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre del rol asignado.
          example: editor
    UIConfiguration:
      type: object
      x-tags:
        - Configuration
      description: Configuración mínima utilizada para renderizado de interfaz en dashboard.
      properties:
        icon_variant:
          type: string
          enum:
            - duotone
            - outline
            - solid
          description: Variante de íconos utilizada por la UI.
        default_color:
          type: string
          nullable: true
          description: Color base de personalización para íconos en UI.
        consent:
          type: object
          properties:
            label_display:
              type: string
              enum:
                - optional_only
                - mandatory_only
            mandatory_label_text:
              type: string
              enum:
                - required
                - mandatory
        privacy_center:
          type: object
          properties:
            public_url:
              type: string
              nullable: true
            contact_email:
              type: string
              nullable: true
    CompanyUser:
      type: object
      x-tags:
        - Company users
      description: Usuario de dashboard perteneciente a una compañía.
      required:
        - id
        - email
        - name
        - created_at
        - updated_at
        - roles
        - permissions
      properties:
        id:
          type: string
          description: Token único del usuario de compañía.
          example: cusr_1B2M2Y8AsgTpgAmY7PhCfg
        email:
          type: string
          format: email
          description: Email del usuario de compañía.
          example: dashboard.user@example.com
        name:
          type: string
          description: Nombre del usuario de compañía.
          example: Dashboard User
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del usuario.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de última actualización del usuario.
          example: '2024-03-20T15:30:00Z'
        roles:
          type: array
          description: Roles actualmente asignados al usuario.
          items:
            $ref: '#/components/schemas/CompanyUserRole'
        permissions:
          type: array
          description: 'Permisos efectivos del usuario, derivados de sus roles.'
          items:
            $ref: '#/components/schemas/DashboardPermission'
    CompanyUserList:
      type: object
      properties:
        company_users:
          type: array
          items:
            $ref: '#/components/schemas/CompanyUser'
    CompanyUserCreateInput:
      type: object
      required:
        - name
        - email
        - role_id
      properties:
        name:
          type: string
          description: Nombre del usuario de compañía.
          example: Dashboard User
        email:
          type: string
          format: email
          description: Email del usuario de compañía.
          example: dashboard.user@example.com
        role_id:
          type: string
          description: Token del rol a asignar al usuario.
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
    CompanyUserUpdateInput:
      type: object
      required:
        - role_id
      properties:
        role_id:
          type: string
          description: Token del rol que reemplazará el rol actual del usuario.
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
    RoleInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Nombre del rol.
          example: support-analyst
        description:
          type: string
          description: Descripción opcional del rol.
          example: Can review and triage requests
        permissions:
          type: array
          description: Permisos de dashboard asociados al rol.
          items:
            $ref: '#/components/schemas/DashboardPermission'
    Role:
      type: object
      x-tags:
        - Roles
      description: Rol asignable a usuarios de una compañía.
      required:
        - id
        - name
        - permissions
        - built_in
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Identificador único del rol.
          example: role_1B2M2Y8AsgTpgAmY7PhCfg
        name:
          type: string
          description: Nombre del rol.
          example: admin
        description:
          type: string
          nullable: true
          description: Descripción del rol.
          example: Full dashboard access
        permissions:
          type: array
          description: Permisos dashboard incluidos en el rol.
          items:
            $ref: '#/components/schemas/DashboardPermission'
        built_in:
          type: boolean
          description: Indica si el rol es administrado por el sistema.
          example: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del rol.
          example: '2024-03-20T15:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de última actualización del rol.
          example: '2024-03-20T15:30:00Z'
    RoleList:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    ApiKey:
      type: object
      x-tags:
        - API Keys
      description: |
        Las API keys permiten autenticar y autorizar el acceso a la API de Soyio.
        Cada API key tiene un entorno específico (sandbox o production) y puede tener un alcance limitado.
      required:
        - id
        - label
        - environment
        - scopes
        - created_at
      properties:
        id:
          type: string
          description: Identificador único de la API key (token). Empieza con `ak_sandbox_` o `ak_live_` dependiendo del entorno.
          example: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg
        label:
          type: string
          description: Etiqueta descriptiva de la API key
          example: Banking App
        environment:
          type: string
          enum:
            - sandbox
            - production
          description: Entorno al que pertenece la API key
          example: sandbox
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: 'Fecha y hora de expiración de la API key. Las claves de production por defecto expiran en 90 días, las de sandbox por defecto no expiran.'
          example: '2024-06-20T15:30:00Z'
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: Fecha y hora del último uso de la API key
          example: '2024-03-20T15:30:00Z'
        scopes:
          type: array
          description: Alcance de permisos para la API key. Lista de patrones de endpoints permitidos.
          items:
            type: string
          example:
            - /v1/identities/*
            - /v1/disclosure_requests/*
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la API key
          example: '2024-03-20T15:30:00Z'
        secret:
          type: string
          description: Token JWT secreto de la API key. Solo se incluye al momento de la creación o al renovarla.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        refresh_token:
          type: string
          description: |
            Token de actualización asociado a la API key. Solo se incluye cuando la clave tiene fecha de expiración y es creado o renovado mediante la API. Debe guardarse para extender la API key una vez vencida
          example: akrt_1B2M2Y8AsgTpgAmY7PhCfg
          nullable: true
    ApiKeyList:
      type: object
      properties:
        api_keys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ActionTokenCreateInput:
      type: object
      required:
        - context
        - kind
        - action_type
        - timestamp
      properties:
        context:
          type: string
          description: 'Contexto de la acción, libre. Quedará registrado en el action / commit asociado. Sirve mayormente para identificar rápidamente el contexto en el que se pidió el consentimiento.'
          example: web_signup
        kind:
          type: string
          description: Tipo de acción ("grant" o "revoke")
          enum:
            - grant
            - revoke
          example: grant
        action_type:
          type: string
          description: |
            Tipo específico de acción.
            Para templates REDEC, cuando `action_data` incluye `audio_reference` y `audio_hash`, el valor debe ser `voice_confirmation`.
            Para templates REDEC, cuando `action_type` es `voice_confirmation`, también se deben incluir `audio_reference` y `audio_hash`.
          enum:
            - opt_in_click
            - voice_confirmation
            - physical_confirmation
          example: opt_in_click
        timestamp:
          type: string
          format: date-time
          description: Fecha y hora de la acción
          example: '2024-03-20T15:30:00Z'
        selected_scopes:
          type: array
          description: |
            Subconjunto de scopes del template que representa la selección del usuario para esta acción.
            Si se omite, la acción aplica a todos los scopes del template.
          items:
            $ref: '#/components/schemas/ConsentTemplateScope'
        scope_selection_behavior:
          type: string
          description: |
            Semántica para manejar scopes no seleccionados en acciones `grant`.
            `replace` trata la selección como intención final (puede revocar scopes no seleccionados).
            `additive` agrega solo los scopes seleccionados sin revocar scopes no seleccionados.
          enum:
            - replace
            - additive
          default: replace
          example: additive
        action_data:
          type: object
          description: |
            Datos adicionales de la acción. Se permite cualquier campo adicional, pero se recomienda no exceder los 4KB de tamaño serializado en JSON.

            En caso de usar REDEC y se está tratando un consentimiento de audio, puede incluir los campos de `audio_reference` y `audio_hash`. Más información en la [documentación de REDEC](/docs/integration-guide/redec/consent-registration#consentimiento-verbal-con-audio).
            Para templates REDEC, cuando se envían ambos campos de audio, `action_type` debe ser `voice_confirmation`.
            Para templates REDEC, cuando `action_type` es `voice_confirmation`, se requieren ambos campos de audio.
          example:
            checkbox_id: cb_123
            audio_reference: 'https://example.com/audio/consent_12345.mp3'
            audio_hash: a3b2c1d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
        contextual_data:
          $ref: '#/components/schemas/ContextualData'
          description: Requerido cuando `action_type` es `opt_in_click`.
    ActionTokenResponse:
      type: object
      properties:
        action_token:
          type: string
          description: Token JWT de la acción de consentimiento
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    ConsentRevocationOriginEvent:
      type: object
      required:
        - system
        - event_id
      properties:
        system:
          type: string
          description: Sistema origen que dispara la revocación.
          example: core-banking
        event_id:
          type: string
          description: Identificador idempotente del evento origen.
          example: evt-12345
        occurred_at:
          type: string
          format: date-time
          nullable: true
          description: Fecha/hora de ocurrencia del evento origen.
          example: '2026-02-11T15:10:00Z'
    ConsentRevocationCreateInput:
      type: object
      required:
        - consent_template_id
        - reason_code
        - origin_event
      properties:
        identity_id:
          type: string
          description: Identificador de identidad a revocar. No puede combinarse con `entity_id` ni `user_reference`.
          example: id_1B2M2Y8AsgTpgAmY7PhCfg
        entity_id:
          type: string
          description: Identificador de entidad a revocar. Se prioriza sobre `user_reference`.
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        user_reference:
          type: string
          description: Referencia de usuario para resolver la entidad cuando no se entrega `entity_id`.
          example: user_123
        consent_template_id:
          type: string
          description: Identificador del template de consentimiento.
          example: constpl_1B2M2Y8AsgTpgAmY7PhCfg
        consent_template_version:
          type: integer
          nullable: true
          description: 'Versión específica del template. Si se omite, usa latest.'
          example: 3
        selected_scopes:
          type: array
          description: |
            Subconjunto de scopes a revocar. Si se omite, intenta revocar todos los scopes del template,
            respetando los guardrails de `revocable_data_uses`.
          items:
            $ref: '#/components/schemas/ConsentTemplateScope'
        reason_code:
          type: string
          description: Código de motivo de revocación definido por la empresa.
          example: contract_ended
        reason_text:
          type: string
          nullable: true
          description: Texto libre opcional con más contexto.
          example: Contrato finalizado en sistema core
        origin_event:
          $ref: '#/components/schemas/ConsentRevocationOriginEvent'
    CompanyConsentRevocation:
      x-tags:
        - Consent revocations
      type: object
      required:
        - id
        - subject_id
        - subject_type
        - consent_template_id
        - consent_template_version
        - reason_code
        - origin_event
        - status
        - created_at
      properties:
        id:
          type: string
          description: Identificador único de la revocación iniciada por la empresa.
          example: ccrev_1B2M2Y8AsgTpgAmY7PhCfg
        subject_id:
          type: string
          description: Identificador del sujeto afectado (`ent_` o `id_`).
          example: ent_1B2M2Y8AsgTpgAmY7PhCfg
        subject_type:
          type: string
          enum:
            - Entity
            - Identity
          example: Entity
        consent_template_id:
          type: string
          description: Identificador del template de consentimiento.
          example: constpl_1B2M2Y8AsgTpgAmY7PhCfg
        consent_template_version:
          type: integer
          example: 3
        selected_scopes:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ConsentTemplateScope'
        reason_code:
          type: string
          example: contract_ended
        reason_text:
          type: string
          nullable: true
          example: Contrato finalizado en sistema core
        origin_event:
          $ref: '#/components/schemas/ConsentRevocationOriginEvent'
        status:
          type: string
          enum:
            - pending
            - applied
            - no_changes
            - failed
          example: applied
        agreement_id:
          type: string
          nullable: true
          description: Identificador del acuerdo resultante cuando hubo cambios efectivos.
          example: agr_1B2M2Y8AsgTpgAmY7PhCfg
        agreement_version:
          type: integer
          nullable: true
          description: Versión del acuerdo resultante cuando hubo cambios efectivos.
          example: 4
        created_at:
          type: string
          format: date-time
          example: '2026-02-11T15:10:00Z'
    EvidenceConsentMethod:
      type: object
      description: 'Método de captura del consentimiento. Es **requerido** si se crea el [action token a través de nuestra API](/docs/api/resources/create-action-token). En caso de usar nuestro embed, este campo no es necesario y **será ignorado**.'
      required:
        - channel
      properties:
        channel:
          type: string
          description: Canal de captura del consentimiento
          enum:
            - website
            - chatbot
            - whatsapp
          example: website
        capture_source:
          type: string
          description: Nombre de la entidad plataforma usada para capturar el consentimiento
          example: Salesforce
        metadata:
          type: object
          description: 'Metadatos adicionales de la forma de captura del consentimiento. Pueden ser referencias a flujos completos (identificadores de chats, urls de tickets, etc.) o descripciones de la forma de captura.'
          example:
            details: se le mostró al usuario el texto de consentimiento en un chatbot de whatsapp
            chat_id: 13928
    ConsentActionStatus:
      type: object
      description: Estadísticas de acciones de consentimiento
      properties:
        count:
          type: integer
          description: Número total de acciones de consentimiento
          example: 150
        acceptance_rates:
          type: array
          description: Tasas de aceptación por template de consentimiento
          items:
            type: object
            properties:
              actions_count:
                type: integer
                description: Número de acciones para este template
                example: 75
              ratio:
                type: number
                format: float
                description: Ratio de acciones para este template respecto al total
                example: 0.5
              entities_count:
                type: integer
                description: Número de entidades únicas que han consentido este template
                example: 25
              consent_template:
                type: object
                description: Información del template de consentimiento
                properties:
                  token:
                    type: string
                    description: Token del template de consentimiento
                    example: ct_abc123
                  name:
                    type: string
                    description: Nombre del template de consentimiento
                    example: Consentimiento de marketing
                  is_optional:
                    type: boolean
                    description: Si el template es opcional
                    example: true
                  version:
                    type: integer
                    description: La versión del template de consentimiento asociado
                    example: 1
    ConsentCommitStats:
      type: object
      description: Estadísticas de commits de consentimiento
      properties:
        count:
          type: integer
          description: Número total de commits de consentimiento
          example: 100
        template_combinations:
          type: array
          description: Combinaciones de templates utilizadas en los commits
          items:
            type: object
            properties:
              commits_count:
                type: integer
                description: Número de commits para esta combinación
                example: 50
              acceptance_rate:
                type: number
                format: float
                description: Tasa de aceptación para esta combinación
                example: 0.5
              entities_count:
                type: integer
                description: Número de entidades únicas para esta combinación
                example: 20
              templates:
                type: array
                description: Templates incluidos en esta combinación
                items:
                  type: object
                  properties:
                    token:
                      type: string
                      description: Token del template de consentimiento
                      example: ct_abc123
                    name:
                      type: string
                      description: Nombre del template de consentimiento
                      example: Consentimiento de marketing
                    is_optional:
                      type: boolean
                      description: Si el template es opcional
                      example: true
    DisclosureRequestStats:
      type: object
      description: Estadísticas de disclosures
      properties:
        count:
          type: integer
          description: Número total de disclosures
          example: 200
        strict_conversion_rate:
          type: number
          format: float
          description: Tasa de conversión estricta (usuarios únicos que completaron vs usuarios únicos que intentaron)
          example: 0.75
        conversion_rate:
          type: number
          format: float
          description: Tasa de conversión general (solicitudes completadas vs total de solicitudes)
          example: 0.8
        status_distribution:
          type: object
          description: Distribución de disclosures por estado
          additionalProperties:
            type: number
            format: float
          example:
            granted: 0.6
            pending: 0.3
            rejected: 0.1
        average_disclosures_per_user:
          type: number
          format: float
          description: Promedio de disclosures por usuario
          example: 1.5
    Report:
      x-tags:
        - Reports
      type: object
      description: Representa un reporte generado para la empresa
      properties:
        id:
          type: string
          description: Identificador único del reporte
          example: rep_1B2M2Y8AsgTpgAmY7PhCfg
        starts_at:
          type: string
          format: date-time
          description: Fecha y hora de inicio del período del reporte
          example: '2025-06-01T00:00:00Z'
        ends_at:
          type: string
          format: date-time
          description: Fecha y hora de fin del período del reporte
          example: '2025-06-30T23:59:59Z'
        content:
          type: object
          description: Contenido del reporte en formato específico según el tipo de reporte
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del reporte
          example: '2025-07-01T10:30:00Z'
        generated_by:
          type: object
          description: Usuario de la empresa que generó el reporte
          nullable: true
          properties:
            id:
              type: string
              description: Identificador único del usuario
              example: cu_1B2M2Y8AsgTpgAmY7PhCfg
            email:
              type: string
              description: Email del usuario
              example: usuario@empresa.com
    ReportIndexList:
      type: object
      description: Lista de reportes con metadatos de paginación
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ReportInput:
      type: object
      required:
        - kind
        - starts_at
        - ends_at
      description: Datos requeridos para crear un nuevo reporte
      properties:
        kind:
          type: string
          description: Tipo de reporte a generar
          enum:
            - rdc30
            - rdc40
          example: rdc30
        starts_at:
          type: string
          format: date-time
          description: Fecha y hora de inicio del período del reporte en formato ISO 8601
          example: '2025-06-01T00:00:00Z'
        ends_at:
          type: string
          format: date-time
          description: Fecha y hora de fin del período del reporte en formato ISO 8601
          example: '2025-06-30T23:59:59Z'
    Export:
      x-tags:
        - Exports
      type: object
      description: Exportación asíncrona de recursos
      properties:
        id:
          type: string
          description: Identificador único de la exportación
          example: exp_1B2M2Y8AsgTpgAmY7PhCfg
        resource_kind:
          type: string
          description: Recurso exportado
          enum:
            - consent_actions
            - consent_commits
          example: consent_actions
        output_format:
          type: string
          description: Formato de salida
          enum:
            - csv
          example: csv
        status:
          type: string
          description: Estado actual de la exportación
          enum:
            - pending
            - processing
            - completed
            - failed
          example: processing
        records_count:
          type: integer
          nullable: true
          description: Número total de registros exportados cuando la exportación finaliza
          example: 1200
        error_message:
          type: string
          nullable: true
          description: Mensaje de error cuando la exportación falla
          example: Export record limit exceeded. Maximum allowed is 100000 records
        file_name:
          type: string
          nullable: true
          description: Nombre del archivo generado
          example: consent-actions-2026-02-19.csv
        download_url:
          type: string
          nullable: true
          description: URL firmada para descargar el archivo generado
          example: 'https://app.soyio.id/attachments/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBB'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación
          example: '2026-02-19T15:30:00Z'
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Fecha y hora de finalización
          example: '2026-02-19T15:31:22Z'
    ExportIndexList:
      type: object
      description: Lista de exportaciones con metadatos de paginación
      properties:
        exports:
          type: array
          items:
            $ref: '#/components/schemas/Export'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
    ExportInput:
      type: object
      required:
        - resource
      properties:
        resource:
          type: string
          description: Recurso a exportar
          enum:
            - consent_actions
            - consent_commits
          example: consent_actions
        output_format:
          type: string
          description: Formato de salida. Actualmente sólo se soporta CSV.
          enum:
            - csv
          default: csv
          example: csv
        where:
          type: string
          description: Filtros en formato JSON serializado
          nullable: true
          example: '{"kind":{"=":"grant"}}'
        order_by:
          type: string
          description: Campo y dirección de ordenamiento
          nullable: true
          example: created_at DESC
    ConsentActionRedecInput:
      type: object
      required:
        - action_token
        - entity_nin
      description: Datos requeridos para crear una acción de consentimiento a través del endpoint REDEC
      properties:
        action_token:
          type: string
          description: Token de acción que contiene la información codificada del consentimiento
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        entity_nin:
          type: string
          description: NIN (Número de Identificación Nacional) de la entidad
          example: 12.345.678-5
        executive_nin:
          type: string
          description: NIN del ejecutivo que procesa la acción (opcional)
          example: 11.111.111-1
          nullable: true
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente (se usa para crear o encontrar la entidad)
          example: redec-entity-123
          nullable: true
        entity_id:
          type: string
          description: ID de la entidad existente (alternativa a user_reference)
          example: ent_5F6Q6C2EwkXtkEpB1TlGjk
          nullable: true
        consent_method:
          type: object
          description: 'Método de captura del consentimiento. **Solo es requerido** si se crea el [action token a través de nuestra API](/docs/api/resources/create-action-token). En caso de usar nuestro embed, este campo no es necesario y **será ignorado**.'
          nullable: true
          allOf:
            - $ref: '#/components/schemas/EvidenceConsentMethod'
            - nullable: true
    ConsentCommitRedecInput:
      type: object
      required:
        - consent_actions
        - entity_nin
      description: Datos requeridos para crear un consent commit a través del endpoint REDEC
      properties:
        consent_actions:
          type: array
          description: Array de action tokens que contienen la información codificada de los consentimientos
          minItems: 1
          items:
            type: object
            required:
              - action_token
            properties:
              action_token:
                type: string
                description: Token de acción que contiene la información codificada del consentimiento
                example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        entity_nin:
          type: string
          description: NIN (Número de Identificación Nacional) de la entidad
          example: 12.345.678-5
        executive_nin:
          type: string
          description: NIN del ejecutivo que procesa la acción (opcional)
          example: 11.111.111-1
          nullable: true
        user_reference:
          type: string
          description: Referencia del usuario en el sistema del cliente (se usa para crear o encontrar la entidad)
          example: redec-entity-123
          nullable: true
        entity_id:
          type: string
          description: ID de la entidad existente (alternativa a user_reference)
          example: ent_5F6Q6C2EwkXtkEpB1TlGjk
          nullable: true
        consent_method:
          type: object
          description: 'Método de captura del consentimiento. **Solo es requerido** si se crea el [action token a través de nuestra API](/docs/api/resources/create-action-token). En caso de usar nuestro embed, este campo no es necesario y **será ignorado**.'
          nullable: true
          allOf:
            - $ref: '#/components/schemas/EvidenceConsentMethod'
            - nullable: true
    GovernmentCheckRequest:
      x-tags:
        - Government check requests
      type: object
      description: |
        Los government check requests representan solicitudes de verificación de identidad contra el registro civil,
        sin necesidad de biometría.
      properties:
        id:
          type: string
          description: Identificador único del government check request.
          example: govcheck_1B2M2Y8AsgTpgAmY7PhCfg
        status:
          type: string
          enum:
            - pending
            - validating
            - successful
            - failed
          description: Estado actual del government check request.
        subject_id:
          type: string
          nullable: true
          description: Identificador del sujeto asociado (Identity o Entity).
          example: ent_5F6Q6C2EwkXtkEpB1TlGjk
        user_reference:
          type: string
          description: Referencia de usuario de tu sistema.
          example: user_123
        validation_errors:
          type: array
          description: |
            Errores de validación (solo presente cuando el estado es `failed`).

            Códigos posibles:
            - `auth-074` / `invalid_document_number`: Número de documento inválido.
            - `auth-075` / `government_api_error`: La base de datos gubernamental no estaba disponible al momento de la consulta.
            - `auth-076` / `document_not_valid`: El documento no se encuentra vigente.
          items:
            type: object
            properties:
              code:
                type: string
                description: Código de error.
                enum:
                  - auth-074
                  - auth-075
                  - auth-076
                example: auth-074
              type:
                type: string
                description: Tipo de error.
                enum:
                  - document
                example: document
              message:
                type: string
                description: Identificador del error.
                enum:
                  - document_not_valid
                  - invalid_document_number
                  - government_api_error
                example: document_not_valid
              detail:
                type: string
                description: Mensaje legible del error.
                example: Número de documento inválido.
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del government check request.
    GovernmentCheckRequestInput:
      type: object
      required:
        - nin
        - document_number
      properties:
        nin:
          type: string
          description: RUT del titular (formato chileno).
          example: 12345678-9
        document_number:
          type: string
          description: Número de documento de identidad.
          example: '123456789'
        subject_id:
          type: string
          nullable: true
          description: Token del sujeto existente (Identity o Entity). Mutuamente exclusivo con `user_reference`.
          example: ent_5F6Q6C2EwkXtkEpB1TlGjk
        user_reference:
          type: string
          nullable: true
          description: Referencia de usuario de tu sistema. Mutuamente exclusivo con `subject_id`.
          example: user_123
    GovernmentCheckRequestList:
      type: object
      properties:
        government_check_requests:
          type: array
          items:
            $ref: '#/components/schemas/GovernmentCheckRequest'
        metadata:
          $ref: '#/components/schemas/FilterOrderAndPaginationMetadata'
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Esquema de autenticación mediante una API key proporcionada en el header de las solicitudes.
    entity_session_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Esquema de autenticación mediante un token JWT de sesión de entidad proporcionado en el header de las solicitudes. Se genera usando el endpoint /entities/session_token y tiene una duración de 15 minutos.
webhooks:
  agreementCreated:
    post:
      tags:
        - Agreements
      summary: Created
      operationId: agreementCreated
      description: |
        #### Nombre del evento: `agreement.created`.
        Se envía cuando se ha creado un nuevo acuerdo (agreement) en el sistema.
      requestBody:
        description: Contiene el recurso Agreement actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - agreement.created
                  description: Nombre del evento
                payload:
                  allOf:
                    - $ref: '#/components/schemas/Agreement'
                    - type: object
                      description: Datos del acuerdo actualizado
                      properties:
                        evidence:
                          $ref: '#/components/schemas/Evidence'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  agreementUpdated:
    post:
      tags:
        - Agreements
      summary: Updated
      operationId: agreementUpdated
      description: |
        #### Nombre del evento: `agreement.updated`.
        Se envía cuando un acuerdo (agreement) existente ha sido actualizado.
      requestBody:
        description: Contiene el recurso Agreement actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - agreement.updated
                  description: Nombre del evento
                payload:
                  allOf:
                    - $ref: '#/components/schemas/Agreement'
                    - type: object
                      description: Datos del acuerdo actualizado
                      properties:
                        evidence:
                          $ref: '#/components/schemas/Evidence'
                        changes:
                          type: object
                          description: Detalle de cambios en los permisos específicos de esta nueva versión del acuerdo
                          properties:
                            created:
                              type: array
                              description: Permisos que se han agregado en esta nueva versión del acuerdo
                              items:
                                $ref: '#/components/schemas/DataPermission'
                            removed:
                              type: array
                              description: Permisos que se han eliminado en esta nueva versión del acuerdo
                              items:
                                $ref: '#/components/schemas/DataPermission'
                            extended:
                              type: array
                              description: Permisos que se han extendido en esta nueva versión del acuerdo
                              items:
                                $ref: '#/components/schemas/DataPermission'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  apiKeyCreated:
    post:
      tags:
        - API Keys
      summary: Created
      operationId: apiKeyCreated
      description: |
        #### Nombre del evento: `api_key.created`.
        Se envía cuando se ha creado una nueva API key.
      requestBody:
        description: Contiene el recurso ApiKey actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - api_key.created
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la API key creada
                    - $ref: '#/components/schemas/ApiKey'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  apiKeyUpdated:
    post:
      tags:
        - API Keys
      summary: Updated
      operationId: apiKeyUpdated
      description: |
        #### Nombre del evento: `api_key.updated`.
        Se envía cuando una API key existente ha sido actualizada.
      requestBody:
        description: Contiene el recurso ApiKey actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - api_key.updated
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la API key actualizada
                    - $ref: '#/components/schemas/ApiKey'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  apiKeyDestroyed:
    post:
      tags:
        - API Keys
      summary: Destroyed
      operationId: apiKeyDestroyed
      description: |
        #### Nombre del evento: `api_key.destroyed`.
        Se envía cuando una API key ha sido eliminada del sistema.
      requestBody:
        description: Contiene información de la API key eliminada. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - api_key.destroyed
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la API key eliminada
                    - $ref: '#/components/schemas/ApiKey'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  authAttemptSuccessful:
    post:
      tags:
        - Auth attempts
      summary: Successful
      operationId: authAttemptSuccessful
      description: |
        #### Nombre del evento: `auth_attempt.successful`.
        Se envía cuando un intento de autenticación se ha completado exitosamente.
      requestBody:
        description: Contiene el recurso AuthAttempt actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - auth_attempt.successful
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos del intento de autenticación actualizado
                    - $ref: '#/components/schemas/AuthAttempt'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  authAttemptFailed:
    post:
      tags:
        - Auth attempts
      summary: Failed
      operationId: authAttemptFailed
      description: |
        #### Nombre del evento: `auth_attempt.failed`.
        Se envía cuando un intento de autenticación ha fallado.
      requestBody:
        description: Contiene el recurso AuthAttempt actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - auth_attempt.failed
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos del intento de autenticación actualizado
                    - $ref: '#/components/schemas/AuthAttempt'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  authRequestSuccessful:
    post:
      tags:
        - Auth requests
      summary: Successful
      operationId: authRequestSuccessful
      description: |
        #### Nombre del evento: `auth_request.successful`.
        Se envía cuando un request de autenticación se ha completado exitosamente.
      requestBody:
        description: Contiene el recurso AuthRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - auth_request.successful
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos del request de autenticación actualizado
                    - $ref: '#/components/schemas/AuthRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  consentActionCreated:
    post:
      tags:
        - Consent actions
      summary: Created
      operationId: consentActionCreated
      description: |
        #### Nombre del evento: `consent_action.created`.
        Se envía cuando se ha creado una nueva acción de consentimiento.
      requestBody:
        description: Contiene el recurso ConsentAction actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - consent_action.created
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la acción de consentimiento actualizada
                    - $ref: '#/components/schemas/ConsentAction'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  consentActionRedecReceiptGenerated:
    post:
      tags:
        - REDEC
      summary: REDEC Receipt Generated
      operationId: consentActionRedecReceiptGenerated
      description: |
        #### Nombre del evento: `consent_action.redec_receipt_generated`.
        Se envía cuando se ha generado exitosamente el PDF de recibo REDEC para una acción de consentimiento. Este evento se gatilla después de que el PDF ha sido creado y guardado en el sistema.
      requestBody:
        description: 'Contiene información del recibo REDEC generado, incluyendo la URL del PDF y su hash de verificación.'
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - consent_action.redec_receipt_generated
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del recibo REDEC generado
                  properties:
                    consent_action_id:
                      type: string
                      description: Token de la acción de consentimiento
                      example: consact_1B2M2Y8AsgTpgAmY7PhCfg
                    user_reference:
                      type: string
                      description: Referencia de usuario del sistema del cliente
                      example: user_123
                    redec_receipt_pdf:
                      type: string
                      format: uri
                      description: URL del PDF del recibo REDEC
                      example: 'https://storage.example.com/receipts/redec_receipt_123.pdf'
                    redec_pdf_hash:
                      type: string
                      description: Hash SHA256 del PDF para verificación de integridad
                      example: a1b2c3d4e5f6...
                    redec_id:
                      type: string
                      description: Identificador único del proceso REDEC
                      example: redec_xyz789
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  consentCommitCreated:
    post:
      tags:
        - Consent commits
      summary: Created
      operationId: consentCommitCreated
      description: |
        #### Nombre del evento: `consent_commit.created`.
        Se envía cuando se ha creado una nueva agrupación de acciones de consentimiento.
      requestBody:
        description: Contiene el recurso ConsentCommit actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - consent_commit.created
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la agrupación de acciones de consentimiento actualizada
                    - $ref: '#/components/schemas/ConsentCommit'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestCreated:
    post:
      tags:
        - Data subject requests
      summary: Created
      operationId: dataSubjectRequestCreated
      description: |
        #### Nombre del evento: `data_subject_request.created`.
        Se envía cuando se ha creado una nueva solicitud de ejercicio de derechos (`data subject request`).
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.created
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestUpdated:
    post:
      tags:
        - Data subject requests
      summary: Updated
      operationId: dataSubjectRequestUpdated
      description: |
        #### Nombre del evento: `data_subject_request.updated`.
        Se envía cuando una solicitud de ejercicio de derechos (`data subject request`) existente ha sido actualizada.
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.updated
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestValidating:
    post:
      tags:
        - Data subject requests
      summary: Validating
      operationId: dataSubjectRequestValidating
      description: |
        #### Nombre del evento: `data_subject_request.validating`.
        Se envía cuando una solicitud de ejercicio de derechos (`data subject request`) existente ha iniciado el proceso de validación.
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.validating
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestProcessing:
    post:
      tags:
        - Data subject requests
      summary: Processing
      operationId: dataSubjectRequestProcessing
      description: |
        #### Nombre del evento: `data_subject_request.processing`.
        Se envía cuando una solicitud de ejercicio de derechos (`data subject request`) existente ha iniciado el proceso de procesamiento. Esto ocurre después de una validación exitosa.
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.processing
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestResolved:
    post:
      tags:
        - Data subject requests
      summary: Resolved
      operationId: dataSubjectRequestResolved
      description: |
        #### Nombre del evento: `data_subject_request.resolved`.
        Se envía cuando una solicitud de ejercicio de derechos (`data subject request`) ha sido resuelta. Una solicitud resuelta significa que la solicitud fue aprobada o rechazada.
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.resolved
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  dataSubjectRequestDataMissmatch:
    post:
      tags:
        - Data subject requests
      summary: Data missmatch
      operationId: dataSubjectRequestDataMissmatch
      description: |
        #### Nombre del evento: `data_subject_request.data_missmatch`.
        Se envía cuando una solicitud de ejercicio de derechos (`data subject request`) se completó, pero cuando se validó la identidad los datos no coinciden con los de la solicitud.
      requestBody:
        description: Contiene el recurso DataSubjectRequest actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - data_subject_request.data_missmatch
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos de la solicitud de derechos actualizada
                    - $ref: '#/components/schemas/DataSubjectRequest'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  disclosureRequestGranted:
    post:
      tags:
        - Disclosure requests
      summary: Granted
      operationId: disclosureRequestGranted
      description: |
        #### Nombre del evento: `disclosure_request.granted`.
        Se envía cuando un `disclosure_request` ha sido completado exitosamente y se ha otorgado acceso a los datos solicitados.
      requestBody:
        description: Contiene información del evento de disclosure request completado exitosamente.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - disclosure_request.granted
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del evento de disclosure request
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario de tu sistema para el disclosure request
                      example: user_123
                    disclosure_request_id:
                      type: string
                      description: Identificador único del disclosure request
                      example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
                    identity_id:
                      type: string
                      description: Identificador único de la identidad creada
                      example: id_ma21KLsmaslopask912Aa2
                    validation_attempt_id:
                      type: string
                      description: Identificador del intento de validación (si existe)
                      example: va_1B2M2Y8AsgTpgAmY7PhCfg
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  disclosureRequestTimedOut:
    post:
      tags:
        - Disclosure requests
      summary: Timed out
      operationId: disclosureRequestTimedOut
      description: |
        #### Nombre del evento: `disclosure_request.timed_out`.
        Se envía cuando un `disclosure_request` ha expirado sin completarse.
      requestBody:
        description: Contiene información del evento de disclosure request que ha expirado.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - disclosure_request.timed_out
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del evento de disclosure request
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario de tu sistema para el disclosure request
                      example: user_123
                    disclosure_request_id:
                      type: string
                      description: Identificador único del disclosure request
                      example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  disclosureRequestFailed:
    post:
      tags:
        - Disclosure requests
      summary: Failed
      operationId: disclosureRequestFailed
      description: |
        #### Nombre del evento: `disclosure_request.failed`.
        Se envía cuando un `disclosure_request` ha fallado durante el proceso.
      requestBody:
        description: Contiene información del evento de disclosure request que ha fallado.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - disclosure_request.failed
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del evento de disclosure request
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario de tu sistema para el disclosure request
                      example: user_123
                    disclosure_request_id:
                      type: string
                      description: Identificador único del disclosure request
                      example: dreq_1B2M2Y8AsgTpgAmY7PhCfg
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  signatureAttemptSuccessful:
    post:
      tags:
        - Signature attempts
      summary: Successful
      operationId: signatureAttemptSuccessful
      description: |
        #### Nombre del evento: `signature_attempt.successful`.
        Se envía cuando un intento de firma de documento se ha completado exitosamente.
      requestBody:
        description: Contiene el recurso SignatureAttempt actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - signature_attempt.successful
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos del intento de firma actualizado
                    - $ref: '#/components/schemas/SignatureAttempt'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  signatureAttemptFailed:
    post:
      tags:
        - Signature attempts
      summary: Failed
      operationId: signatureAttemptFailed
      description: |
        #### Nombre del evento: `signature_attempt.failed`.
        Se envía cuando un intento de firma de documento ha fallado.
      requestBody:
        description: Contiene el recurso SignatureAttempt actualizado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - signature_attempt.failed
                  description: Nombre del evento
                payload:
                  allOf:
                    - type: object
                      description: Datos del intento de firma actualizado
                    - $ref: '#/components/schemas/SignatureAttempt'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  validationAttemptSuccessful:
    post:
      tags:
        - Validation attempts
      summary: Successful
      operationId: validationAttemptSuccessful
      description: |
        #### Nombre del evento: `validation_attempt.successful`.
        Se envía cuando un intento de validación de identidad se ha completado exitosamente.
      requestBody:
        description: 'Contiene información del intento de validación exitoso, incluyendo referencias al objeto requestable (DataSubjectRequest o DisclosureRequest).'
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - validation_attempt.successful
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del intento de validación exitoso
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario del sistema del cliente
                      example: user_123
                    requestable_type:
                      type: string
                      description: Tipo de objeto asociado (DataSubjectRequest o DisclosureRequest)
                      example: DataSubjectRequest
                    requestable_id:
                      type: string
                      description: Token del objeto requestable asociado
                      example: dsreq_1B2M2Y8AsgTpgAmY7PhCfg
                    validation_attempt_id:
                      type: string
                      description: Token del intento de validación
                      example: va_1B2M2Y8AsgTpgAmY7PhCfg
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  validationAttemptFailed:
    post:
      tags:
        - Validation attempts
      summary: Failed
      operationId: validationAttemptFailed
      description: |
        #### Nombre del evento: `validation_attempt.failed`.
        Se envía cuando un intento de validación de identidad ha fallado.
      requestBody:
        description: 'Contiene información del intento de validación fallido, incluyendo referencias al objeto requestable (DataSubjectRequest o DisclosureRequest) y los errores.'
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - validation_attempt.failed
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del intento de validación fallido
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario del sistema del cliente
                      example: user_123
                    requestable_type:
                      type: string
                      description: Tipo de objeto asociado (DataSubjectRequest o DisclosureRequest)
                      example: DataSubjectRequest
                    requestable_id:
                      type: string
                      description: Token del objeto requestable asociado
                      example: dsreq_1B2M2Y8AsgTpgAmY7PhCfg
                    validation_attempt_id:
                      type: string
                      description: Token del intento de validación
                      example: va_1B2M2Y8AsgTpgAmY7PhCfg
                    error_reason:
                      type: string
                      description: Razón del error de validación
                      example: document_validation_error
                    errors_array:
                      type: array
                      description: Array de errores detallados
                      items:
                        type: object
                        properties:
                          message:
                            type: string
                            description: Mensaje de error
                          code:
                            type: string
                            description: Código de error
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  agreementDataPermissionsExpired:
    post:
      tags:
        - Agreements
      summary: Data Permissions Expired
      operationId: agreementDataPermissionsExpired
      description: |
        #### Nombre del evento: `agreement.data_permissions_expired`.
        Se envía cuando uno o más permisos de uso de datos (`data_permissions`) en un acuerdo (agreement) han expirado. Este evento notifica que ciertos permisos ya no son válidos y que el tratamiento de datos relacionado debe cesar.
      requestBody:
        description: 'Contiene información del acuerdo, el sujeto y los permisos de datos que han expirado.'
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - agreement.data_permissions_expired
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos de los permisos expirados
                  properties:
                    agreement_id:
                      type: string
                      description: Token del acuerdo que contiene los permisos expirados
                      example: agr_1B2M2Y8AsgTpgAmY7PhCfg
                    subject_type:
                      type: string
                      description: Tipo de sujeto (identidad o entidad) asociado al acuerdo
                      example: ent_1B2M2Y8AsgTpgAmY7PhCfg
                      enum:
                        - Entity
                        - Identity
                    subject_id:
                      type: string
                      description: Token del sujeto (identidad o entidad) asociado al acuerdo
                      example: ent_1B2M2Y8AsgTpgAmY7PhCfg
                    expired_permissions:
                      type: array
                      description: 'Lista de permisos de datos que han expirado, serializados según el esquema DataPermission usando Api::Exposed::V1::DataPermissionSerializer'
                      items:
                        $ref: '#/components/schemas/DataPermission'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  reportCreated:
    post:
      tags:
        - Reports
      summary: Created
      operationId: reportCreated
      description: |
        #### Nombre del evento: `report.created`.
        Se envía cuando se ha generado un nuevo reporte en el sistema.
      requestBody:
        description: Contiene el recurso Report creado. El payload corresponde al esquema completo del recurso.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - report.created
                  description: Nombre del evento
                payload:
                  $ref: '#/components/schemas/Report'
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  redecRdc40NoChanges:
    post:
      tags:
        - Reports
      summary: RDC40 no changes
      operationId: redecRdc40NoChanges
      description: |
        #### Nombre del evento: `redec.rdc40_no_changes`.
        Se envía cuando no se encontraron eventos que gatillen la generación del reporte RDC40 en las últimas 24 horas.
        Los eventos gatillantes corresponden a solicitudes REDEC con ingreso, inicio de procesamiento o cierre.
      requestBody:
        description: Contiene el evento de ausencia de cambios para RDC40.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - redec.rdc40_no_changes
                  description: Nombre del evento
                payload:
                  type: object
                  description: Detalle del evento
                  properties:
                    detail:
                      type: string
                      description: Mensaje descriptivo del motivo
                      example: No triggering events for the last 24 hours.
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  governmentCheckRequestSuccessful:
    post:
      tags:
        - Government check requests
      summary: Successful
      operationId: governmentCheckRequestSuccessful
      description: |
        #### Nombre del evento: `government_check_request.successful`.
        Se envía cuando un government check request se ha completado exitosamente.
      requestBody:
        description: Contiene información del government check request completado exitosamente.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - government_check_request.successful
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del government check request
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario de tu sistema
                      example: user_123
                    government_check_request_id:
                      type: string
                      description: Identificador único del government check request
                      example: govcheck_1B2M2Y8AsgTpgAmY7PhCfg
                    subject_id:
                      type: string
                      nullable: true
                      description: Identificador del sujeto asociado
                      example: ent_5F6Q6C2EwkXtkEpB1TlGjk
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
  governmentCheckRequestFailed:
    post:
      tags:
        - Government check requests
      summary: Failed
      operationId: governmentCheckRequestFailed
      description: |
        #### Nombre del evento: `government_check_request.failed`.
        Se envía cuando un government check request ha fallado.
      requestBody:
        description: Contiene información del government check request fallido.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: ID único del evento
                  example: evt_1B2M2Y8AsgTpgAmY7PhCfg
                name:
                  type: string
                  enum:
                    - government_check_request.failed
                  description: Nombre del evento
                payload:
                  type: object
                  description: Datos del government check request
                  properties:
                    user_reference:
                      type: string
                      description: Referencia de usuario de tu sistema
                      example: user_123
                    government_check_request_id:
                      type: string
                      description: Identificador único del government check request
                      example: govcheck_1B2M2Y8AsgTpgAmY7PhCfg
                    subject_id:
                      type: string
                      nullable: true
                      description: Identificador del sujeto asociado
                      example: ent_5F6Q6C2EwkXtkEpB1TlGjk
                created_at:
                  type: string
                  format: date-time
                  description: Fecha y hora de creación del evento
      responses:
        '200':
          description: Webhook recibido correctamente
        4XX:
          description: Error en el procesamiento del webhook
