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

# Belege

> Kryptographisch signierte, in Transparenzprotokollen verankerte Belege für jedes Ereignis

## Was sind Quittungen?

Belege sind signierte, unveränderliche Aufzeichnungen diskreter Ereignisse – Zahlungen, Sicherheitsvorfälle, Compliance-Prüfungen, Lieferungen und mehr. Im Gegensatz zu Protokollen oder Audit-Trails ist jeder Beleg:

* **Kryptografisch signiert** mit Ihrem Ausstellerschlüssel (Ed25519 oder ES256)
* **Verankert im Transparenzprotokoll** mit einem Merkle-Inklusionsnachweis
* **Offline verifizierbar** über den Export von Proof-Bundles
* **Idempotent** – dasselbe Ereignis erzeugt immer denselben Beleg

## Belegtypen

Plattformdefinierte Belegtypen stehen allen Mandanten zur Verfügung. Jeder Typ hat ein JSON-Schema, gegen das das Feld `payload` vor der Signierung validiert wird.

| Typ | Anwendungsfall |
| - | - |
| `payment_receipt` | Zahlungen, Rechnungen, Rückerstattungen |
| `security_event_receipt` | Authentifizierungsereignisse, Schlüsselrotationen, Anomalien |
| `delivery_receipt` | Dokumentenzustellung, Benachrichtigungen |
| `compliance_receipt` | KYC/AML-Prüfungen, regulatorische Nachweise |
| `custom_receipt` | Jedes andere Ereignis mit offenem Schema |

### Verfügbare Typen entdecken

