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

# Recibos

> Recibos criptograficamente assinados e ancorados em log de transparência para qualquer evento

## O que são Recibos?

Recibos são registros assinados e imutáveis de eventos discretos — pagamentos, incidentes de segurança, verificações de conformidade, entregas e muito mais. Ao contrário de logs ou trilhas de auditoria, cada recibo é:

* **Assinado criptograficamente** com sua chave de emissor (Ed25519 ou ES256)
* **Ancorado no log de transparência** com uma prova de inclusão Merkle
* **Verificável offline** via exportação de pacote de prova
* **Idempotente** — o mesmo evento sempre produz o mesmo recibo

## Tipos de recibo

Os tipos de recibo definidos pela plataforma estão disponíveis para todos os locatários. Cada tipo tem um JSON Schema contra o qual o campo `payload` é validado antes da assinatura.

| Tipo | Caso de Uso |
| - | - |
| `payment_receipt` | Pagamentos, faturas, reembolsos |
| `security_event_receipt` | Eventos de autenticação, rotações de chaves, anomalias |
| `delivery_receipt` | Entrega de documentos, notificações |
| `compliance_receipt` | Verificações KYC/AML, evidências regulatórias |
| `custom_receipt` | Qualquer outro evento com esquema aberto |

### Descobrindo tipos disponíveis

Chame [`GET /v1/receipt-types`](https://docs.truthlocks.com/pt/api-reference/receipts/list-types) para listar todos os tipos que seu locatário pode usar, ou [`GET /v1/receipt-types/{name}`](https://docs.truthlocks.com/pt/api-reference/receipts/get-type) para buscar um único tipo e inspecionar seu JSON Schema.

```typescript JavaScript theme={null}
const types = await client.receipts.listTypes();

// Inspect a specific type's schema
const paymentType = await client.receipts.getType("payment_receipt");
console.log(paymentType.schema.required); // ["amount", "currency", "provider", ...]
```

```go Go theme={null}
types, _ := client.Receipts.ListTypes(ctx)
for _, t := range types.Items {
    fmt.Println(t.Name, t.Version)
}

// Pin a specific version
rt, _ := client.Receipts.GetType(ctx, "payment_receipt@1.0.0")
```

## Cunhando um recibo

O exemplo usa IDs e valores de payload ilustrativos. Substitua-os pelo emissor do seu espaço de trabalho, chave de assinatura disponível e um payload que corresponda ao esquema do tipo de recibo selecionado. Não envie o exemplo como um registro de pagamento real.

**1. Escolha um tipo de recibo**

Chame `GET /v1/receipt-types` para listar os tipos disponíveis e inspecionar o esquema para campos obrigatórios.

**2. Construa seu payload**

Construa o objeto `payload` correspondente aos campos obrigatórios para o seu tipo de recibo. Para `payment_receipt`, você precisa de `amount`, `currency`, `provider`, `provider_reference` e `subject`.

**3. Emitir via API**

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-2026",
    "alg": "Ed25519",
    "receipt_type": "payment_receipt",
    "subject": "customer@example.com",
    "payload": {
      "amount": 5000,
      "currency": "USD",
      "provider": "stripe",
      "provider_reference": "ch_3Px..."
    }
  }'
```

**4. Armazenar o receipt\_id**

A resposta inclui o `receipt_id` e o `log.leaf_index`. Armazene ambos para verificação futura.

## Exemplos de SDK

```typescript JavaScript theme={null}
const receipt = await client.receipts.mint({
  issuer_id: 'your-issuer-id',
  kid: 'ed-key-2026',
  alg: 'Ed25519',
  receipt_type: 'payment_receipt',
  subject: 'customer@example.com',
  payload: {
    amount: 5000,
    currency: 'USD',
    provider: 'stripe',
    provider_reference: 'ch_3Px...'
  }
});

