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

# Reçus

> Reçus signés cryptographiquement et ancrés dans un journal de transparence pour tout événement

## Que sont les reçus ?

Les reçus sont des enregistrements signés et immuables d'événements discrets — paiements, incidents de sécurité, contrôles de conformité, livraisons, et plus encore. Contrairement aux journaux ou aux pistes d'audit, chaque reçu est :

* **Signé cryptographiquement** avec votre clé d'émetteur (Ed25519 ou ES256)
* **Ancré dans le journal de transparence** avec une preuve d'inclusion Merkle
* **Vérifiable hors ligne** via l'exportation du paquet de preuves
* **Idempotent** — le même événement produit toujours le même reçu

## Types de reçus

Les types de reçus définis par la plateforme sont disponibles pour tous les locataires. Chaque type a un schéma JSON par rapport auquel le champ `payload` est validé avant la signature.

| Type | Cas d'utilisation |
| - | - |
| `payment_receipt` | Paiements, factures, remboursements |
| `security_event_receipt` | Événements d'authentification, rotations de clés, anomalies |
| `delivery_receipt` | Livraison de documents, notifications |
| `compliance_receipt` | Vérifications KYC/AML, preuves réglementaires |
| `custom_receipt` | Tout autre événement avec un schéma ouvert |

### Découverte des types disponibles