Rufen Sie [`GET /v1/receipt-types`](https://docs.truthlocks.com/de/api-reference/receipts/list-types) auf, um alle Typen aufzulisten, die Ihr Mandant verwenden kann, oder [`GET /v1/receipt-types/{name}`](https://docs.truthlocks.com/de/api-reference/receipts/get-type), um einen einzelnen Typ abzurufen und sein JSON-Schema zu überprüfen.

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

## Einen Beleg prägen

Das Beispiel verwendet illustrative IDs und Nutzlastwerte. Ersetzen Sie diese durch Ihren Arbeitsbereich-Aussteller, den verfügbaren Signaturschlüssel und eine Nutzlast, die dem ausgewählten Belegtyp-Schema entspricht. Übermitteln Sie das Beispiel nicht als echten Zahlungsdatensatz.

**1. Wählen Sie einen Belegtyp**

Rufen Sie `GET /v1/receipt-types` auf, um verfügbare Typen aufzulisten und das Schema auf erforderliche Felder zu überprüfen.

**2. Erstellen Sie Ihre Payload**

Erstellen Sie das Objekt `payload`, das den erforderlichen Feldern für Ihren Belegtyp entspricht. Für `payment_receipt` benötigen Sie `amount`, `currency`, `provider`, `provider_reference` und `subject`.

**3. Über API prägen**

```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. Die receipt\_id speichern**

Die Antwort enthält die `receipt_id` und `log.leaf_index`. Speichern Sie beide für zukünftige Verifizierungen.

## SDK-Beispiele

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

### Belege auflisten

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

### Abrufen eines Belegs

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

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

## Webhook-Ereignisse

Abonnieren Sie Empfangsereignisse, indem Sie einen Webhook-Endpunkt in der Konsole konfigurieren:

| Ereignis | Ausgelöst wenn |
| - | - |
| `receipt.created` | Eine Quittung wird erfolgreich geprägt |
| `receipt.revoked` | Eine Quittung wird widerrufen |

## Widerruf eines Belegs

Der Widerruf ist dauerhaft und wird im Transparenzprotokoll aufgezeichnet. Belege mit dem Status `revoked` bleiben abfragbar, und ihr Widerrufszeitstempel ist in den Proof-Bundles enthalten. Sie können einen optionalen `reason` hinzufügen, um den Grund für den Widerruf des Belegs zu erfassen.

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

## Eine Quittung verifizieren

Verwenden Sie den Verify-Endpunkt, um die kryptografische Gültigkeit und den aktuellen Status eines Belegs zu überprüfen. Die API prüft die Signatur, den Schlüsselstatus und den Widerrufsstatus und gibt dann ein Urteil zurück.

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

### Urteile

| Urteil | Bedeutung |
| - | - |
| `VALID` | Signatur ist gültig, Schlüssel ist aktiv, Beleg ist nicht widerrufen |
| `REVOKED` | Beleg wurde explizit widerrufen |
| `INVALID_SIGNATURE` | Kryptografische Signaturprüfung fehlgeschlagen |
| `KEY_COMPROMISED` | Signaturschlüssel wurde zum Zeitpunkt der Ausstellung oder davor als kompromittiert markiert |
| `KEY_INACTIVE` | Signaturschlüssel ist nicht mehr aktiv |
| `NOT_FOUND` | Beleg für diesen Mandanten nicht gefunden |

## Proof-Bundles

Ein Proof Bundle ist ein eigenständiges Paket zur Offline-Verifizierung. Es enthält den signierten Empfangs-Umschlag, den Merkle-Inklusionsnachweis aus dem Transparenzprotokoll und den Schnappschuss des Ausstellerschlüssels zum Zeitpunkt der Ausstellung.

Nach dem Herunterladen eines Proof-Bundles können Sie den Beleg überprüfen, ohne weitere API-Aufrufe zu tätigen.

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

Die vollständige Bündelstruktur finden Sie in der [API-Referenz für Proof-Bundles](https://docs.truthlocks.com/de/api-reference/receipts/proof-bundle.md).

> [!TIP]
>
> Sie können Proof-Bundles direkt aus der Konsole herunterladen. Öffnen Sie die Detailseite eines Belegs und klicken Sie auf **Proof-Bundle herunterladen**. Siehe [Herunterladen in der Konsole](#downloading-a-proof-bundle).

## Belege suchen

Suchen Sie in Ihren Belegen mithilfe der Volltextsuche und facettierten Filtern. Der Suchindex unterstützt Abfragen von Nutzlastinhalten, und Sie können die Ergebnisse nach Typ, Status, Datumsbereich oder indizierten Nutzlastfeldern eingrenzen.

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

### Suchfilter

| Feld | Typ | Beschreibung |
| - | - | - |
| `q` | string | Volltextsuche über den Nutzlastinhalt |
| `receipt_type` | string | Nach Typnamen filtern |
| `status` | string | `active`, `revoked`, `superseded` oder `redacted` |
| `issuer_id` | UUID | Nach Aussteller filtern |
| `from_date` | RFC 3339 | Beginn des Datumsbereichs |
| `to_date` | RFC 3339 | Ende des Datumsbereichs |
| `index_key` | string | Name des indizierten Payload-Feldes |
| `index_value` | string | Wert, der für `index_key` übereinstimmen soll |
| `limit` | integer | Maximale Ergebnisse (1–100, Standard 20) |
| `offset` | integer | Paginierungs-Offset |

> [!TIP]
>
> Sie können Belege auch über die Konsole suchen, ohne Code schreiben zu müssen. Öffnen Sie **Belege** in der Seitenleiste und verwenden Sie die Suchleiste und Filtersteuerungen. Siehe [Suchen in der Konsole](#searching-receipts-1).

## Belege exportieren

Einen asynchronen Massenexport von Belegen als JSON oder CSV in die Warteschlange stellen. Die API kehrt sofort mit einer Job-ID zurück. Fragen Sie den Exportstatus-Endpunkt ab, bis `status` `complete` ist, und laden Sie dann von der vorab signierten URL herunter.

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

### Exportstatuswerte

| Status | Bedeutung |
| - | - |
| `pending` | In Warteschlange, noch nicht gestartet |
| `running` | Aufzeichnungen verarbeiten |
| `complete` | Fertig – `download_url` ist verfügbar |
| `failed` | Fehler – siehe `error_message` |

> [!TIP]
>
> Sie können Exporte in die Warteschlange stellen und deren Fortschritt über die Konsole verfolgen. Öffnen Sie **Belege**, klicken Sie auf **Exportieren** und wählen Sie CSV oder JSON. Ein Statusbanner verfolgt den Auftrag, bis der Download bereit ist. Siehe [Exportieren in der Konsole](#exporting-receipts-1).

## Belege redigieren

Die Redaktion entfernt PII dauerhaft aus der Nutzlast eines Belegs, während der kryptografische Nachweis erhalten bleibt. Die Signatur des Belegs, der Transparenzprotokolleintrag und der Merkle-Inklusionsnachweis bleiben intakt – nur die `payload_json` wird durch einen Redaktionsmarker ersetzt.

Verwenden Sie dies für DSGVO-Anfragen zum Recht auf Löschung von Belegen, die personenbezogene Daten enthalten.

```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]
>
> Die Schwärzung ist dauerhaft. Die ursprüngliche Nutzlast kann nicht wiederhergestellt werden. Der kryptografische Nachweis bleibt für Prüfzwecke gültig.

Nach der Redaktion:

