> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recibos

> Recibos anclados en el registro de transparencia y firmados criptográficamente para cualquier evento

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

| Tipo | Caso de uso |
| - | - |
| `payment_receipt` | Pagos, facturas, reembolsos |
| `security_event_receipt` | Eventos de autenticación, rotaciones de claves, anomalías |
| `delivery_receipt` | Entrega de documentos, notificaciones |
| `compliance_receipt` | Comprobaciones KYC/AML, evidencia regulatoria |
| `custom_receipt` | Cualquier otro evento con esquema abierto |

### Descubriendo tipos disponibles

Llame a [`GET /v1/receipt-types`](https://docs.truthlocks.com/es/api-reference/receipts/list-types) para listar cada tipo que su inquilino puede usar, o a [`GET /v1/receipt-types/{name}`](https://docs.truthlocks.com/es/api-reference/receipts/get-type) para obtener un solo tipo e inspeccionar su esquema JSON.

```typescript JavaScript theme={null}
const types = await client.receipts.listTypes();

// Inspect a specific type's schema
const paymentType = await client.receipts.getType("payment_receipt");
console.log(paymentType.schema.required); // ["amount", "currency", "provider", ...]
```

```go Go theme={null}
types, _ := client.Receipts.ListTypes(ctx)
for _, t := range types.Items {
    fmt.Println(t.Name, t.Version)
}

// Pin a specific version
rt, _ := client.Receipts.GetType(ctx, "payment_receipt@1.0.0")
```

## 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**

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-2026",
    "alg": "Ed25519",
    "receipt_type": "payment_receipt",
    "subject": "customer@example.com",
    "payload": {
      "amount": 5000,
      "currency": "USD",
      "provider": "stripe",
      "provider_reference": "ch_3Px..."
    }
  }'
```

**4. Almacenar el receipt\_id**

La respuesta incluye el `receipt_id` y el `log.leaf_index`. Almacene ambos para futuras verificaciones.

## Ejemplos de SDK

```typescript JavaScript theme={null}
const receipt = await client.receipts.mint({
  issuer_id: 'your-issuer-id',
  kid: 'ed-key-2026',
  alg: 'Ed25519',
  receipt_type: 'payment_receipt',
  subject: 'customer@example.com',
  payload: {
    amount: 5000,
    currency: 'USD',
    provider: 'stripe',
    provider_reference: 'ch_3Px...'
  }
});

console.log(receipt.receipt_id, receipt.log.leaf_index);
```

```go Go theme={null}
receipt, err := client.Receipts.Mint(ctx, &truthlock.MintReceiptRequest{
    IssuerID:    "your-issuer-id",
    KID:         "ed-key-2026",
    Alg:         "Ed25519",
    ReceiptType: "payment_receipt",
    Subject:     "customer@example.com",
    Payload: map[string]interface{}{
        "amount":             5000,
        "currency":           "USD",
        "provider":           "stripe",
        "provider_reference": "ch_3Px...",
    },
})
```

### Listar recibos

```typescript JavaScript theme={null}
const receipts = await client.receipts.list({
  receipt_type: "payment_receipt",
  status: "active",
  limit: 20,
});
```

```go Go theme={null}
receipts, err := client.Receipts.List(ctx, &truthlock.ListReceiptsFilter{
    ReceiptType: "payment_receipt",
    Status:      "active",
    Limit:       20,
})
```

### Recuperación de un recibo

```typescript JavaScript theme={null}
const receipt = await client.receipts.get("receipt-uuid");
```

```go Go theme={null}
receipt, err := client.Receipts.Get(ctx, "receipt-uuid")
```

## Eventos de webhook

Suscríbase a los eventos de recibos configurando un punto final de webhook en la consola:

| Evento | Se activa cuando |
| - | - |
| `receipt.created` | Un recibo se acuña con éxito |
| `receipt.revoked` | Un recibo es revocado |

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

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/{id}/revoke \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Duplicate charge refunded"}'
```

```typescript JavaScript theme={null}
await client.receipts.revoke("receipt-uuid", {
  reason: "Duplicate charge refunded",
});
```

```go Go theme={null}
_, err := client.Receipts.Revoke(ctx, "receipt-uuid", &truthlock.RevokeReceiptRequest{
    Reason: "Duplicate charge refunded",
})
```

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

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/verify \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "receipt-uuid" }'
```

```typescript JavaScript theme={null}
const result = await client.receipts.verify("receipt-uuid");

if (result.verdict === "VALID") {
  console.log("Receipt is valid");
}
```

```go Go theme={null}
result, err := client.Receipts.Verify(ctx, "receipt-uuid")
if result.Verdict == "VALID" {
    fmt.Println("Receipt is valid")
}
```

```python Python theme={null}
result = client.receipts.verify("receipt-uuid")

if result["verdict"] == "VALID":
    print("Receipt is valid")
```

### Veredictos

| Veredicto | Significado |
| - | - |
| `VALID` | La firma es válida, la clave está activa, el recibo no está revocado |
| `REVOKED` | El recibo ha sido revocado explícitamente |
| `INVALID_SIGNATURE` | Falló la verificación de la firma criptográfica |
| `KEY_COMPROMISED` | La clave de firma fue marcada como comprometida en o antes de la emisión |
| `KEY_INACTIVE` | La clave de firma ya no está activa |
| `NOT_FOUND` | Recibo no encontrado para este inquilino |

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

```typescript JavaScript theme={null}
const bundle = await client.receipts.getProofBundle("receipt-uuid");

