¿Qué son los recibos?
Los recibos son registros firmados e inmutables de eventos discretos: pagos, incidentes de seguridad, controles de cumplimiento, entregas y más. A diferencia de los registros o las pistas de auditoría, cada recibo es:- Firmado criptográficamente con su clave de emisor (Ed25519 o ES256)
- Anclado en el registro de transparencia con una prueba de inclusión de Merkle
- Verificable sin conexión mediante exportación de paquete de prueba
- Idempotente — el mismo evento siempre produce el mismo recibo
Tipos de recibos
Los tipos de recibo definidos por la plataforma están disponibles para todos los inquilinos. Cada tipo tiene un esquema JSON contra el cual se valida el campopayload antes de firmar.
Descubriendo tipos disponibles
Llame aGET /v1/receipt-types para listar cada tipo que su inquilino puede usar, o a GET /v1/receipt-types/{name} para obtener un solo tipo e inspeccionar su esquema JSON.
Acuñación de un recibo
El ejemplo utiliza ID y valores de carga útil ilustrativos. Reemplácelos con el emisor de su espacio de trabajo, la clave de firma disponible y una carga útil que coincida con el esquema de tipo de recibo seleccionado. No envíe el ejemplo como un registro de pago real.1
Elija un tipo de recibo
Llame a
GET /v1/receipt-types para listar los tipos disponibles e inspeccionar el esquema en busca de campos obligatorios.2
Construya su carga útil
Construya el objeto
payload que coincida con los campos requeridos para su tipo de recibo. Para payment_receipt, necesita amount, currency, provider, provider_reference y subject.3
Emitir mediante API
4
Almacenar el receipt_id
La respuesta incluye el
receipt_id y el log.leaf_index. Almacene ambos para futuras verificaciones.Ejemplos de SDK
Listar recibos
Recuperación de un recibo
Eventos de webhook
Suscríbase a los eventos de recibos configurando un punto final de webhook en la consola:Revocación de un recibo
La revocación es permanente y se registra en el registro de transparencia. Los recibos con estadorevoked siguen siendo consultables y su marca de tiempo de revocación se incluye en los paquetes de prueba. Puede incluir un reason opcional para registrar por qué se revocó el recibo.
Verificación de un recibo
Utilice el endpoint de verificación para comprobar la validez criptográfica y el estado actual de un recibo. La API comprueba la firma, el estado de la clave y el estado de revocación, y luego devuelve un veredicto.Veredictos
Paquetes de prueba
Un paquete de prueba es un paquete autocontenido para verificación offline. Incluye el sobre del recibo firmado, la prueba de inclusión de Merkle del registro de transparencia y la instantánea de la clave del emisor en el momento de la emisión. Después de descargar un paquete de prueba, puede verificar el recibo sin realizar más llamadas a la API.Búsqueda de recibos
Busque en sus recibos utilizando la búsqueda de texto completo y filtros facetados. El índice de búsqueda admite consultas contra el contenido de la carga útil, y puede restringir los resultados por tipo, estado, rango de fechas o campos de carga útil indexados.Filtros de búsqueda
Exportación de recibos
Poner en cola una exportación masiva asíncrona de recibos como JSON o CSV. La API regresa inmediatamente con un ID de trabajo. Sondee el punto final de estado de exportación hasta questatus sea complete, luego descargue desde la URL pre-firmada.
Valores de estado de exportación
Redacción de recibos
La redacción elimina permanentemente la PII de la carga útil de un recibo mientras conserva la prueba criptográfica. La firma del recibo, la entrada del registro de transparencia y la prueba de inclusión de Merkle permanecen intactas; solo elpayload_json se reemplaza por un marcador de redacción.
Utilice esto para solicitudes de derecho al olvido del RGPD en recibos que contengan datos personales.
statuscambia aredactedpayload_jsonse reemplaza por{"redacted": true, "redacted_by": "tenant_request"}- Un evento
RECEIPT_REDACTestá anclado en el registro de transparencia - Todos los demás campos (firma, prueba de registro, tipo de recibo) se conservan
Gestión de recibos en la consola
Puede gestionar todo el ciclo de vida de los recibos desde la consola sin escribir ningún código. Abra Recibos en la barra lateral de la consola para acceder a las siguientes funciones.Búsqueda de recibos
La página de lista de recibos incluye una barra de búsqueda y filtros. Escriba una palabra clave para buscar en las cargas útiles de los recibos, o use los controles de filtro para restringir los resultados por tipo de recibo, estado, emisor o rango de fechas. Los resultados se actualizan en tiempo real a medida que refina su consulta.Exportar recibos
Haga clic en Exportar desde la lista de recibos para poner en cola una exportación masiva como CSV o JSON. Aparece un banner de estado en la parte superior de la página que rastrea el trabajo a través de los estadospending, running y complete. Una vez que finaliza la exportación, haga clic en el banner para descargar el archivo. También puede monitorear los trabajos de exportación desde la API usando GET /v1/receipt-exports/{id} — vea export receipts.
Descarga de un paquete de prueba
Abra la página de detalles de cualquier recibo y haga clic en Descargar paquete de prueba para guardar un paquete de verificación autocontenido. El paquete incluye el sobre del recibo firmado, la prueba de inclusión de Merkle y la instantánea de la clave del emisor, todo lo necesario para la verificación fuera de línea.Redacción de un recibo
Desde la página de detalles de cualquier recibo activo, haga clic en Redactar para eliminar permanentemente la información de identificación personal de la carga útil. Un cuadro de diálogo de confirmación explica que la redacción es irreversible antes de continuar. La redacción solo está disponible para recibos con estadoactive. Después de la redacción, se conservan la prueba criptográfica y la entrada del registro de transparencia; solo se elimina el contenido de la carga útil. Consulte redacción de recibos para obtener detalles sobre los cambios.
Política de retención
Los recibos se limpian automáticamente según la política de retención establecida en el momento de la emisión. Un trabajador en segundo plano elimina los recibos caducados de forma regular. Establezcaretention_policy al acuñar:
Los recibos que se acercan a su fecha límite de retención pueden ser redactados en lugar de eliminados si necesita preservar la prueba criptográfica mientras elimina los datos de la carga útil.
Próximos pasos
Especificación del paquete de prueba
Estructura completa y pasos de verificación offline para paquetes de prueba.
Referencia de la API de recibos
Referencia completa de la API para acuñar, buscar, exportar y redactar recibos.
Webhooks
Suscríbase a los eventos de recibo y procéselos en tiempo real.
Políticas de emisión
Aplique flujos de trabajo de aprobación y restricciones en la acuñación de recibos.

