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

# Emitir uma atestação

> Emita um atestado assinado usando esquema e reivindicações estruturadas, ou um payload codificado. Mantenha a mesma Idempotency-Key e corpo ao tentar novamente esta solicitação.

Assina uma carga útil usando a chave de assinatura disponível de um emissor e registra a atestação resultante. A política do emissor, o status da chave, o ambiente e os limites de uso podem impedir a cunhagem.

## Escolha um tipo de registro

Para um registo estruturado, escolha `schema` na lista suspensa de tipo de registo e insira um objeto JSON em `claims`. Deixe `payload_b64url` vazio. O servidor serializa esses campos no payload JSON assinado. Isso identifica o tipo de registo; não estabelece independentemente que as reivindicações são verdadeiras.

## Escolha um pacote de verificação

Os pacotes de verificação pertencem ao seu espaço de trabalho. Use o seletor abaixo com o mesmo ambiente e chave de API de Experimente, então copie o ID selecionado para `pack_id`. Omita esse campo para um registro autônomo. Você também pode usar [Listar pacotes de verificação](https://docs.truthlocks.com/pt/api-reference/verification-packs/list.md) ou [Emitir no Console](https://console.truthlocks.com/attestations/mint).

**Select a workspace verification pack**

This read-only lookup sends your key directly to the selected Truthlocks API. It keeps the key only in this componentâ€™s memory and does not mint a record.

API environment
Workspace API key

Clear key and results

Verification pack

## Usar um payload existente

Se você já tiver os bytes exatos para assinar, omita `schema` e `claims`. Codifique os bytes originais como **base64url sem preenchimento** em `payload_b64url`. Para JSON, serialize o objeto primeiro. Campos de aplicação como `subject`, `claims` e `schema` pertencem a esses bytes codificados; use-os através da entrada estruturada acima ou dentro dos bytes codificados, nunca ambos. Este endpoint não verifica independentemente a veracidade das reivindicações enviadas nem valida esquemas de credenciais arbitrários.

Use o `kid` da chave e o `alg` correspondente. O registro de chave pública por si só não torna uma chave de assinatura privada disponível. Consulte [chaves do emissor](https://docs.truthlocks.com/pt/api-reference/issuers/keys.md).

## Validade opcional

Para `schema` e `claims` estruturados, defina `expires_at_unix` para um timestamp Unix futuro em **segundos**. O Truthlocks inclui-o na raiz do payload JSON assinado. Com `payload_b64url`, coloque este campo dentro do payload JSON exato antes de codificá-lo e omita o campo de solicitação separado.

Após esse instante, a verificação retorna `EXPIRED`. A expiração não pode ser estendida ou removida de um registro assinado existente; crie um substituto. Omita-a quando não quiser uma expiração de atestado. Datas dentro de reivindicações individuais, como o `expiry_date` de um passaporte, são reivindicações separadas e não definem automaticamente a expiração do atestado. Registros existentes não recebem uma data retroativamente.

Mantenha a carga útil exata e a expiração ao tentar novamente. Uma nova tentativa idempotente retorna o registro original mesmo após sua expiração.

## Tentar novamente com segurança

`Idempotency-Key` é obrigatório. Gere um valor por cunhagem pretendida e mantenha-o com a solicitação original para novas tentativas. Não o reutilize para conteúdo diferente.

## Integridade do documento

O hash do documento armazenado é selecionado nesta ordem:

1. `claims.document.sha256` dentro de um payload JSON.
2. O `document_hash` da solicitação.
3. SHA-256 dos bytes do payload decodificado.

Um hash incorporado tem precedência sobre o campo separado. Inclua o hash no payload assinado quando precisar de vincular essa alegação à assinatura. Um hash submetido é uma alegação sobre um ficheiro; o servidor não pode estabelecer o conteúdo do ficheiro apenas a partir do hash.

Passe `document_hash_hex` para [verificação](https://docs.truthlocks.com/pt/api-reference/verify.md) para comparar um hash de arquivo. Mantenha o payload original para verificação de integridade do payload.

## Resposta e entrega

HTTP 201 retorna `attestation_id`, `issued_at_unix`, `signature` e `log`. A posição do log é `log.leaf_index`, não um `log_index` de nível superior.

`recipient_email` solicita notificação assíncrona. HTTP 201 confirma a cunhagem, não a entrega do e-mail. Omita-o ao distribuir o registro você mesmo.

Consulte o [início rápido](https://docs.truthlocks.com/pt/quickstart.md) para uma solicitação usando os campos de entrada e resposta reais.

## Guia de campo de tipo de registro

Esses campos são estruturas de reivindicação sugeridas, não uma garantia de validação de reivindicação ou verificação de identidade.

| ID do Esquema | Nome | Categoria | Campos de Reivindicação |
| - | - | - | - |
| `verifiable-id` | ID Verificável | Identidade | `full_name, employee_id, department, title, start_date` |
| `passport` | Passaporte | Identidade | `full_name, nationality, passport_number, date_of_birth, expiry_date, issuing_country` |
| `drivers-license` | Carteira de Motorista | Identidade | `full_name, license_number, state, class, expiry_date, date_of_birth` |
| `government-id` | ID Governamental | Identidade | `full_name, id_number, id_type, issuing_authority, country, expiry_date` |
| `self-sovereign-id` | ID Auto-Soberana | Identidade | `did, display_name, created_at` |
| `employment-verification` | Verificação de Emprego | Emprego | `employee_name, employer, position, department, employment_type, start_date, end_date` |
| `professional-role` | Função Profissional | Emprego | `full_name, title, organization, department, effective_date` |
| `membership-card` | Cartão de Membro | Emprego | `member_name, organization, membership_id, tier, valid_from, valid_to` |
| `professional-certification` | Certificação Profissional | Emprego | `holder_name, certification_name, issuing_body, certification_id, issued_date, expiry_date` |
| `license` | Licença | Emprego | `holder_name, license_type, license_number, issuing_authority, jurisdiction, issued_date, expiry_date` |
| `accreditation` | Acreditação | Emprego | `entity_name, accreditation_body, standard, scope, valid_from, valid_to` |
| `degree` | Grau | Educação | `student_name, institution, degree_type, field_of_study, graduation_date, honors` |
| `completion-cert` | Certificado de Conclusão | Educação | `participant_name, program_name, institution, completion_date, hours` |
| `course-credit` | Crédito de Curso | Educação | `student_name, course_name, institution, credits, grade, semester` |
| `transcript` | Histórico Escolar | Educação | `student_name, institution, program, gpa, total_credits, issue_date` |
| `micro-credential` | Micro-Credencial | Educação | `earner_name, credential_name, issuer, skills, earned_date` |
| `training-completion` | Conclusão de Treinamento | Educação | `trainee_name, training_program, provider, completion_date, score, certificate_id` |
| `medical-license` | Licença Médica | Saúde | `practitioner_name, license_number, specialty, state, issued_date, expiry_date` |
| `dea-registration` | Registro DEA | Saúde | `registrant_name, dea_number, schedules, business_activity, expiry_date` |
| `board-certification` | Certificação de Conselho | Saúde | `physician_name, board, specialty, certification_date, expiry_date` |
| `health-credential` | Credencial de Saúde | Saúde | `patient_name, credential_type, provider, date, details` |
| `vaccination-record` | Registro de Vacinação | Saúde | `patient_name, vaccine_name, manufacturer, lot_number, date_administered, dose_number, site` |
| `aml-kyc` | Verificação AML/KYC | Conformidade | `entity_name, check_type, result, risk_level, verified_by, verified_at` |
| `security-clearance` | Autorização de Segurança | Conformidade | `holder_name, clearance_level, granting_agency, granted_date, expiry_date` |
| `sam-gov` | Registro SAM.gov | Conformidade | `entity_name, cage_code, uei, registration_status, expiry_date` |
| `jurisdiction-approval` | Aprovação de Jurisdição | Conformidade | `entity_name, jurisdiction, approval_type, approved_date, conditions` |
| `attestation-of-will` | Atestado de Testamento | Conformidade | `declarant_name, declaration, witness, date` |
| `bank-verification` | Verificação Bancária | Financeiro | `account_holder, bank_name, account_type, routing_number_last4, verified_date` |
| `credit-attestation` | Atestado de Crédito | Financeiro | `entity_name, credit_score_range, reporting_agency, assessment_date` |
| `income-verification` | Verificação de Renda | Financeiro | `individual_name, employer, annual_income_range, verification_date, tax_year` |
| `skill-badge` | Selo de Habilidade | Habilidades e Treinamento | `earner_name, skill_name, proficiency_level, assessed_by, earned_date` |
| `competency` | Atestado de Competência | Habilidades e Treinamento | `individual_name, competency, level, assessor, assessment_date` |
| `industry-cert` | Certificação da Indústria | Habilidades e Treinamento | `holder_name, certification, issuing_body, cert_id, issued_date, expiry_date` |
| `product-authenticity` | Autenticidade do Produto | Cadeia de Suprimentos | `product_name, sku, serial_number, manufacturer, manufactured_date, origin_country` |
| `chain-of-custody` | Cadeia de Custódia | Cadeia de Suprimentos | `item_description, from_entity, to_entity, transfer_date, location, condition` |
| `origin-verification` | Verificação de Origem | Cadeia de Suprimentos | `product_name, origin_country, origin_region, certifying_body, verified_date` |
| `custom` | Personalizado | Outro | `subject, type, details` |
| `attestation` | Atestado Genérico | Outro | `subject, claim, evidence` |


## OpenAPI

````yaml pt/mint-openapi.yaml POST /v1/attestations/mint
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/attestations/mint:
    post:
      tags:
        - Attestations
      summary: Emitir Atestado
      description: >-
        Emita um atestado assinado usando esquema e reivindicações estruturadas,
        ou um payload codificado. Mantenha a mesma Idempotency-Key e corpo ao
        tentar novamente esta solicitação.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Mantenha o mesmo valor e corpo da solicitação ao tentar novamente
            uma cunhagem.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                Escolha Registro estruturado para selecionar um tipo de registro
                e inserir reivindicações, ou Payload codificado para assinar
                bytes existentes. Nunca combine ambos os formatos de entrada.
              oneOf:
                - title: Structured record
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - schema
                    - claims
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: >-
                        Deve corresponder à chave de assinatura do emissor
                        selecionada.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        Tipo MIME dos bytes originais, como application/json,
                        application/pdf ou image/png. A entrada de
                        esquema/declarações estruturadas requer
                        application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        Hash SHA-256 hexadecimal opcional do documento. Um
                        claims.document.sha256 incorporado tem precedência; caso
                        contrário, este campo é usado, depois o hash do payload
                        decodificado.
                    issuer_id:
                      type: string
                      description: O UUID do emissor que cria o atestado
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: Identificador da chave para a chave de assinatura
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        UUID opcional do pacote de verificação do espaço de
                        trabalho. Use Listar pacotes de verificação com a mesma
                        chave de API para selecionar um pacote ativo existente;
                        omita para um registro autônomo.
                      format: uuid
                    expires_at_unix:
                      type: integer
                      format: int64
                      minimum: 1
                      maximum: 253402300799
                      description: >-
                        Timestamp Unix futuro opcional em segundos para entrada
                        de esquema/declarações estruturadas. Ele é incluído no
                        payload JSON assinado. Para entrada payload_b64url,
                        omita este campo de solicitação e incorpore
                        expires_at_unix na raiz do payload JSON exato. A
                        expiração não pode ser alterada no local.
                    recipient_email:
                      type: string
                      description: >-
                        Destinatário opcional para notificação assíncrona após a
                        cunhagem. Uma resposta de cunhagem bem-sucedida não
                        confirma a entrega.
                      format: email
                    schema:
                      type: string
                      description: >-
                        Tipo de registro para entrada estruturada. Forneça
                        reivindicações e omita payload_b64url. Este rótulo não
                        valida independentemente a veracidade das
                        reivindicações.
                      enum:
                        - verifiable-id
                        - passport
                        - drivers-license
                        - government-id
                        - self-sovereign-id
                        - employment-verification
                        - professional-role
                        - membership-card
                        - professional-certification
                        - license
                        - accreditation
                        - degree
                        - completion-cert
                        - course-credit
                        - transcript
                        - micro-credential
                        - training-completion
                        - medical-license
                        - dea-registration
                        - board-certification
                        - health-credential
                        - vaccination-record
                        - aml-kyc
                        - security-clearance
                        - sam-gov
                        - jurisdiction-approval
                        - attestation-of-will
                        - bank-verification
                        - credit-attestation
                        - income-verification
                        - skill-badge
                        - competency
                        - industry-cert
                        - product-authenticity
                        - chain-of-custody
                        - origin-verification
                        - custom
                        - attestation
                      example: verifiable-id
                    claims:
                      type: object
                      additionalProperties: true
                      description: >-
                        Campos de registro estruturados. Obrigatório com
                        esquema; não pode ser combinado com payload_b64url.
                      example:
                        full_name: Example recipient
                        employee_id: QA-001
                - title: Encoded payload
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - payload_b64url
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: >-
                        Deve corresponder à chave de assinatura do emissor
                        selecionada.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        Tipo MIME dos bytes originais, como application/json,
                        application/pdf ou image/png. A entrada de
                        esquema/declarações estruturadas requer
                        application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        Hash SHA-256 hexadecimal opcional do documento. Um
                        claims.document.sha256 incorporado tem precedência; caso
                        contrário, este campo é usado, depois o hash do payload
                        decodificado.
                    issuer_id:
                      type: string
                      description: O UUID do emissor que cria o atestado
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: Identificador da chave para a chave de assinatura
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        UUID opcional do pacote de verificação do espaço de
                        trabalho. Use Listar pacotes de verificação com a mesma
                        chave de API para selecionar um pacote ativo existente;
                        omita para um registro autônomo.
                      format: uuid
                    recipient_email:
                      type: string
                      description: >-
                        Destinatário opcional para notificação assíncrona após a
                        cunhagem. Uma resposta de cunhagem bem-sucedida não
                        confirma a entrega.
                      format: email
                    payload_b64url:
                      type: string
                      description: >-
                        Base64url sem preenchimento dos bytes exatos a serem
                        assinados. Use este OU esquema mais reivindicações.
      responses:
        '201':
          description: Atestação cunhada
          content:
            application/json:
              schema:
                type: object
                properties:
                  attestation_id:
                    type: string
                    format: uuid
                  issuer_id:
                    type: string
                    format: uuid
                  version:
                    type: string
                  status:
                    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
                    format: int64
                  payload_hash:
                    type: string
                  signature:
                    type: object
                    properties:
                      alg:
                        type: string
                      kid:
                        type: string
                      value:
                        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
                  governance:
                    type: object
                    nullable: true
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: Payload muito grande
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: PAYLOAD_TOO_LARGE
                message: Request body exceeds maximum size of 1MB
                http_status: 413
        '429':
          description: Limite de taxa ou cota excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded
                http_status: 429
                retry_after_ms: 60000
      security:
        - APIKey: []
components:
  schemas:
    SigningAlgorithm:
      type: string
      enum:
        - Ed25519
        - ES256
        - ES384
        - ES512
        - RS256
        - RS384
        - RS512
        - PS256
        - PS384
        - PS512
      description: Algoritmo de assinatura para geração de chave
    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
  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.