# Deals API

Een deal is één verkoopkans op je [Sales Pipeline](../deals/sales-pipeline.md)-bord — een titel, een waarde, de fase waarin deze zich bevindt, en optioneel de contactpersoon waartoe deze behoort en het teamlid aan wie deze is toegewezen. Deze handleiding behandelt het lezen en beheren van deals via de API.

- **Basis-URL** — `https://api.dmchamp.com/v1`
- **Authenticatie** — uw API-sleutel (zie [Authenticatie](authentication.md))
- **Fouten & paginering** — zie [Fouten & Paginering](errors-and-pagination.md)

Alle onderstaande voorbeelden tonen de `?apiKey=` query-vorm in cURL en de `X-API-Key` header in JavaScript en Python — beide werken op elk eindpunt.

---

## Het deal-object

```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` is de id van een van je pipeline-fasen — lees deze uit je pipeline-instellingen (`GET /users/me/pipeline-settings`). Tijdstempels zijn ISO 8601.

---

## Deals weergeven

`GET /deals` — retourneert de deals in je account, de nieuwste eerst.

**Queryparameters** (allemaal optioneel): `stage` (een fase-id), `contact_id`, `limit` (standaard 50, max 200), `cursor` (van de `next_cursor` van de vorige pagina).

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

**Antwoord** (`200`)

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

---

## Een deal ophalen

`GET /deals/{dealId}`

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

**Antwoord** (`200`)

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

Een deal die niet bestaat, of die bij een ander account hoort, retourneert `404`.

---

## Een deal aanmaken

`POST /deals` — `title` en `stage` zijn verplicht; `stage` moet een van de fase-id's van je pipeline zijn.

```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" }'
```

**Antwoord** (`201`)

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

---

## Een deal bijwerken

`PUT /deals/{dealId}` — stuur alleen de velden die je wilt wijzigen (`title`, `description`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` moet een getal zijn.

```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" }'
```

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

---

## Verplaats een deal naar een andere fase

`POST /deals/{dealId}/move` — body `{ "new_stage_id": "stage-3", "new_position": 0 }`. Positie `0` plaatst de kaart bovenaan de kolom.

```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 }'
```

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

---

## Een deal verwijderen

`DELETE /deals/{dealId}` — verwijdert de deal. **Dit kan niet ongedaan worden gemaakt.**

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

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

---

## Volgende stappen

- [Verkooppijplijn](../deals/sales-pipeline.md) — hoe fasen, fasetags en het bord werken.
- [Taken-API](tasks.md) — taken kunnen aan een deal worden gekoppeld met `deal_id`.
- [Automatiseringen](../automations/automations.md) — de stappen **Deals zoeken** en **Deal zoeken** lezen dezelfde gegevens binnen een workflow.