> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Comprovantes e auditoria > Cada leitura deixa um comprovante encadeado por SHA-256: quem leu o quê, sob qual política. Toda vez que um agente lê a memória, a Niadra deixa um comprovante: qual fonte leu, sobre quem, para qual finalidade, em qual nível de verificação, sob qual versão da política, quais itens foram entregues e quantos ficaram retidos. O comprovante é gravado antes de a resposta sair, nunca é opcional, e os comprovantes são encadeados por SHA-256, para que ninguém altere o passado sem quebrar a corrente. É assim que você responde, meses depois, por que um agente disse o que disse. ## O que deixa comprovante | Tipo | Gerado por | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Leituras de contexto (`POST` e `GET /v1/context`) e de objetos | | `history` | Navegação do histórico: busca, linha do tempo e abrir item | | `analytics` | [Análise da base](/api/insights-aggregate), com pseudônimo por padrão; uma revelação registra o motivo | | `admin` | Ações de governança: uniões, separações, apagamentos, mudanças de política, padrões retirados, mudanças de regra, execuções de exportação, vereditos de revisão, diffs aprovados e ações no Console | | `holdout` | O grupo de controle: o contexto que teria sido entregue, registrado e não entregue | Ações de agentes, vínculos e mudanças administrativas caem na mesma trilha, então "quem fez o quê" e "quem leu o quê" ficam num lugar só. ## O que um comprovante guarda ```json theme={null} { "receipt_id": "0192f7a4-2b61-7c1e-8a3d-5f0e9c7b1d24", "kind": "read", "surface": "object", "read_at": "2026-09-22T17:07:03Z", "source_id": "src_voice", "profile_id": "prf_01J1", "conversation_id": "call-4471", "audience": "customer_agent", "purpose": "customer_service", "verification": "V1", "policy_version": "pol-14", "item_ids": ["fct_01", "act_01J8ZK", "oi_01J8ZK"], "withheld": 2, "manifest_hash": "sha256:5b1e0c", "day": "2026-09-22", "slice": 3, "seq": 88213, "prev_hash": "sha256:0d9f3a", "hash": "sha256:7e21c8" } ``` Os itens aparecem por id, e o conteúdo nunca é copiado para o comprovante. O `manifest_hash` aponta para o manifesto de origem daquela entrega, que registra: * cada item incluído, com o evento de onde veio; * cada exclusão, com o motivo: `policy`, `verification`, `budget` ou `quarantine`; * as versões do compilador, do modelo de texto, da política e do extrator; * tokens por seção e a decisão de cache de prompt. Os comprovantes da navegação também registram a consulta, os filtros e os itens devolvidos, por hash. ## A corrente Comprovantes só crescem. Cada um traz a própria posição (`seq`) e o hash do anterior (`prev_hash`), encadeados por espaço, por fatia e por dia. Um espaço pequeno tem uma fatia; um grande tem até 16, escolhidas pelo perfil, para que o espaço mais movimentado grave sem gargalo único. Uma vez por dia, as cabeças das fatias são combinadas numa raiz diária, que vai para armazenamento imutável com trava de objeto. Alterar qualquer comprovante passado quebra todos os hashes seguintes e deixa de bater com a raiz. Uma conferência rápida de continuidade sobre uma página de uma fatia: ```python Python theme={null} import os import httpx response = httpx.get( "https://acme-prod.us-east-1.api.niadra.com/v1/receipts", params={"conversation_id": "call-4471"}, headers={"Authorization": f"Bearer {os.environ['NIADRA_API_KEY']}"}, ) items = sorted(response.json()["items"], key=lambda r: r["seq"]) for previous, current in zip(items, items[1:]): if current["seq"] == previous["seq"] + 1: assert current["prev_hash"] == previous["hash"], current["receipt_id"] ``` ```typescript TypeScript theme={null} const url = new URL("https://acme-prod.us-east-1.api.niadra.com/v1/receipts"); url.searchParams.set("conversation_id", "call-4471"); const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.NIADRA_API_KEY}` }, }); const items = (await response.json()).items.sort((a: { seq: number }, b: { seq: number }) => a.seq - b.seq); for (let i = 1; i < items.length; i++) { if (items[i].seq === items[i - 1].seq + 1 && items[i].prev_hash !== items[i - 1].hash) { throw new Error(`chain broken at ${items[i].receipt_id}`); } } ``` ```bash cURL theme={null} curl "https://acme-prod.us-east-1.api.niadra.com/v1/receipts?conversation_id=call-4471" \ -H "Authorization: Bearer $NIADRA_API_KEY" ``` A conferência completa fica no servidor: [`GET /v1/receipts/verify?day=2026-09-22`](/api/receipts-verify) percorre todas as fatias daquele dia e responde `valid`, o número de `receipts`, as cabeças de cada fatia em `heads`, as quebras que achou em `breaks` e se a raiz recalculada bate com a ancorada (`root_matches`). As rotas de comprovante são rotas de governança: uma pessoa do Console com o papel `security`, ou uma chave de escopo `admin`. Filtre a lista por `profile_id`, `conversation_id`, `source_id`, `kind` e por uma janela `since`/`until`, e pagine com `cursor`. Veja [Listar comprovantes](/api/receipts). ## Três perguntas que os comprovantes respondem **Por que o agente disse X?** Às 14h07, o agente de voz disse à Marina que o crédito de 40 já tinha sido lançado. O comprovante de `call-4471` lista `act_01J8ZK`, a ação do agente de cobrança das 14h06, entre os itens entregues; o manifesto mostra que ela veio da ação `credit` sobre `invoice:erp:0823`, confirmada pelo evento do ERP. Comprovante, manifesto, item, evento: quatro passos da frase até a origem. [`GET /v1/lineage/receipt/{receipt_id}`](/api/lineage-receipt) percorre esses passos por você e devolve o comprovante, os itens entregues com a origem de cada um e as exclusões. **Quem viu o fato F?** [`GET /v1/lineage/fact/{fact_id}`](/api/lineage-fact) devolve cada comprovante cuja entrega levou aquele fato: cada fonte que o recebeu, com finalidade, nível e horário. **O que foi retido, e por quê?** `withheld` diz quantos itens a política segurou; o manifesto diz qual motivo valeu para cada um (`policy`, `verification`, `budget` ou `quarantine`). O agente fica sabendo só da contagem, nunca do conteúdo, e entende que verificar o cliente libera mais. ## Comprovantes no seu SIEM Os comprovantes saem em segundos pelo mesmo mecanismo de entrega dos webhooks, em JSON no esquema OCSF, ou como arquivos no seu bucket junto com a exportação contínua. Você escolhe o caminho. O envio ao SIEM é opcional no plano Produção e incluído no plano Regulado. ## Comprovantes e apagamento Quando um titular é esquecido, os comprovantes de leitura não são reescritos: eles já guardam só ids e hashes, então provam que a leitura aconteceu sem guardar o que foi lido. O próprio apagamento deixa um comprovante `admin`, o comprovante de apagamento, que lista o que foi apagado e as execuções de exportação que já continham o dado. As linhas de medição seguem a retenção e a política do comprovante a que pertencem. ## Próximos passos o comprovante de apagamento e a linhagem que ele percorre. cada sinal abre o comprovante da entrega. itens retidos e níveis de verificação. o endpoint em detalhe.