> ## 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 Atestado

> Verifique o status do registro, metadados do emissor e evidências disponíveis. Forneça o payload_b64url original exato para verificar a assinatura criptográfica. Uma pesquisa apenas por ID ou apenas por impressão digital de arquivo retorna INCOMPLETO com signature_verified false se nenhuma falha mais forte se aplicar. VÁLIDO significa que o payload fornecido passou nas verificações de assinatura; isso não prova a veracidade das reivindicações nem garante que as verificações opcionais de política e transparência foram concluídas. Inspecione os motivos e log.proof_checked. Solicitações públicas não precisam de chave de API; solicitações autenticadas são escopadas e medidas em relação ao espaço de trabalho do chamador.

Verifique o status atual de um registro e as evidências disponíveis. Para verificar sua assinatura criptográfica, envie o **payload assinado original exato** como `payload_b64url`. Um ID de registro ou impressão digital de arquivo sozinho não pode fornecer esses bytes.

### Escolha a verificação que você precisa

| Entrada | O que verifica |
| - | - |
| `attestation_id` | Encontra um registo acessível e verifica o seu estado atual, metadados do emissor e evidências de registo disponíveis. |
| ID mais `payload_b64url` | Também verifica o resumo da carga útil e a assinatura em relação à chave pública registrada. Codifique os bytes originais; a reformatação de JSON pode alterar esses bytes. |
| ID mais `document_hash_hex` | Compara uma impressão digital SHA-256 fornecida com a impressão digital do documento registrada. Isso não substitui a verificação da carga útil assinada. |

Uma verificação somente por ID ou somente por impressão digital retorna `INCOMPLETE` e `signature_verified: false`, a menos que um resultado mais forte, como `REVOKED`, `EXPIRED` ou `ALTERED`, se aplique. Forneça o payload original para uma verificação de assinatura completa.

Um `attestation` inline deve identificar um registo registado com `attestation_id`. O status online e a identidade da chave são carregados desse registo; os campos fornecidos pelo chamador não podem substituir o seu emissor ou revogação. Use um verificador offline compatível para verificações de assinatura autónomas.

### Interpretar a resposta

| Veredito | Significado |
| - | - |
| `VALID` | O payload fornecido passou na verificação de assinatura e nenhuma falha de bloqueio foi retornada. Inspecione os motivos e as verificações individuais. |
| `INCOMPLETE` | O conteúdo original necessário não foi fornecido; a assinatura não foi verificada. |
| `ALTERED` | Uma carga útil, assinatura ou impressão digital de documento fornecida falhou em uma verificação de integridade. |
| `REVOKED` | O registro foi revogado. |
| `SUPERSEDED` | Um registro mais recente substitui este. Peça ao emissor seu registro atual. |
| `EXPIRED` | O registro ou a chave de assinatura expirou. |
| `INVALID` | Uma entrada ou verificação obrigatória falhou. |
| `NOT_FOUND` | Nenhum registro acessível correspondeu à solicitação e ao seu ambiente. |
| `UNKNOWN_ISSUER` | A chave de assinatura do emissor não pôde ser aceita. |

`signature_verified` relata especificamente a verificação da assinatura. `log.proof_checked` relata a verificação bem-sucedida da inclusão de transparência. Uma prova ausente produz uma razão e um índice de folha nulo; zero é uma primeira folha legítima. Um valor `expires_at_unix` ausente não significa que uma nova expiração deva ser inventada para um registro histórico.

> [!WARNING]
>
> Uma assinatura válida não prova propriedade, validade legal ou a verdade de cada reivindicação. Leia `reasons`, a governança atual do emissor e as evidências disponíveis antes de confiar em um registro. As verificações opcionais de política ou log podem não estar disponíveis mesmo quando a assinatura da carga útil é aprovada.

### Autenticação e limites

A verificação pública não requer uma chave de API. Chamadas autenticadas usam o espaço de trabalho e o ambiente do chamador e podem estar sujeitas à sua permissão de verificação. Os limites de taxa de serviço ainda se aplicam a solicitações públicas. Um registro privado ou de sandbox pode não estar disponível por meio de uma pesquisa de produção anônima.

Compartilhe um registro acessível usando `https://verify.truthlocks.com/proof/{attestation_id}`. Uma URL compartilhada não concede acesso a cargas úteis privadas.


## OpenAPI

