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

# Registro de Hash de Documento (Experimental)

> Entradas atuais do pipeline de documentos e limitações de implementação.

> [!WARNING]
>
> A implementação atual simula extração e verificação por IA. Seu veredito e confiança gerados não são evidência de autenticidade do documento. Não use este endpoint para aprovar identidades, estabelecer conformidade ou autenticar documentos.

O manipulador aceita `agent_id` e `document_hash`, com `document_type`, `file_name` e `metadata` opcionais. O agente deve existir e estar ativo. Ele **não** aceita bytes de documento em `document_b64`, realiza OCR ou compara um arquivo carregado com o hash fornecido.

O manipulador cria seu registro de forma síncrona. Use o identificador de documento retornado com [Obter Documento](https://docs.truthlocks.com/pt/api-reference/machine-identity/documents/get.md). Hashes de extração gerados descrevem conteúdo simulado, não bytes de arquivo extraídos. As assinaturas de recibo do pipeline atualmente contêm marcadores de sistema em vez de assinaturas criptográficas.

Para verificação criptográfica de registos, use [Verificar Atestado](https://docs.truthlocks.com/pt/api-reference/verify.md) com um atestado assinado real e o payload original ou hash do documento. Isso verifica a integridade e o estado do registo, não se as afirmações factuais do documento são verdadeiras.


## OpenAPI

````yaml pt/mint-openapi.yaml POST /v1/truth/document/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/truth/document/verify:
    post:
      tags:
        - Machine Identity
      summary: Verificar Verdade do Documento
      description: >-
        Registro experimental de hash de documento. A extração e os resultados
        da IA são simulados na implementação atual. Este endpoint não aceita
        bytes de documento e não deve ser usado como evidência de autenticidade
        do documento.
      operationId: maip.truth.document.verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_id:
                  type: string
                  description: Agente solicitante
                  format: uuid
                document_hash:
                  type: string
                  description: Hash SHA-256 do documento
                document_type:
                  type: string
                file_name:
                  type: string
                metadata: {}
              type: object
              required:
                - agent_id
                - document_hash
      responses:
        '200':
          description: Resultado da verificação do documento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipDocumentVerification'
        '400':
          description: Erro de validação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticação necessária
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Limite de taxa excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipDocumentVerification:
      type: object
      properties:
        verification_id:
          type: string
          format: uuid
        document_id:
          type: string
          format: uuid
        document_hash:
          type: string
        status:
          type: string
          enum:
            - pending
            - verified
            - failed
        results:
          type: array
          items:
            type: object
            additionalProperties: true
        verifications:
          type: array
          items:
            type: object
            additionalProperties: true
        claims:
          type: array
          items:
            $ref: '#/components/schemas/MaipTruthClaim'
        created_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Código de erro legível por máquina
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensagem de erro legível por humanos
        http_status:
          type: integer
          description: Código de status HTTP
        retry_after_ms:
          type: integer
          description: >-
            Milissegundos para aguardar antes de tentar novamente (para limites
            de taxa)
        details:
          type: object
          description: Contexto de erro adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
    MaipTruthClaim:
      type: object
      properties:
        claim_id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        claim_type:
          type: string
        payload:
          type: object
          additionalProperties: true
        evidence:
          type: array
          items:
            type: object
            additionalProperties: true
        status:
          type: string
          enum:
            - pending
            - verified
            - rejected
            - expired
        receipt_id:
          type: string
          format: uuid
        attestations:
          type: array
          items:
            $ref: '#/components/schemas/MaipAttestation'
        verified_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    MaipAttestation:
      type: object
      properties:
        attestation_id:
          type: string
          format: uuid
        witness_id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        claim_hash:
          type: string
        signature:
          type: string
        status:
          type: string
          enum:
            - pending
            - accepted
            - rejected
        created_at:
          type: string
          format: date-time
  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.