# Konten des Kontakts

Diese Methoden arbeiten mit den [Konten des Kontakts](https://support.watbot.org/de/chatbots/contacts/accounts-referrals#konten) — dem internen Guthaben im Bot: Boni, Punkte, ein Depot. Es sind dieselben Konten, mit denen die Blöcke [„Kontaktkonto aufladen“](https://support.watbot.org/de/chatbots/blocks/contact-data/top-up-balance) und [„Vom Kontaktkonto abbuchen“](https://support.watbot.org/de/chatbots/blocks/contact-data/debit-balance) arbeiten und die in der Kontaktkarte im Tab „Konten“ zu sehen sind. Zum Beispiel kann ein Zahlungssystem dem Kontakt nach einem Kauf auf Ihrer Website Boni gutschreiben, und der Bot zeigt das Guthaben mit der Funktion `getBalance` an.

Für jede Währung hat der Kontakt ein eigenes Konto. Vorgänge über die API erscheinen im Journal des Kontos als „Aufladung über API“ und „Abbuchung über API“.

> [!WARNING]
> Konten des Kontakts sind interne Guthaben des Bots (Boni, Punkte, Depot), keine Bankkonten: Die Plattform überweist darüber kein Geld und ist kein Zahlungsdienst. Führen Sie in Ihrem eigenen System Buch über die Operationen, die Sie über die API senden — damit können Sie die Guthaben abgleichen.

> [!IMPORTANT]
> Beträge werden **in der kleinsten Einheit der Währung** — Cent — als Ganzzahl übergeben und zurückgegeben. `15000` auf einem `EUR`-Konto sind 150 €. Bei Währungen ohne Nachkommastellen, etwa `JPY`, ist die Einheit der ganze Yen. Eine einzelne Aufladung oder Abbuchung beträgt höchstens 10¹⁴ kleinste Einheiten (bei Euro eine Billion Euro); ein höherer Betrag ergibt `422`.

## getContactAccounts

Gibt alle Konten eines Kontakts zurück.

```endpoint
GET POST https://watbot.org/de/api/v1/getContactAccounts
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Ganzzahl | ja | ID des Kontakts |

```bash title="Anfrage"
curl -G "https://watbot.org/de/api/v1/getContactAccounts" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"
```
```json title="Antwort 200"
{
  "data": [
    {
      "id": 4521,
      "currency": "EUR",
      "amount": 15000,
      "amount_note": "150 EUR",
      "created_at": "2026-09-14T10:22:05+02:00",
      "updated_at": "2026-10-01T18:40:12+02:00",
      "blocked_at": null
    }
  ]
}
```

| Feld | Beschreibung |
|---|---|
| `id` | ID des Kontos — sie wird an die übrigen Methoden als `account_id` übergeben |
| `currency` | Währungscode nach ISO 4217 |
| `amount` | Guthaben in der kleinsten Einheit der Währung |
| `amount_note` | Guthaben in Haupteinheiten mit Währungscode, zur Anzeige |
| `created_at`, `updated_at` | Wann das Konto eröffnet und zuletzt geändert wurde |
| `blocked_at` | Wann das Konto gesperrt wurde; `null` — nicht gesperrt. Von einem gesperrten Konto kann nicht abgebucht werden |

Die Konten kommen in der Reihenfolge ihrer Eröffnung.

## addContactAccount

Eröffnet für den Kontakt ein Konto in einer Währung. Dieselbe Methode ist auch unter dem Namen `createContactAccount` erreichbar.

```endpoint
POST https://watbot.org/de/api/v1/addContactAccount
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Ganzzahl | ja | ID des Kontakts |
| `currency` | Zeichenkette | ja | Währungscode nach ISO 4217 in Großbuchstaben: `EUR`, `CHF`, `USD` |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/addContactAccount" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "currency": "EUR"}'
```
```json title="Antwort 201"
{
  "data": {
    "id": 4521,
    "currency": "EUR",
    "amount": 0,
    "amount_note": "0 EUR",
    "created_at": "2026-10-03T12:00:00+02:00",
    "updated_at": "2026-10-03T12:00:00+02:00",
    "blocked_at": null
  }
}
```
```json title="Antwort 422"
{
  "message": "Der Kontakt hat bereits ein Konto in dieser Währung.",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "Der Kontakt hat bereits ein Konto in dieser Währung."
    ]
  }
}
```

Besonderheiten:

- Hat der Kontakt bereits ein Konto in dieser Währung — `422` mit einem Fehler im Feld `currency`.
- Für Blöcke im Szenario muss das Konto nicht vorab existieren: Der Block „Kontaktkonto aufladen“ eröffnet es selbst. Die Aufladung über die API braucht es dagegen, denn sie arbeitet mit `account_id`.

## deleteContactAccount

Löscht ein Konto des Kontakts.

```endpoint
POST https://watbot.org/de/api/v1/deleteContactAccount
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `account_id` | Ganzzahl | ja | ID des Kontos |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/deleteContactAccount" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521}'
```
```json title="Antwort 422"
{
  "message": "Ein Konto mit einem Guthaben von 150 EUR kann nicht gelöscht werden.",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "Ein Konto mit einem Guthaben von 150 EUR kann nicht gelöscht werden."
    ]
  }
}
```

Die Antwort ist der Status `204` ohne Inhalt.

Gelöscht werden kann nur ein leeres Konto. Liegt Geld darauf — `422` mit einem Fehler im Feld `account_id`; buchen Sie zuerst den Rest ab.

## addFundsToContactAccount

Lädt ein Konto auf.

```endpoint
POST https://watbot.org/de/api/v1/addFundsToContactAccount
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `account_id` | Ganzzahl | ja | ID des Kontos |
| `amount` | Ganzzahl | ja | Betrag in der kleinsten Einheit der Währung, von 1 bis 100.000.000.000.000 (10¹⁴) |
| `description` | Zeichenkette | ja | Wofür die Gutschrift ist, bis 255 Zeichen. Erscheint im Journal des Kontos |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/addFundsToContactAccount" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 15000, "description": "Bonus für Bestellung A-1024"}'
```
```json title="Antwort 200"
{
  "data": {
    "id": 4521,
    "currency": "EUR",
    "amount": 15000,
    "amount_note": "150 EUR",
    "created_at": "2026-10-03T12:00:00+02:00",
    "updated_at": "2026-10-03T12:05:41+02:00",
    "blocked_at": null
  }
}
```

Ein gesperrtes Konto lässt sich trotzdem aufladen.

## withdrawFundsFromContactAccount

Bucht von einem Konto ab.

```endpoint
POST https://watbot.org/de/api/v1/withdrawFundsFromContactAccount
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `account_id` | Ganzzahl | ja | ID des Kontos |
| `amount` | Ganzzahl | ja | Betrag in der kleinsten Einheit der Währung, von 1 bis 100.000.000.000.000 (10¹⁴) |
| `description` | Zeichenkette | ja | Wofür die Abbuchung ist, bis 255 Zeichen. Erscheint im Journal des Kontos |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/withdrawFundsFromContactAccount" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 5000, "description": "Versandkosten"}'
```
```json title="Antwort 200"
{
  "data": {
    "id": 4521,
    "currency": "EUR",
    "amount": 10000,
    "amount_note": "100 EUR",
    "created_at": "2026-10-03T12:00:00+02:00",
    "updated_at": "2026-10-03T12:07:15+02:00",
    "blocked_at": null
  }
}
```
```json title="Antwort 422"
{
  "message": "Nicht genügend Guthaben. Aktueller Kontostand: 100 EUR.",
  "code": "insufficient_funds",
  "errors": {
    "account_id": [
      "Nicht genügend Guthaben. Aktueller Kontostand: 100 EUR."
    ]
  }
}
```

Eine Abbuchung bringt das Konto nie ins Minus, auch nicht bei gleichzeitigen Anfragen. Ist die Abbuchung nicht möglich, ändert die Methode nichts und antwortet mit `422` und einem Fehler im Feld `account_id`:

| `code` | Ursache |
|---|---|
| `account_blocked` | Das Konto ist gesperrt — entsperren Sie es in der Kontaktkarte |
| `insufficient_funds` | Auf dem Konto liegt weniger als `amount`; der Text nennt das aktuelle Guthaben |

Zuerst wird die Sperre geprüft, dann das Guthaben.

## Fehler bei Konten

- Kein Kontakt oder Konto mit dieser ID, Kontakt gelöscht oder sein Bot gelöscht — `404`.
- Kontakt oder Konto aus einem fremden Bot — `403`.
- Fehler dieser Methoden sind `422` mit den Feldern `message`, `code` und `errors`. Der Fehlertext ist in der Sprache der Anfrage (Header `Accept-Language`), prüfen Sie im Code daher `code`:

| `code` | Methode | Ursache |
|---|---|---|
| `currency_exists` | `addContactAccount` | Ein Konto in dieser Währung gibt es bereits |
| `account_not_empty` | `deleteContactAccount` | Auf dem Konto ist noch Geld |
| `account_blocked` | `withdrawFundsFromContactAccount` | Das Konto ist gesperrt |
| `insufficient_funds` | `withdrawFundsFromContactAccount` | Nicht genügend Guthaben auf dem Konto |

Allgemeine Fehler der API finden Sie unter [Fehler](https://support.watbot.org/de/api#fehler).