# 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.youraiconnector.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",
  "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` is de id van een van je pijplijnfasen — lees ze met `GET /pipelines` (zie [Pijplijnen](#pipelines) hieronder). Fase-ids zijn uniek voor al je pijplijnen, dus `pipeline_id` is afgeleid van de fase en is alleen-lezen: `default` is je hoofdpijplijn, en deze is `null` wanneer de fase niet langer bestaat. Tijdstempels zijn ISO 8601.

Een deal slaat alleen de hierboven getoonde velden op. Wanneer je er een aanmaakt of bijwerkt, wordt elk ander veld geweigerd met een `400` waarin dit wordt benoemd, zodat niets wat je verstuurt stilletjes verloren gaat. Bewaar extra gegevens in de aangepaste velden van de gekoppelde contactpersoon.

---

## Deals weergeven

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

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

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

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

**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`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` moet een getal zijn.

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

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

**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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

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

---

## Pijplijnen

Elk account heeft een hoofdpijplijn (`id: "default"`); je kunt er maximaal negen toevoegen, elk met zijn eigen fasen. Fase-ids en trigger-tags moeten uniek zijn voor alle pijplijnen in het account, en elke pijplijn kan één fase markeren als zijn `won` en één als zijn `lost` resultaat.

### Pijplijnen weergeven

`GET /pipelines` — elke pijplijn, de hoofd-pijplijn eerst, elk met zijn fasen gesorteerd op positie.

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

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

### Een pijplijn aanmaken

`POST /pipelines` — body `{ "id"?, "name", "stages"?, "settings"? }`. Laat `id` weg om er een te laten genereren. Elke fase gebruikt dezelfde velden als het dialoogvenster Fasen: `id`, `name`, `color`, `position`, optioneel `trigger_tag` (een tagpad, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (een fase van dezelfde pijplijn) en `outcome` (`"won"` of `"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" }
    ]
  }'
```

**Antwoord** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Een fase-id of trigger-tag die al door een andere pijplijn wordt gebruikt, is een `400` die die pijplijn benoemt; een id die al bestaat is een `409`.

### Een pijplijn bijwerken

`PUT /pipelines/{pipelineId}` — body `{ "name"?, "stages"?, "settings"? }`. `stages` vervangt de hele lijst, zoals in het dialoogvenster Fasen. Gebruik `default` voor de hoofdpijplijn. De pijplijn-id zelf kan niet worden gewijzigd.

### Een pijplijn verwijderen

`DELETE /pipelines/{pipelineId}` — verwijdert een extra pijplijn (de hoofdpijplijn kan niet worden verwijderd). Als er nog deals in de fasen staan, antwoordt de aanroep met `409` met `deal_count`; voeg `?delete_deals=true` toe om die deals samen met de pijplijn te verwijderen. **Dit kan niet ongedaan worden gemaakt.**

**Antwoord** (`204`).

---

## Volgende stappen

- [Sales Pipeline](../deals/sales-pipeline.md) — hoe fasen, fasetags, meerdere pijplijnen en het bord werken.
- [Tasks API](tasks.md) — taken kunnen worden gekoppeld aan een deal met `deal_id`.
- [Automations](../automations/automations.md) — de stappen **Find deals** en **Find deal** lezen dezelfde gegevens binnen een workflow.