Appelez [`GET /v1/receipt-types`](https://docs.truthlocks.com/fr/api-reference/receipts/list-types) pour lister tous les types que votre locataire peut utiliser, ou [`GET /v1/receipt-types/{name}`](https://docs.truthlocks.com/fr/api-reference/receipts/get-type) pour récupérer un seul type et inspecter son schéma 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")
```

## Création d'un reçu

L'exemple utilise des identifiants et des valeurs de charge utile illustratifs. Remplacez-les par l'émetteur de votre espace de travail, la clé de signature disponible et une charge utile correspondant au schéma de type de reçu sélectionné. Ne soumettez pas l'exemple comme un enregistrement de paiement réel.

**1. Choisissez un type de reçu**

Appelez `GET /v1/receipt-types` pour lister les types disponibles et inspecter le schéma pour les champs requis.

**2. Construisez votre charge utile**

Construisez l'objet `payload` correspondant aux champs requis pour votre type de reçu. Pour `payment_receipt`, vous avez besoin de `amount`, `currency`, `provider`, `provider_reference`, et `subject`.

**3. Émettre via l'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. Stocker le receipt\_id**

La réponse inclut le `receipt_id` et le `log.leaf_index`. Stockez les deux pour une vérification future.

## Exemples 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...",
    },
})
```

### Lister les reçus

```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,
})
```

### Récupération d'un reçu

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

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

## Événements de webhook

Abonnez-vous aux événements de réception en configurant un point de terminaison de webhook dans la console :

| Événement | Déclenché quand |
| - | - |
| `receipt.created` | Un reçu est émis avec succès |
| `receipt.revoked` | Un reçu est révoqué |

## Révocation d'un reçu

La révocation est permanente et enregistrée dans le journal de transparence. Les reçus avec le statut `revoked` restent interrogeables et leur horodatage de révocation est inclus dans les paquets de preuves. Vous pouvez inclure un `reason` facultatif pour enregistrer la raison de la révocation du reçu.

```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",
})
```

## Vérification d'un reçu

Utilisez le point de terminaison de vérification pour vérifier la validité cryptographique et le statut actuel d'un reçu. L'API vérifie la signature, le statut de la clé et l'état de révocation, puis renvoie un verdict.

```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")
```

### Verdicts

| Verdict | Signification |
| - | - |
| `VALID` | La signature est valide, la clé est active, le reçu n'est pas révoqué |
| `REVOKED` | Le reçu a été explicitement révoqué |
| `INVALID_SIGNATURE` | La vérification de la signature cryptographique a échoué |
| `KEY_COMPROMISED` | La clé de signature a été marquée comme compromise à ou avant l'émission |
| `KEY_INACTIVE` | La clé de signature n'est plus active |
| `NOT_FOUND` | Reçu introuvable pour ce locataire |

## Lots de preuves

Un bundle de preuves est un paquet autonome pour la vérification hors ligne. Il comprend l'enveloppe du reçu signé, la preuve d'inclusion Merkle du journal de transparence et l'instantané de la clé de l'émetteur au moment de l'émission.

Après avoir téléchargé un paquet de preuves, vous pouvez vérifier le reçu sans effectuer d'autres appels 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")
```

Consultez la [référence de l'API du bundle de preuves](https://docs.truthlocks.com/fr/api-reference/receipts/proof-bundle.md) pour la structure complète du bundle.

> [!TIP]
>
> Vous pouvez télécharger des lots de preuves directement depuis la console. Ouvrez la page de détails d'un reçu et cliquez sur **Télécharger le lot de preuves**. Voir [téléchargement dans la console](#downloading-a-proof-bundle).

## Recherche de reçus

Recherchez dans vos reçus en utilisant la recherche en texte intégral et les filtres à facettes. L'index de recherche prend en charge les requêtes sur le contenu de la charge utile, et vous pouvez affiner les résultats par type, statut, plage de dates ou champs de charge utile indexés.

```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,
)
```

### Filtres de recherche

| Champ | Type | Description |
| - | - | - |
| `q` | string | Recherche en texte intégral dans le contenu de la charge utile |
| `receipt_type` | string | Filtrer par nom de type |
| `status` | chaîne | `active`, `revoked`, `superseded`, ou `redacted` |
| `issuer_id` | UUID | Filtrer par émetteur |
| `from_date` | RFC 3339 | Début de la plage de dates |
| `to_date` | RFC 3339 | Fin de la plage de dates |
| `index_key` | chaîne | Nom du champ de charge utile indexé |
| `index_value` | chaîne | Valeur à faire correspondre pour `index_key` |
| `limit` | integer | Nombre maximal de résultats (1–100, par défaut 20) |
| `offset` | integer | Décalage de pagination |

> [!TIP]
>
> Vous pouvez également rechercher des reçus depuis la console sans écrire de code. Ouvrez **Reçus** dans la barre latérale et utilisez la barre de recherche et les contrôles de filtre. Voir [recherche dans la console](#searching-receipts-1).

## Exportation des reçus

Mettre en file d'attente une exportation en masse asynchrone des reçus au format JSON ou CSV. L'API renvoie immédiatement un ID de tâche. Interrogez le point de terminaison de l'état de l'exportation jusqu'à ce que `status` soit `complete`, puis téléchargez à partir de l'URL pré-signée.

```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"])
```

### Valeurs du statut d'exportation

| Statut | Signification |
| - | - |
| `pending` | En file d'attente, pas encore démarré |
| `running` | Enregistrements de traitement |
| `complete` | Terminé — `download_url` est disponible |
| `failed` | Erreur — voir `error_message` |

> [!TIP]
>
> Vous pouvez mettre en file d'attente les exportations et suivre leur progression depuis la console. Ouvrez **Reçus**, cliquez sur **Exporter** et choisissez CSV ou JSON. Une bannière d'état suit le travail jusqu'à ce que le téléchargement soit prêt. Voir [exportation dans la console](#exporting-receipts-1).

## Rédaction de reçus

La rédaction supprime définitivement les informations personnelles identifiables (PII) de la charge utile d'un reçu tout en préservant la preuve cryptographique. La signature du reçu, l'entrée du journal de transparence et la preuve d'inclusion Merkle restent intactes — seul le `payload_json` est remplacé par un marqueur de rédaction.

Utilisez ceci pour les demandes de droit à l'effacement GDPR sur les reçus contenant des données personnelles.

```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 rédaction est permanente. La charge utile originale ne peut pas être restaurée. La preuve cryptographique reste valide à des fins d'audit.

Après rédaction :

