# Deals-API

Ein Deal ist eine Verkaufschance auf Ihrem [Sales Pipeline](../deals/sales-pipeline.md)-Board – bestehend aus einem Titel, einem Wert, der Phase, in der er sich befindet, sowie optional dem zugehörigen Kontakt und dem zugewiesenen Teammitglied. Dieser Leitfaden behandelt das Lesen und Verwalten von Deals über die API.

- **Basis-URL** — `https://api.dmchamp.com/v1`
- **Authentifizierung** — Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md))
- **Fehler & Paginierung** — siehe [Fehler & Paginierung](errors-and-pagination.md)

Alle nachstehenden Beispiele zeigen die `?apiKey=`-Abfrageform in cURL und den `X-API-Key`-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

---

## Das Deal-Objekt

```json
{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "stage": "stage-2",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}
```

`stage` ist die ID einer Ihrer Pipeline-Phasen – lesen Sie diese aus Ihren Pipeline-Einstellungen (`GET /users/me/pipeline-settings`) aus. Zeitstempel entsprechen ISO 8601.

---

## Deals auflisten

`GET /deals` – gibt die Deals Ihres Kontos zurück, beginnend mit dem neuesten.

**Abfrageparameter** (alle optional): `stage` (eine Phasen-ID), `contact_id`, `limit` (Standard 50, max. 200), `cursor` (von der `next_cursor` der vorherigen Seite).

**cURL**

```bash
curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.dmchamp.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]
```

**Antwort** (`200`)

```json
{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }
```

---

## Einen Deal abrufen

`GET /deals/{dealId}`

```bash
curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`)

```json
{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }
```

Ein Deal, der nicht existiert oder zu einem anderen Konto gehört, gibt `404` zurück.

---

## Einen Deal erstellen

`POST /deals` – `title` und `stage` sind erforderlich; `stage` muss eine der Phasen-IDs Ihrer Pipeline sein.

```bash
curl -X POST "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'
```

**Antwort** (`201`)

```json
{ "success": true, "deal_id": "deal_abc123" }
```

---

## Einen Deal aktualisieren

`PUT /deals/{dealId}` – senden Sie nur die Felder, die Sie ändern möchten (`title`, `description`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` muss eine Zahl sein.

```bash
curl -X PUT "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'
```

**Antwort** (`200`): `{ "success": true, "deal_id": "deal_abc123" }`

---

## Einen Deal in eine andere Phase verschieben

`POST /deals/{dealId}/move` — body `{ "new_stage_id": "stage-3", "new_position": 0 }`. Die Position `0` platziert die Karte ganz oben in der Spalte.

```bash
curl -X POST "https://api.dmchamp.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'
```

**Antwort** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }`

---

## Einen Deal löschen

`DELETE /deals/{dealId}` — entfernt den Deal. **Dies kann nicht rückgängig gemacht werden.**

```bash
curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`): `{ "success": true }`

---

## Nächste Schritte

- [Verkaufspipeline](../deals/sales-pipeline.md) — wie Phasen, Phasen-Tags und das Board funktionieren.
- [Aufgaben-API](tasks.md) — Aufgaben können mit `deal_id` mit einem Deal verknüpft werden.
- [Automatisierungen](../automations/automations.md) — die Schritte **Deals finden** und **Deal finden** lesen dieselben Daten innerhalb eines Workflows.