# 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.youraiconnector.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",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "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 mit `GET /pipelines` (siehe [Pipelines](#pipelines) weiter unten). Phasen-IDs sind über alle Ihre Pipelines hinweg eindeutig, daher wird `pipeline_id` von der Phase abgeleitet und ist schreibgeschützt: `default` ist Ihre Haupt-Pipeline, und sie ist `null`, wenn die Phase nicht mehr existiert. Zeitstempel entsprechen ISO 8601.

Ein Deal speichert nur die oben gezeigten Felder. Wenn Sie einen erstellen oder aktualisieren, wird jedes andere Feld mit einem `400` abgelehnt, das es benennt, sodass nichts, was Sie senden, stillschweigend verloren geht. Speichern Sie zusätzliche Daten in den benutzerdefinierten Feldern des verknüpften Kontakts.

---

## Deals auflisten

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

**Abfrageparameter** (alle optional): `stage` (eine Phasen-ID), `pipeline_id` (nur die Deals in dieser Pipeline), `contact_id`, `limit` (Standard 50, max. 200), `cursor` (von der `next_cursor` der vorherigen Seite).

**cURL**

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

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` muss eine Zahl sein.

```bash
curl -X PUT "https://api.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

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

---

## Pipelines

Jedes Konto hat eine Haupt-Pipeline (`id: "default"`); Sie können bis zu neun weitere hinzufügen, jede mit ihren eigenen Phasen. Phasen-IDs und Trigger-Tags müssen über alle Pipelines des Kontos hinweg eindeutig sein, und jede Pipeline kann eine Phase als `won` und eine als `lost` markieren.

### Pipelines auflisten

`GET /pipelines` — jede Pipeline, beginnend mit der Haupt-Pipeline, jeweils mit den nach Position sortierten Phasen.

```bash
curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`):

```json
{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}
```

### Pipeline erstellen

`POST /pipelines` — Body `{ "id"?, "name", "stages"?, "settings"? }`. Lassen Sie `id` weg, damit eine generiert wird. Jede Phase verwendet dieselben Felder wie der Phasen-Dialog: `id`, `name`, `color`, `position`, optional `trigger_tag` (ein Tag-Pfad, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (eine Phase derselben Pipeline) und `outcome` (`"won"` oder `"lost"`).

```bash
curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'
```

**Antwort** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Eine Phasen-ID oder ein Trigger-Tag, das bereits von einer anderen Pipeline verwendet wird, ist ein `400`, das diese Pipeline benennt; eine ID, die bereits existiert, ist ein `409`.

### Pipeline aktualisieren

`PUT /pipelines/{pipelineId}` — Body `{ "name"?, "stages"?, "settings"? }`. `stages` ersetzt die gesamte Liste, wie im Phasen-Dialog. Verwenden Sie `default` für die Haupt-Pipeline. Die Pipeline-ID selbst kann nicht geändert werden.

### Pipeline löschen

`DELETE /pipelines/{pipelineId}` — entfernt eine zusätzliche Pipeline (die Haupt-Pipeline kann nicht gelöscht werden). Wenn sich noch Deals in ihren Phasen befinden, antwortet der Aufruf mit `409` und `deal_count`; fügen Sie `?delete_deals=true` hinzu, um diese Deals zusammen mit der Pipeline zu löschen. **Dies kann nicht rückgängig gemacht werden.**

**Antwort** (`204`).

---

## Nächste Schritte

- [Sales Pipeline](../deals/sales-pipeline.md) — wie Phasen, Phasen-Tags, mehrere Pipelines und das Board funktionieren.
- [Tasks 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 innerhalb eines Workflows dieselben Daten.