> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificar atestación

> Verifique el estado del registro, los metadatos del emisor y la evidencia disponible. Suministre el payload_b64url original exacto para verificar la firma criptográfica. Una búsqueda solo por ID o solo por huella digital de archivo devuelve INCOMPLETO con signature_verified falso si no se aplica un fallo más fuerte. VÁLIDO significa que la carga útil suministrada pasó las verificaciones de firma; no prueba la veracidad de las afirmaciones ni garantiza que se completaron las verificaciones opcionales de política y transparencia. Inspeccione las razones y log.proof_checked. Las solicitudes públicas no necesitan clave API; las solicitudes autenticadas están dentro del alcance y se miden con respecto al espacio de trabajo del llamante.

Verifique el estado actual de un registro y la evidencia disponible. Para verificar su firma criptográfica, envíe la **carga útil original firmada exacta** como `payload_b64url`. Un ID de registro o una huella digital de archivo por sí solos no pueden proporcionar esos bytes.

### Elija la verificación que necesita

| Entrada | Qué verifica |
| - | - |
| `attestation_id` | Encuentra un registro accesible y verifica su estado actual, metadatos del emisor y evidencia de registro disponible. |
| ID más `payload_b64url` | También verifica el resumen de la carga útil y la firma contra la clave pública registrada. Codifique los bytes originales; reformatear JSON puede cambiar esos bytes. |
| ID más `document_hash_hex` | Compara una huella digital SHA-256 proporcionada con la huella digital del documento registrada. Esto no reemplaza la verificación de la carga útil firmada. |

Una verificación solo por ID o solo por huella digital devuelve `INCOMPLETE` y `signature_verified: false` a menos que se aplique un resultado más fuerte como `REVOKED`, `EXPIRED` o `ALTERED`. Suministre la carga útil original para una verificación de firma completa.

Un `attestation` en línea debe identificar un registro registrado con `attestation_id`. El estado en línea y la identidad de la clave se cargan de ese registro; los campos proporcionados por el llamador no pueden anular su emisor o revocación. Utilice un verificador fuera de línea compatible para comprobaciones de firma independientes.

### Interpretar la respuesta

| Veredicto | Significado |
| - | - |
| `VALID` | La carga útil suministrada pasó su verificación de firma y no se devolvió ningún fallo de bloqueo. Inspeccione las razones y las verificaciones individuales. |
| `INCOMPLETE` | No se proporcionó el contenido original requerido; la firma no fue verificada. |
| `ALTERED` | Una carga útil, firma o huella digital de documento suministrada falló una verificación de integridad. |
| `REVOKED` | El registro ha sido revocado. |
| `SUPERSEDED` | Un registro más reciente reemplaza a este. Solicite al emisor su registro actual. |
| `EXPIRED` | El registro o la clave de firma han caducado. |
| `INVALID` | Falló una entrada requerida o una verificación. |
| `NOT_FOUND` | Ningún registro accesible coincidió con la solicitud y su entorno. |
| `UNKNOWN_ISSUER` | La clave de firma del emisor no pudo ser aceptada. |

`signature_verified` informa específicamente la verificación de la firma. `log.proof_checked` informa la verificación exitosa de la inclusión de transparencia. Una prueba faltante produce una razón y un índice de hoja nulo; cero es una primera hoja legítima. Un valor `expires_at_unix` ausente no significa que se deba inventar una nueva fecha de vencimiento para un registro histórico.

> [!WARNING]
>
> Una firma válida no prueba la propiedad, la validez legal o la veracidad de cada afirmación. Lea `reasons`, la gobernanza actual del emisor y la evidencia disponible antes de confiar en un registro. Las políticas opcionales o las verificaciones de registro pueden no estar disponibles incluso cuando la firma de la carga útil pasa.

### Autenticación y límites

La verificación pública no requiere una clave API. Las llamadas autenticadas utilizan el espacio de trabajo y el entorno del llamante y pueden estar sujetas a su asignación de verificación. Los límites de velocidad del servicio aún se aplican a las solicitudes públicas. Un registro privado o de sandbox puede no estar disponible a través de una búsqueda de producción anónima.