console.log(receipt.receipt_id, receipt.log.leaf_index);
```

```go Go theme={null}
receipt, err := client.Receipts.Mint(ctx, &truthlock.MintReceiptRequest{
    IssuerID:    "your-issuer-id",
    KID:         "ed-key-2026",
    Alg:         "Ed25519",
    ReceiptType: "payment_receipt",
    Subject:     "customer@example.com",
    Payload: map[string]interface{}{
        "amount":             5000,
        "currency":           "USD",
        "provider":           "stripe",
        "provider_reference": "ch_3Px...",
    },
})
```

### Listar recibos

```typescript JavaScript theme={null}
const receipts = await client.receipts.list({
  receipt_type: "payment_receipt",
  status: "active",
  limit: 20,
});
```

```go Go theme={null}
receipts, err := client.Receipts.List(ctx, &truthlock.ListReceiptsFilter{
    ReceiptType: "payment_receipt",
    Status:      "active",
    Limit:       20,
})
```

### Recuperando um recibo

```typescript JavaScript theme={null}
const receipt = await client.receipts.get("receipt-uuid");
```

```go Go theme={null}
receipt, err := client.Receipts.Get(ctx, "receipt-uuid")
```

## Eventos de webhook

Assine os eventos de recibo configurando um endpoint de webhook no console:

| Evento | Acionado Quando |
| - | - |
| `receipt.created` | Um recibo é cunhado com sucesso |
| `receipt.revoked` | Um recibo é revogado |

## Revogando um recibo

A revogação é permanente e registrada no log de transparência. Recibos com status `revoked` permanecem consultáveis e seu carimbo de data/hora de revogação é incluído nos pacotes de prova. Você pode incluir um `reason` opcional para registrar o motivo pelo qual o recibo foi revogado.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/{id}/revoke \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Duplicate charge refunded"}'
```

```typescript JavaScript theme={null}
await client.receipts.revoke("receipt-uuid", {
  reason: "Duplicate charge refunded",
});
```

```go Go theme={null}
_, err := client.Receipts.Revoke(ctx, "receipt-uuid", &truthlock.RevokeReceiptRequest{
    Reason: "Duplicate charge refunded",
})
```

## Verificando um recibo

Use o endpoint de verificação para verificar a validade criptográfica e o status atual de um recibo. A API verifica a assinatura, o status da chave e o estado de revogação, e então retorna um veredito.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/verify \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "receipt-uuid" }'
```

```typescript JavaScript theme={null}
const result = await client.receipts.verify("receipt-uuid");

if (result.verdict === "VALID") {
  console.log("Receipt is valid");
}
```

```go Go theme={null}
result, err := client.Receipts.Verify(ctx, "receipt-uuid")
if result.Verdict == "VALID" {
    fmt.Println("Receipt is valid")
}
```

```python Python theme={null}
result = client.receipts.verify("receipt-uuid")

if result["verdict"] == "VALID":
    print("Receipt is valid")
```

### Vereditos

| Veredito | Significado |
| - | - |
| `VALID` | A assinatura é válida, a chave está ativa, o recibo não foi revogado |
| `REVOKED` | Recibo foi explicitamente revogado |
| `INVALID_SIGNATURE` | Falha na verificação da assinatura criptográfica |
| `KEY_COMPROMISED` | A chave de assinatura foi marcada como comprometida na emissão ou antes |
| `KEY_INACTIVE` | A chave de assinatura não está mais ativa |
| `NOT_FOUND` | Recibo não encontrado para este inquilino |

## Pacotes de prova

Um pacote de prova é um pacote autocontido para verificação offline. Inclui o envelope de recibo assinado, prova de inclusão Merkle do log de transparência e o snapshot da chave do emissor no momento da emissão.

Após baixar um pacote de prova, você pode verificar o recibo sem fazer mais chamadas de API.

```typescript JavaScript theme={null}
const bundle = await client.receipts.getProofBundle("receipt-uuid");

console.log(bundle.bundle_version);          // "receipt-v1"
console.log(bundle.transparency_log);        // Merkle inclusion proof
```

```go Go theme={null}
bundle, err := client.Receipts.GetProofBundle(ctx, "receipt-uuid")
```

```python Python theme={null}
bundle = client.receipts.get_proof_bundle("receipt-uuid")
```

Consulte a [referência da API do pacote de prova](https://docs.truthlocks.com/pt/api-reference/receipts/proof-bundle.md) para a estrutura completa do pacote.

> [!TIP]
>
> Você pode baixar pacotes de prova diretamente do console. Abra a página de detalhes de um recibo e clique em **Baixar Pacote de Prova**. Consulte [baixando no console](#downloading-a-proof-bundle).

## Pesquisando recibos

Pesquise seus recibos usando pesquisa de texto completo e filtros facetados. O índice de pesquisa suporta consultas contra o conteúdo do payload, e você pode restringir os resultados por tipo, status, intervalo de datas ou campos de payload indexados.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/search \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "q": "stripe",
    "receipt_type": "payment_receipt",
    "from_date": "2026-01-01T00:00:00Z",
    "limit": 20
  }'
```

