# Deals API

En handel er en salgsmulighed på din [Salgspipeline](../deals/sales-pipeline.md)-tavle — en titel, en værdi, det stadie den befinder sig i, og valgfrit den kontaktperson den tilhører, og det teammedlem den er tildelt. Denne guide dækker læsning og håndtering af handler via API'et.

- **Base URL** — `https://api.youraiconnector.com/v1`
- **Autentificering** — din API-nøgle (se [Autentificering](authentication.md))
- **Fejl & paginering** — se [Fejl & Paginering](errors-and-pagination.md)

Alle eksempler herunder viser `?apiKey=` forespørgselsformen i cURL og `X-API-Key` headeren i JavaScript og Python — begge virker på alle slutpunkter.

---

## Handelsobjektet

```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` er id'et på et af dine pipelinestadier — læs dem med `GET /pipelines` (se [Pipelines](#pipelines) nedenfor). Stadie-id'er er unikke på tværs af alle dine pipelines, så `pipeline_id` er afledt af stadiet og er skrivebeskyttet: `default` er din hovedpipeline, og den er `null`, når stadiet ikke længere eksisterer. Tidsstempler er ISO 8601.

En aftale gemmer kun de felter, der er vist ovenfor. Når du opretter eller opdaterer en, afvises ethvert andet felt med en `400`, der navngiver det, så intet af det, du sender, går tabt uden videre. Gem ekstra data i den tilknyttede kontakts brugerdefinerede felter.

---

## List handler

`GET /deals` — returnerer handlerne på din konto, nyeste først.

**Forespørgselsparametre** (alle valgfrie): `stage` (et stadie-id), `pipeline_id` (kun handlerne på den pipeline), `contact_id`, `limit` (standard 50, maks 200), `cursor` (fra den forrige sides `next_cursor`).

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

**Svar** (`200`)

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

---

## Hent en handel

`GET /deals/{dealId}`

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

**Svar** (`200`)

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

En handel, der ikke eksisterer, eller som tilhører en anden konto, returnerer `404`.

---

## Opret en handel

`POST /deals` — `title` og `stage` er påkrævet; `stage` skal være et af din pipelines stadie-id'er.

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

**Svar** (`201`)

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

---

## Opdater en handel

`PUT /deals/{dealId}` — send kun de felter, du vil ændre (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` skal være et tal.

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

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

---

## Flyt en handel til et andet stadie

`POST /deals/{dealId}/move` — body `{ "new_stage_id": "stage-3", "new_position": 0 }`. Position `0` placerer kortet øverst i kolonnen.

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

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

---

## Slet en handel

`DELETE /deals/{dealId}` — fjerner handlen. **Dette kan ikke fortrydes.**

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

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

---

## Pipelines

Hver konto har en hovedpipeline (`id: "default"`); du kan tilføje op til ni mere, hver med sine egne stadier. Stadie-id'er og trigger-tags skal være unikke på tværs af alle pipelines på kontoen, og hver pipeline kan markere ét stadie som sit `won` og ét som sit `lost` resultat.

### List pipelines

`GET /pipelines` — hver pipeline, hovedpipelinen først, hver med sine stadier sorteret efter position.

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

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

### Opret en pipeline

`POST /pipelines` — brødtekst `{ "id"?, "name", "stages"?, "settings"? }`. Udelad `id` for at få genereret et. Hvert stadie bruger de samme felter som Stadier-dialogen: `id`, `name`, `color`, `position`, valgfri `trigger_tag` (en tag-sti, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (et stadie i samme pipeline) og `outcome` (`"won"` eller `"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" }
    ]
  }'
```

**Svar** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Et stadie-id eller trigger-tag, der allerede bruges af en anden pipeline, er en `400`, der navngiver den pipeline; et id, der allerede eksisterer, er en `409`.

### Opdater en pipeline

`PUT /pipelines/{pipelineId}` — brødtekst `{ "name"?, "stages"?, "settings"? }`. `stages` erstatter hele listen, ligesom Stadier-dialogen. Brug `default` til hovedpipelinen. Selve pipeline-id'et kan ikke ændres.

### Slet en pipeline

`DELETE /pipelines/{pipelineId}` — fjerner en ekstra pipeline (hovedpipelinen kan ikke slettes). Hvis der stadig er handler i dens stadier, svarer kaldet `409` med `deal_count`; tilføj `?delete_deals=true` for at slette disse handler sammen med pipelinen. **Dette kan ikke fortrydes.**

**Svar** (`204`).

---

## Næste skridt

- [Salgspipeline](../deals/sales-pipeline.md) — hvordan stadier, stadietags, flere pipelines og tavlen fungerer.
- [Tasks API](tasks.md) — opgaver kan linkes til en handel med `deal_id`.
- [Automatiseringer](../automations/automations.md) — trinnene **Find handler** og **Find handel** læser de samme data i et workflow.