Comparta un registro accesible usando `https://verify.truthlocks.com/proof/{attestation_id}`. Una URL compartida no otorga acceso a cargas útiles privadas.


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/verify
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/verify:
    post:
      tags:
        - Verification
      summary: Verificar atestación
      description: >-
        Verifique el estado del registro, los metadatos del emisor y la
        evidencia disponible. Suministre el payload_b64url original exacto para
        verificar la firma criptográfica. Una búsqueda solo por ID o solo por
        huella digital de archivo devuelve INCOMPLETO con signature_verified
        falso si no se aplica un fallo más fuerte. VÁLIDO significa que la carga
        útil suministrada pasó las verificaciones de firma; no prueba la
        veracidad de las afirmaciones ni garantiza que se completaron las
        verificaciones opcionales de política y transparencia. Inspeccione las
        razones y log.proof_checked. Las solicitudes públicas no necesitan clave
        API; las solicitudes autenticadas están dentro del alcance y se miden
        con respecto al espacio de trabajo del llamante.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                attestation:
                  description: >-
                    Sobre de búsqueda en línea. Se requiere un attestation_id
                    registrado aquí o a nivel de solicitud. El estado
                    almacenado, el emisor, la clave y la hora de emisión son
                    autoritativos; las copias suministradas no pueden anularlos.
                  nullable: true
                  properties:
                    attestation_id:
                      type: string
                    document_hash:
                      type: string
                    expires_at_unix:
                      type: integer
                      format: int64
                      nullable: true
                      description: >-
                        Caducidad firmada registrada en segundos Unix; nulo
                        significa que no se registra ninguna caducidad. A los
                        registros heredados no se les asigna una nueva
                        caducidad.
                    issued_at_unix:
                      type: integer
                    issuer_id:
                      type: string
                    log:
                      type: object
                      properties:
                        log_id:
                          type: string
                        leaf_index:
                          type: integer
                          nullable: true
                          description: >-
                            Índice de hoja de transparencia basado en cero. Nulo
                            significa que no se pudo recuperar la referencia del
                            registro; cero es una entrada válida.
                        status:
                          type: string
                          enum:
                            - recorded
                            - unavailable
                          description: >-
                            Disponibilidad de la referencia del registro
                            almacenado; esto no establece un veredicto de
                            inclusión verificado.
                        leaf_hash:
                          type: string
                        proof_url:
                          type: string
                    payload_hash:
                      type: string
                    signature:
                      type: object
                      properties:
                        alg:
                          type: string
                        kid:
                          type: string
                        value:
                          type: string
                    status:
                      type: string
                    tenant_id:
                      type: string
                      format: uuid
                    version:
                      type: string
                  type: object
                attestation_id:
                  type: string
                document_hash_hex:
                  type: string
                payload_b64url:
                  type: string
              type: object
      responses:
        '200':
          description: Resultado de la verificación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                valid:
                  summary: Valid attestation
                  value:
                    verdict: VALID
                    valid: true
                    details:
                      issuer_id: 550e8400-e29b-41d4-a716-446655440000
                      issuer_name: Acme University
                      log_index: 42
                revoked:
                  summary: Revoked attestation
                  value:
                    verdict: REVOKED
                    valid: false
                    details:
                      revoked_at: '2026-01-13T15:00:00.000Z'
                      reason: Certificate holder no longer employed
      security:
        - APIKey: []
        - {}
components:
  schemas:
    VerifyResponse:
      type: object
      required:
        - verdict
      description: >-
        Evidencia de verificación pública. Inspeccione las razones y las
        comprobaciones individuales; una comprobación solo de ID no verifica el
        contenido original proporcionado por el llamante.
      properties:
        verdict:
          $ref: '#/components/schemas/Verdict'
        signature_verified:
          type: boolean
          description: >-
            Verdadero solo cuando la carga útil original suministrada pasó la
            verificación de firma criptográfica. Las comprobaciones solo por ID
            y solo por huella digital devuelven falso.
        reasons:
          type: array
          items:
            type: string
        attestation_id:
          type: string
          format: uuid
        issuer_id:
          type: string
          format: uuid
        expires_at_unix:
          type: integer
          format: int64
          nullable: true
          description: >-
            Caducidad firmada registrada en segundos Unix; nulo significa que no
            se registra ninguna caducidad. A los registros heredados no se les
            asigna una nueva caducidad.
        issued_at_unix:
          type: integer
          format: int64
          description: >-
            Tiempo de emisión original almacenado en segundos Unix. Este no es
            el momento de la verificación actual o la descarga del certificado.
            Ausente si no está disponible.
        kid:
          type: string
          description: Identificador de clave de firma.
        alg:
          type: string
          description: Algoritmo de firma declarado.
        payload_hash:
          type: string
          description: Resumen SHA-256 codificado en Base64url de la carga útil canónica.
        document_hash:
          type: string
          description: >-
            Huella digital hexadecimal SHA-256 del archivo original, cuando se
            almacena.
        log:
          type: object
          properties:
            log_id:
              type: string
            leaf_index:
              type: integer
              format: int64
              nullable: true
              description: >-
                Índice de la hoja de transparencia verificado; nulo cuando la
                verificación de la prueba no estaba disponible. Cero es una
                primera hoja válida.
            leaf_hash:
              type: string
              description: >-
                Resumen de la hoja de inclusión verificado, cuando esté
                disponible.
            proof_checked:
              type: boolean
              description: >-
                Si la inclusión de transparencia se verificó correctamente para
                esta respuesta.
        governance:
          type: object
          properties:
            issuer_display_name:
              type: string
            issuer_status:
              type: string
            issuer_trust_tier:
              type: string
            issuer_risk_rating:
              type: string
            issuer_jurisdiction:
              type: string
            primary_color:
              type: string
            accent_color:
              type: string
            logo_url:
              type: string
            snapshot_status:
              type: string
            snapshot_trust_tier:
              type: string
            snapshot_risk_rating:
              type: string
            snapshot_jurisdiction:
              type: string
    Verdict:
      type: string
      enum:
        - VALID
        - INCOMPLETE
        - INVALID
        - REVOKED
        - ALTERED
        - SUPERSEDED
        - EXPIRED
        - UNKNOWN_ISSUER
        - NOT_FOUND
      description: >-
        Inspeccione las razones, las entradas de verificación proporcionadas y
        log.proof_checked junto con este veredicto. VÁLIDO por sí solo no
        establece la propiedad ni prueba todas las afirmaciones en el registro.
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.