console.log(bundle.bundle_version);          // "receipt-v1"
console.log(bundle.transparency_log);        // Merkle inclusion proof
```

```go Go theme={null}
bundle, err := client.Receipts.GetProofBundle(ctx, "receipt-uuid")
```

```python Python theme={null}
bundle = client.receipts.get_proof_bundle("receipt-uuid")
```

Consulte la [referencia de API del paquete de prueba](https://docs.truthlocks.com/es/api-reference/receipts/proof-bundle.md) para conocer la estructura completa del paquete.

> [!TIP]
>
> 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](#downloading-a-proof-bundle).

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

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/search \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "q": "stripe",
    "receipt_type": "payment_receipt",
    "from_date": "2026-01-01T00:00:00Z",
    "limit": 20
  }'
```

```typescript JavaScript theme={null}
const results = await client.receipts.search({
  q: "stripe",
  receipt_type: "payment_receipt",
  from_date: "2026-01-01T00:00:00Z",
  limit: 20,
});

for (const r of results.items) {
  console.log(r.receipt_id, r.receipt_type);
}
```

```go Go theme={null}
results, err := client.Receipts.Search(ctx, &truthlock.SearchReceiptsQuery{
    Q:           "stripe",
    ReceiptType: "payment_receipt",
    FromDate:    "2026-01-01T00:00:00Z",
    Limit:       20,
})
```

```python Python theme={null}
results = client.receipts.search(
    q="stripe",
    receipt_type="payment_receipt",
    from_date="2026-01-01T00:00:00Z",
    limit=20,
)
```

### Filtros de búsqueda

| Campo | Tipo | Descripción |
| - | - | - |
| `q` | string | Búsqueda de texto completo en el contenido de la carga útil |
| `receipt_type` | string | Filtrar por nombre de tipo |
| `status` | string | `active`, `revoked`, `superseded`, o `redacted` |
| `issuer_id` | UUID | Filtrar por emisor |
| `from_date` | RFC 3339 | Inicio del rango de fechas |
| `to_date` | RFC 3339 | Fin del rango de fechas |
| `index_key` | string | Nombre del campo de carga útil indexado |
| `index_value` | string | Valor a coincidir para `index_key` |
| `limit` | integer | Máximo de resultados (1–100, predeterminado 20) |
| `offset` | integer | Desplazamiento de paginación |

> [!TIP]
>
> 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](#searching-receipts-1).

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

```typescript JavaScript theme={null}
// Start an export
const job = await client.receipts.export({
  format: "json",
  filters: {
    receipt_type: "payment_receipt",
    status: "active",
  },
});

console.log(job.id, job.status); // "pending"

// Poll for completion
const completed = await client.receipts.getExport(job.id);
if (completed.status === "complete") {
  console.log("Download:", completed.download_url);
}

// List all export jobs
const exports = await client.receipts.listExports();
```

```go Go theme={null}
job, err := client.Receipts.Export(ctx, &truthlock.CreateExportRequest{
    Format: "json",
    Filters: map[string]interface{}{
        "receipt_type": "payment_receipt",
        "status":       "active",
    },
})

// Poll for completion
completed, err := client.Receipts.GetExport(ctx, job.ID)
```

```python Python theme={null}
job = client.receipts.export(
    format="json",
    filters={"receipt_type": "payment_receipt", "status": "active"},
)

# Poll for completion
completed = client.receipts.get_export(job["id"])
if completed["status"] == "complete":
    print("Download:", completed["download_url"])
```

### Valores de estado de exportación

| Estado | Significado |
| - | - |
| `pending` | En cola, aún no iniciado |
| `running` | Registros de procesamiento |
| `complete` | Hecho — `download_url` está disponible |
| `failed` | Error — ver `error_message` |

> [!TIP]
>
> 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](#exporting-receipts-1).

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

```typescript JavaScript theme={null}
await client.receipts.redact("receipt-uuid");
```

```go Go theme={null}
_, err := client.Receipts.Redact(ctx, "receipt-uuid")
```

```python Python theme={null}
client.receipts.redact("receipt-uuid")
```

> [!WARNING]
>
> 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](https://docs.truthlocks.com/es/api-reference/receipts/export.md).

### 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](#proof-bundles).

### 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](#redacting-receipts) 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:

| Política | Duración | Descripción |
| - | - | - |
| `standard` | 2 años | Predeterminado. Adecuado para la mayoría de los recibos transaccionales. |
| `extended` | 7 años | Para casos de uso de cumplimiento que requieren una retención más prolongada. |
| `permanent` | Nunca | Nunca se elimina automáticamente. |

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

> [card] [Especificación del paquete de prueba](https://docs.truthlocks.com/specification/proof-bundle.md)
>
> Estructura completa y pasos de verificación offline para paquetes de prueba.

> [card] [Referencia de la API de recibos](https://docs.truthlocks.com/api-reference/receipts/mint.md)
>
> Referencia completa de la API para acuñar, buscar, exportar y redactar recibos.

> [card] [Webhooks](https://docs.truthlocks.com/guides/webhooks.md)
>
> Suscríbase a los eventos de recibo y procéselos en tiempo real.

> [card] [Políticas de emisión](https://docs.truthlocks.com/guides/issuance-policies.md)
>
> Aplique flujos de trabajo de aprobación y restricciones en la acuñación de recibos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.