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 campopayload é validado antes da assinatura.
Descobrindo tipos disponíveis
ChameGET /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 statusrevoked 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.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
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é questatus seja complete, então baixe do URL pré-assinado.
Valores de estado de exportação
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 opayload_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.
statusmuda pararedactedpayload_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 estadospending, 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 statusactive. 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. Definaretention_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.

