---
title: Schnellstart
description: >-
  Tätigen Sie Ihren ersten Kauf mit einem Testschlüssel und wechseln Sie dann in
  den Echtbetrieb.
mode: wide
sidebar:
  order: 1
---
## 1. Zugang erhalten [#1-get-access]

Beantragen Sie API-Zugang auf der [Entwicklerseite](https://trimcarbon.com/developers/access). Bevor wir einen Antrag genehmigen, muss das Konto die Zwei-Faktor-Authentifizierung oder einen Passkey nutzen. Wir senden Ihnen eine E-Mail, sobald das Konto aktiv ist.

## 2. Testschlüssel erstellen [#2-create-a-test-key]

Erstellen Sie auf der Entwicklerseite einen Schlüssel im Modus **Test** mit dem Zugriff **Lesen und kaufen**. Kopieren Sie ihn sofort, denn wir zeigen ihn nur einmal an.

Testschlüssel verbrauchen ein simuliertes Guthaben von 1.000 $. Es wird nichts abgerechnet und es werden keine CO₂-Zertifikate stillgelegt. So können Sie Ihre Integration gefahrlos entwickeln.

## 3. Angebot einholen [#3-get-a-quote]

Ein Angebot zeigt Ihnen, was ein Kauf umfassen und kosten würde, ohne dass etwas gekauft wird:

```bash
curl https://trimcarbon.com/api/v1/quotes \
  -H "Authorization: Bearer $TRIMCARBON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kg": 100}'
```

## 4. Kompensationen kaufen [#4-buy-offsets]

Senden Sie bei jedem Kauf einen eindeutigen `Idempotency-Key` mit. Wenn bei der Anfrage eine Zeitüberschreitung auftritt, wiederholen Sie sie mit demselben Schlüssel. Sie erhalten dann den ersten Kauf als Antwort, statt doppelt zu kaufen.

```bash
curl https://trimcarbon.com/api/v1/offsets \
  -H "Authorization: Bearer $TRIMCARBON_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kg": 100, "reference": "fleet-2026-09"}'
```

`POST /offsets`

**Request body** (`application/json`, required)

Exactly one of \`kg\` (whole kg, up to 1,000,000) and \`amount\_cents\`, and an optional \`reference\`.

Request body example, By volume:

```json
{
  "kg": 1000,
  "reference": "fleet-2026-09"
}
```

Request body example, By price:

```json
{
  "amount_cents": 5000
}
```

**Responses**

- `201` — The purchase (or, on a retry, the first one).
- `400` — Bad JSON, or a missing or invalid Idempotency-Key.
- `401` — Missing, unknown or revoked API key.
- `402` — \`insufficient\_balance\`: the balance doesn’t cover the purchase. The error has \`balance\_cents\` and \`required\_cents\`.
- `403` — \`api\_access\_inactive\` (the account is suspended or not approved) or \`insufficient\_permissions\` (a read-only key).
- `409` — \`idempotency\_key\_reused\`: the key was used for a different request.
- `422` — \`validation\_error\` (with \`param\`) or \`amount\_too\_small\`.
- `429` — \`rate\_limited\`: wait for the \`Retry-After\` seconds.

Response example, 201:

```json
{
  "object": "offset",
  "id": "off_8Hq2kP0aZr4mXc1vB7nT3yLw",
  "livemode": true,
  "status": "processing",
  "kg": 0,
  "amount_cents": 0,
  "currency": "usd",
  "rate_millicents_per_kg": 4000,
  "requested": {
    "kg": 0,
    "amount_cents": 0
  },
  "reference": "string",
  "certificate_url": "http://example.com",
  "created": "2026-10-08T14:03:12.000Z",
  "placed": "2026-10-08T14:03:12.000Z"
}
```

## 5. Bestellung verfolgen [#5-follow-the-order]

Eine Kompensation hat zunächst den Status `processing`. Fragen Sie sie regelmäßig ab, bis sie den Status `placed` hat:

```bash
curl https://trimcarbon.com/api/v1/offsets/off_8Hq2kP0aZr4mXc1vB7nT3yLw \
  -H "Authorization: Bearer $TRIMCARBON_KEY"
```

Eine Testkompensation erreicht den Status `placed` nach wenigen Sekunden. Bei einer echten Kompensation dauert das meist einige Minuten. Danach verweist `certificate_url` auf ihr öffentliches TrimCarbon-Zertifikat.

## 6. Echtbetrieb starten [#6-go-live]

1. Laden Sie Ihr Guthaben auf der Entwicklerseite auf.
2. Erstellen Sie einen Schlüssel im Modus **Echt** und speichern Sie ihn als Secret auf Ihrem Server.
3. Ersetzen Sie den Testschlüssel durch den echten Schlüssel. Sonst ändert sich nichts.

:::warning
Bei echten Käufen werden echte CO₂-Zertifikate stillgelegt. Das Guthaben ist vorausbezahlt und wird nicht erstattet. Weitere Informationen finden Sie unter [Guthaben und Käufe](/docs/de/balance).
:::