```typescript JavaScript theme={null}
const results = await client.receipts.search({
  q: "stripe",
  receipt_type: "payment_receipt",
  from_date: "2026-01-01T00:00:00Z",
  limit: 20,
});

for (const r of results.items) {
  console.log(r.receipt_id, r.receipt_type);
}
```

```go Go theme={null}
results, err := client.Receipts.Search(ctx, &truthlock.SearchReceiptsQuery{
    Q:           "stripe",
    ReceiptType: "payment_receipt",
    FromDate:    "2026-01-01T00:00:00Z",
    Limit:       20,
})
```

```python Python theme={null}
results = client.receipts.search(
    q="stripe",
    receipt_type="payment_receipt",
    from_date="2026-01-01T00:00:00Z",
    limit=20,
)
```

### Filtros de pesquisa

| Campo | Tipo | Descrição |
| - | - | - |
| `q` | string | Pesquisa de texto completo no conteúdo da carga |
| `receipt_type` | string | Filtrar por nome de tipo |
| `status` | string | `active`, `revoked`, `superseded`, ou `redacted` |
| `issuer_id` | UUID | Filtrar por emissor |
| `from_date` | RFC 3339 | Início do período |
| `to_date` | RFC 3339 | Fim do período |
| `index_key` | string | Nome do campo de carga indexado |
| `index_value` | string | Valor a ser correspondido para `index_key` |
| `limit` | integer | Máximo de resultados (1–100, padrão 20) |
| `offset` | integer | Deslocamento de paginação |