* `status` passe à `redacted`
* `payload_json` est remplacé par `{"redacted": true, "redacted_by": "tenant_request"}`
* Un événement `RECEIPT_REDACT` est ancré dans le journal de transparence
* Tous les autres champs (signature, preuve de journal, type de reçu) sont conservés

## Gestion des reçus dans la console

Vous pouvez gérer le cycle de vie complet des reçus depuis la console sans écrire de code. Ouvrez **Reçus** dans la barre latérale de la console pour accéder aux fonctionnalités suivantes.

### Recherche de reçus

La page de liste des reçus comprend une barre de recherche et des filtres. Tapez un mot-clé pour rechercher dans les charges utiles des reçus, ou utilisez les commandes de filtre pour affiner les résultats par type de reçu, statut, émetteur ou plage de dates. Les résultats se mettent à jour en temps réel au fur et à mesure que vous affinez votre requête.

### Exportation des reçus

Cliquez sur **Exporter** dans la liste des reçus pour mettre en file d'attente une exportation en masse au format CSV ou JSON. Une bannière d'état apparaît en haut de la page, suivant le travail à travers les états `pending`, `running` et `complete`. Une fois l'exportation terminée, cliquez sur la bannière pour télécharger le fichier. Vous pouvez également surveiller les tâches d'exportation depuis l'API en utilisant `GET /v1/receipt-exports/{id}` — voir [exporter les reçus](https://docs.truthlocks.com/fr/api-reference/receipts/export.md).

### Téléchargement d'un paquet de preuves

Ouvrez la page de détails de n'importe quel reçu et cliquez sur **Télécharger le paquet de preuve** pour enregistrer un paquet de vérification autonome. Le paquet comprend l'enveloppe du reçu signé, la preuve d'inclusion Merkle et l'instantané de la clé de l'émetteur — tout ce qui est nécessaire pour la [vérification hors ligne](#proof-bundles).

### Masquer un reçu

Depuis la page de détails de n'importe quel reçu actif, cliquez sur **Masquer** pour supprimer définitivement les informations personnellement identifiables de la charge utile. Une boîte de dialogue de confirmation explique que la masquage est irréversible avant de continuer. La masquage n'est disponible que pour les reçus avec le statut `active`. Après la masquage, la preuve cryptographique et l'entrée du journal de transparence sont préservées — seul le contenu de la charge utile est supprimé. Voir [masquage des reçus](#redacting-receipts) pour plus de détails sur les changements.

## Politique de rétention

Les reçus sont automatiquement nettoyés en fonction de la politique de rétention définie au moment de la création. Un processus en arrière-plan supprime les reçus expirés selon un calendrier régulier.

Définissez `retention_policy` lors de la frappe :

| Politique | Durée | Description |
| - | - | - |
| `standard` | 2 ans | Par défaut. Convient à la plupart des reçus transactionnels. |
| `extended` | 7 ans | Pour les cas d'utilisation de conformité nécessitant une rétention plus longue. |
| `permanent` | Jamais | Jamais supprimé automatiquement. |

Les reçus approchant leur date limite de conservation peuvent être expurgés au lieu d'être supprimés si vous avez besoin de préserver la preuve cryptographique tout en supprimant les données de la charge utile.

## Prochaines étapes

> [card] [Spécification du paquet de preuves](https://docs.truthlocks.com/specification/proof-bundle.md)
>
> Structure complète et étapes de vérification hors ligne pour les bundles de preuves.

> [card] [Référence de l'API des reçus](https://docs.truthlocks.com/api-reference/receipts/mint.md)
>
> Référence API complète pour la création, la recherche, l'exportation et la rédaction de reçus.

> [card] [Webhooks](https://docs.truthlocks.com/guides/webhooks.md)
>
> Abonnez-vous aux événements de réception et traitez-les en temps réel.

> [card] [Politiques d'émission](https://docs.truthlocks.com/guides/issuance-policies.md)
>
> Appliquer des flux d'approbation et des contraintes sur la création de reçus.


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