Saltar para o conteúdo principal

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.

Descobrindo tipos disponíveis

Chame GET /v1/receipt-types para listar todos os tipos que seu locatário pode usar, ou GET /v1/receipt-types/{name} para buscar um único tipo e inspecionar seu JSON Schema.

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

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

Listar recibos

Recuperando um recibo

Eventos de webhook

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

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.

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.

Vereditos

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.
Consulte a referência da API do pacote de prova para a estrutura completa do pacote.
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.

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.

Filtros de pesquisa

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.

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.

Valores de estado de exportação

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.

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

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.

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 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: 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

Especificação do pacote de prova

Estrutura completa e etapas de verificação offline para pacotes de prova.

Referência da API de recibos

Referência completa da API para cunhagem, pesquisa, exportação e redação de recibos.

Webhooks

Assine eventos de recebimento e processe-os em tempo real.

Políticas de emissão

Aplique fluxos de trabalho de aprovação e restrições na emissão de recibos.