> [!TIP]
>
> Você também pode pesquisar recibos no console sem escrever código. Abra **Recibos** na barra lateral e use a barra de pesquisa e os controles de filtro. Consulte [pesquisando no console](#searching-receipts-1).

## Exportando recibos

Enfileire uma exportação em massa assíncrona de recibos como JSON ou CSV. A API retorna imediatamente com um ID de trabalho. Consulte o endpoint de status de exportação até que `status` seja `complete`, então baixe do URL pré-assinado.

```typescript JavaScript theme={null}
// Start an export
const job = await client.receipts.export({
  format: "json",
  filters: {
    receipt_type: "payment_receipt",
    status: "active",
  },
});

console.log(job.id, job.status); // "pending"

// Poll for completion
const completed = await client.receipts.getExport(job.id);
if (completed.status === "complete") {
  console.log("Download:", completed.download_url);
}

// List all export jobs
const exports = await client.receipts.listExports();
```

```go Go theme={null}
job, err := client.Receipts.Export(ctx, &truthlock.CreateExportRequest{
    Format: "json",
    Filters: map[string]interface{}{
        "receipt_type": "payment_receipt",
        "status":       "active",
    },
})

// Poll for completion
completed, err := client.Receipts.GetExport(ctx, job.ID)
```

```python Python theme={null}
job = client.receipts.export(
    format="json",
    filters={"receipt_type": "payment_receipt", "status": "active"},
)

# Poll for completion
completed = client.receipts.get_export(job["id"])
if completed["status"] == "complete":
    print("Download:", completed["download_url"])
```

### Valores de estado de exportação

| Status | Significado |
| - | - |
| `pending` | Na fila, ainda não iniciado |
| `running` | Registros de processamento |
| `complete` | Concluído — `download_url` está disponível |
| `failed` | Erro — ver `error_message` |

> [!TIP]
>
> Você pode enfileirar exportações e acompanhar seu progresso no console. Abra **Recibos**, clique em **Exportar** e escolha CSV ou JSON. Um banner de status acompanha o trabalho até que o download esteja pronto. Consulte [exportando no console](#exporting-receipts-1).

## Redação de recibos

A redação remove permanentemente informações de identificação pessoal (PII) do payload de um recibo, preservando a prova criptográfica. A assinatura do recibo, a entrada do log de transparência e a prova de inclusão Merkle permanecem intactas — apenas o `payload_json` é substituído por um marcador de redação.

Use isso para solicitações de direito ao esquecimento do GDPR em recibos que contêm dados pessoais.

```typescript JavaScript theme={null}
await client.receipts.redact("receipt-uuid");
```

```go Go theme={null}
_, err := client.Receipts.Redact(ctx, "receipt-uuid")
```

```python Python theme={null}
client.receipts.redact("receipt-uuid")
```

> [!WARNING]
>
> A redação é permanente. O payload original não pode ser restaurado. A prova criptográfica permanece válida para fins de auditoria.

Após a redação:

* `status` muda para `redacted`
* `payload_json` é substituído por `{"redacted": true, "redacted_by": "tenant_request"}`
* Um evento `RECEIPT_REDACT` é ancorado no log de transparência
* Todos os outros campos (assinatura, prova de log, tipo de recibo) são preservados

## Gerenciando recibos no console

Você pode gerenciar todo o ciclo de vida dos recibos no console sem escrever nenhum código. Abra **Recibos** na barra lateral do console para acessar os seguintes recursos.

### Pesquisando recibos

A página da lista de recibos inclui uma barra de pesquisa e filtros. Digite uma palavra-chave para pesquisar em cargas de recibos ou use os controles de filtro para restringir os resultados por tipo de recibo, status, emissor ou intervalo de datas. Os resultados são atualizados em tempo real à medida que você refina sua consulta.

### Exportar recibos

Clique em **Exportar** na lista de recibos para enfileirar uma exportação em massa como CSV ou JSON. Um banner de status aparece na parte superior da página, rastreando o trabalho pelos estados `pending`, `running` e `complete`. Assim que a exportação for concluída, clique no banner para baixar o arquivo. Você também pode monitorar trabalhos de exportação da API usando `GET /v1/receipt-exports/{id}` — consulte [export receipts](https://docs.truthlocks.com/pt/api-reference/receipts/export.md).

### Baixando um pacote de prova

Abra a página de detalhes de qualquer recibo e clique em **Descarregar Pacote de Prova** para guardar um pacote de verificação autónomo. O pacote inclui o envelope do recibo assinado, a prova de inclusão Merkle e o instantâneo da chave do emissor — tudo o que é necessário para [verificação offline](#proof-bundles).

### Redigindo um recibo

Em qualquer página de detalhes de um recibo ativo, clique em **Redigir** para remover permanentemente informações de identificação pessoal do payload. Uma caixa de diálogo de confirmação explica que a redação é irreversível antes de você prosseguir. A redação está disponível apenas para recibos com status `active`. Após a redação, a prova criptográfica e a entrada do log de transparência são preservadas — apenas o conteúdo do payload é removido. Consulte [redação de recibos](#redacting-receipts) para obter detalhes sobre o que muda.

## Política de retenção

Os recibos são automaticamente limpos com base na política de retenção definida no momento da emissão. Um processo em segundo plano remove recibos expirados regularmente.

Defina `retention_policy` ao cunhar:

| Política | Duração | Descrição |
| - | - | - |
| `standard` | 2 anos | Padrão. Adequado para a maioria dos recibos transacionais. |
| `extended` | 7 anos | Para casos de uso de conformidade que exigem retenção mais longa. |
| `permanent` | Nunca | Nunca excluído automaticamente. |

Os recibos que se aproximam do prazo de retenção podem ser redigidos em vez de excluídos, se você precisar preservar a prova criptográfica enquanto remove os dados da carga útil.

## Próximos passos

> [card] [Especificação do pacote de prova](https://docs.truthlocks.com/specification/proof-bundle.md)
>
> Estrutura completa e etapas de verificação offline para pacotes de prova.

> [card] [Referência da API de recibos](https://docs.truthlocks.com/api-reference/receipts/mint.md)
>
> Referência completa da API para cunhagem, pesquisa, exportação e redação de recibos.

> [card] [Webhooks](https://docs.truthlocks.com/guides/webhooks.md)
>
> Assine eventos de recebimento e processe-os em tempo real.

> [card] [Políticas de emissão](https://docs.truthlocks.com/guides/issuance-policies.md)
>
> Aplique fluxos de trabalho de aprovação e restrições na emissão de recibos.


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