Saltar al contenido principal

¿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 campo payload antes de firmar.

Descubriendo tipos disponibles

Llame a GET /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 estado revoked 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.
Consulte la referencia de API del paquete de prueba para conocer la estructura completa del paquete.
Puede descargar paquetes de prueba directamente desde la consola. Abra la página de detalles de un recibo y haga clic en Descargar paquete de prueba. Consulte descarga en la consola.

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

También puede buscar recibos desde la consola sin escribir código. Abra Recibos en la barra lateral y utilice la barra de búsqueda y los controles de filtro. Consulte búsqueda en la consola.

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 que status sea complete, luego descargue desde la URL pre-firmada.

Valores de estado de exportación

Puede poner en cola las exportaciones y seguir su progreso desde la consola. Abra Recibos, haga clic en Exportar y elija CSV o JSON. Un banner de estado rastrea el trabajo hasta que la descarga esté lista. Consulte exportación en la consola.

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 el payload_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.
La redacción es permanente. La carga útil original no se puede restaurar. La prueba criptográfica sigue siendo válida para fines de auditoría.
Después de la redacción:
  • status cambia a redacted
  • payload_json se reemplaza por {"redacted": true, "redacted_by": "tenant_request"}
  • Un evento RECEIPT_REDACT está 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 estados pending, 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 estado active. 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. Establezca retention_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.