````yaml pt/mint-openapi.yaml POST /v1/verify
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >-
    Truthlocks é uma infraestrutura de verificação universal para documentos,
    credenciais e ativos digitais.

    Esta especificação define a API canônica para interagir com os serviços
    Truthlocks.


    ## URLs Base

    - **Produção**: `https://api.truthlocks.com`

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


    ## Autenticação

    - **Chaves de API**: Use o cabeçalho `X-API-Key` para operações máquina a
    máquina

    - **Tokens de Portador**: Use `Authorization: Bearer <jwt>` para operações
    iniciadas pelo usuário


    ## Identidade do Inquilino

    Em produção, a identidade do inquilino é derivada do contexto autenticado
    (chave de API ou JWT).

    O cabeçalho `X-Tenant-ID` é ignorado em produção para evitar falsificação.
  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 Produção
  - url: https://sandbox-api.truthlocks.com
    description: Ambiente Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gerenciamento de chaves e tokens de API
  - name: Issuers
    description: Registro do emissor e gerenciamento de confiança
  - name: Keys
    description: Gerenciamento de chaves criptográficas para emissores
  - name: Attestations
    description: Ciclo de vida da atestação (cunhar, revogar, substituir)
  - name: Verification
    description: Verificação de atestado e pacotes de prova
  - name: Governance
    description: Fluxos de trabalho de governança do emissor (somente administrador)
  - name: Identity
    description: Gerenciamento de organização, usuário e função
  - name: Audit
    description: Consultas de eventos de auditoria
  - name: Tenant Console
    description: Endpoints de perfil e ciclo de vida do locatário
  - name: Health
    description: Endpoints de saúde e prontidão do serviço
  - name: Risk
    description: Ingestão de sinal de risco e detecção de fraude
  - name: Risk Enforcement
    description: Ações de aplicação de risco — bloqueio, desafio, quarentena e configuração
  - name: Billing
    description: Gerenciamento de faturamento, assinatura e complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidade de Agente de Máquina (MAIP) — registro de agente,
      sessões, confiança, testemunha, conformidade, orquestração e
      observabilidade
externalDocs:
  description: API somente leitura de transparência (especificação de serviço separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/verify:
    post:
      tags:
        - Verification
      summary: Verificar Atestado
      description: >-
        Verifique o status do registro, metadados do emissor e evidências
        disponíveis. Forneça o payload_b64url original exato para verificar a
        assinatura criptográfica. Uma pesquisa apenas por ID ou apenas por
        impressão digital de arquivo retorna INCOMPLETO com signature_verified
        false se nenhuma falha mais forte se aplicar. VÁLIDO significa que o
        payload fornecido passou nas verificações de assinatura; isso não prova
        a veracidade das reivindicações nem garante que as verificações
        opcionais de política e transparência foram concluídas. Inspecione os
        motivos e log.proof_checked. Solicitações públicas não precisam de chave
        de API; solicitações autenticadas são escopadas e medidas em relação ao
        espaço de trabalho do chamador.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                attestation:
                  description: >-
                    Envelope de pesquisa online. Um attestation_id registado é
                    necessário aqui ou ao nível do pedido. O estado armazenado,
                    o emissor, a chave e a hora de emissão são autoritativos; as
                    cópias fornecidas não podem substituí-los.
                  nullable: true
                  properties:
                    attestation_id:
                      type: string
                    document_hash:
                      type: string
                    expires_at_unix:
                      type: integer
                      format: int64
                      nullable: true
                      description: >-
                        Expiração assinada registrada em segundos Unix; nulo
                        significa que nenhuma expiração é registrada. Registros
                        legados não recebem uma nova expiração.
                    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 folha de transparência baseado em zero.
                            Nulo significa que a referência do log não pôde ser
                            recuperada; zero é uma primeira entrada válida.
                        status:
                          type: string
                          enum:
                            - recorded
                            - unavailable
                          description: >-
                            Disponibilidade da referência de log armazenada;
                            isso não estabelece um veredito de inclusão
                            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 da verificação
          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: >-
        Evidência de verificação pública. Inspecione os motivos e as
        verificações individuais; uma verificação apenas de ID não verifica o
        conteúdo original fornecido pelo chamador.
      properties:
        verdict:
          $ref: '#/components/schemas/Verdict'
        signature_verified:
          type: boolean
          description: >-
            Verdadeiro apenas quando o payload original fornecido passou na
            verificação criptográfica de assinatura. Verificações somente de ID
            e somente de impressão digital retornam 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: >-
            Expiração assinada registrada em segundos Unix; nulo significa que
            nenhuma expiração é registrada. Registros legados não recebem uma
            nova expiração.
        issued_at_unix:
          type: integer
          format: int64
          description: >-
            Tempo de emissão original armazenado em segundos Unix. Este não é o
            tempo da verificação atual ou do download do certificado. Ausente se
            indisponível.
        kid:
          type: string
          description: Identificador da chave de assinatura.
        alg:
          type: string
          description: Algoritmo de assinatura declarado.
        payload_hash:
          type: string
          description: Resumo SHA-256 codificado em Base64url da carga útil canônica.
        document_hash:
          type: string
          description: >-
            Impressão digital hexadecimal SHA-256 do arquivo original, quando
            armazenado.
        log:
          type: object
          properties:
            log_id:
              type: string
            leaf_index:
              type: integer
              format: int64
              nullable: true
              description: >-
                Índice da folha de transparência verificada; nulo quando a
                verificação da prova não estava disponível. Zero é uma primeira
                folha válida.
            leaf_hash:
              type: string
              description: Resumo da folha de inclusão verificada, quando disponível.
            proof_checked:
              type: boolean
              description: >-
                Se a inclusão de transparência foi verificada com sucesso para
                esta resposta.
        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: >-
        Inspecione as razões, as entradas de verificação fornecidas e
        log.proof_checked junto com este veredito. VALID por si só não
        estabelece propriedade nem prova todas as alegações no registro.
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Chave de API para autenticação máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operações iniciadas pelo usuário

````

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