* `status` ändert sich zu `redacted`
* `payload_json` wird durch `{"redacted": true, "redacted_by": "tenant_request"}` ersetzt
* Ein `RECEIPT_REDACT` Ereignis ist im Transparenzprotokoll verankert
* Alle anderen Felder (Signatur, Log-Nachweis, Belegtyp) bleiben erhalten

## Belege in der Konsole verwalten

Sie können den gesamten Beleg-Lebenszyklus von der Konsole aus verwalten, ohne Code schreiben zu müssen. Öffnen Sie **Belege** in der Konsolen-Seitenleiste, um auf die folgenden Funktionen zuzugreifen.

### Belege suchen

Die Seite mit der Belegliste enthält eine Suchleiste und Filter. Geben Sie ein Stichwort ein, um Beleg-Payloads zu durchsuchen, oder verwenden Sie die Filtersteuerelemente, um die Ergebnisse nach Belegtyp, Status, Aussteller oder Datumsbereich einzugrenzen. Die Ergebnisse werden in Echtzeit aktualisiert, während Sie Ihre Abfrage verfeinern.

### Exportieren von Belegen

Klicken Sie in der Belegliste auf **Exportieren**, um einen Massenexport als CSV oder JSON in die Warteschlange zu stellen. Ein Statusbanner erscheint oben auf der Seite und verfolgt den Auftrag durch die Zustände `pending`, `running` und `complete`. Sobald der Export abgeschlossen ist, klicken Sie auf das Banner, um die Datei herunterzuladen. Sie können Exportaufträge auch über die API mit `GET /v1/receipt-exports/{id}` überwachen – siehe [Belege exportieren](https://docs.truthlocks.com/de/api-reference/receipts/export.md).

### Herunterladen eines Proof-Bundles

Öffnen Sie die Detailseite eines beliebigen Belegs und klicken Sie auf **Nachweis-Bundle herunterladen**, um ein eigenständiges Verifizierungspaket zu speichern. Das Bundle enthält den signierten Belegumschlag, den Merkle-Inklusionsnachweis und den Ausstellerschlüssel-Snapshot – alles, was für die [Offline-Verifizierung](#proof-bundles) benötigt wird.

### Redigieren eines Belegs

Klicken Sie auf der Detailseite eines aktiven Belegs auf **Redigieren**, um persönlich identifizierbare Informationen dauerhaft aus der Nutzlast zu entfernen. Ein Bestätigungsdialog erklärt, dass die Redaktion irreversibel ist, bevor Sie fortfahren. Die Redaktion ist nur für Belege mit dem Status `active` verfügbar. Nach der Redaktion bleiben der kryptografische Nachweis und der Transparenzprotokolleintrag erhalten – nur der Inhalt der Nutzlast wird entfernt. Weitere Informationen zu den Änderungen finden Sie unter [Belege redigieren](#redacting-receipts).

## Aufbewahrungsrichtlinie

Belege werden automatisch gemäß der zum Zeitpunkt der Erstellung festgelegten Aufbewahrungsrichtlinie bereinigt. Ein Hintergrundprozess löscht abgelaufene Belege nach einem regelmäßigen Zeitplan.

Setzen Sie `retention_policy` beim Prägen:

| Richtlinie | Dauer | Beschreibung |
| - | - | - |
| `standard` | 2 Jahre | Standard. Geeignet für die meisten Transaktionsbelege. |
| `extended` | 7 Jahre | Für Compliance-Anwendungsfälle, die eine längere Aufbewahrung erfordern. |
| `permanent` | Nie | Wird nie automatisch gelöscht. |

Belege, die sich ihrem Aufbewahrungsende nähern, können geschwärzt statt gelöscht werden, wenn Sie den kryptografischen Nachweis erhalten möchten, während Sie die Payload-Daten entfernen.

## Nächste Schritte

> [card] [Proof-Bundle-Spezifikation](https://docs.truthlocks.com/specification/proof-bundle.md)
>
> Vollständige Struktur und Offline-Verifizierungsschritte für Proof-Bundles.

> [card] [Receipts API-Referenz](https://docs.truthlocks.com/api-reference/receipts/mint.md)
>
> Vollständige API-Referenz für das Prägen, Suchen, Exportieren und Redigieren von Belegen.

> [card] [Webhooks](https://docs.truthlocks.com/guides/webhooks.md)
>
> Abonnieren Sie Empfangsereignisse und verarbeiten Sie diese in Echtzeit.

> [card] [Ausstellungsrichtlinien](https://docs.truthlocks.com/guides/issuance-policies.md)
>
> Genehmigungsworkflows und Einschränkungen für die Belegprägung durchsetzen.


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