# Deals API

En affär är en försäljningsmöjlighet på din [försäljningspipeline](../deals/sales-pipeline.md) — en titel, ett värde, stadiet den befinner sig i, och valfritt den kontakt den tillhör och den teammedlem den är tilldelad. Den här guiden täcker hur du läser och hanterar affärer via API:et.

- **Bas-URL** — `https://api.dmchamp.com/v1`
- **Autentisering** — din API-nyckel (se [Autentisering](authentication.md))
- **Fel och sidnumrering** — se [Fel och sidnumrering](errors-and-pagination.md)

Alla exempel nedan visar frågeformuläret `?apiKey=` i cURL och headern `X-API-Key` i JavaScript och Python — båda fungerar på alla slutpunkter.

---

## Affärsobjektet

```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` är id:t för ett av dina pipelinestadier — läs dem från dina pipelineinställningar (`GET /users/me/pipeline-settings`). Tidsstämplar är ISO 8601.

---

## Lista affärer

`GET /deals` — returnerar affärerna på ditt konto, med de nyaste först.

**Frågeparametrar** (alla valfria): `stage` (ett stadie-id), `contact_id`, `limit` (standard 50, max 200), `cursor` (från föregående sidas `next_cursor`).

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

**Svar** (`200`)

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

---

## Hämta en affär

`GET /deals/{dealId}`

```bash
curl "https://api.dmchamp.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 affär som inte existerar, eller som tillhör ett annat konto, returnerar `404`.

---

## Skapa en affär

`POST /deals` — `title` och `stage` krävs; `stage` måste vara ett av din pipelines stadie-id:n.

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

**Svar** (`201`)

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

---

## Uppdatera en affär

`PUT /deals/{dealId}` — skicka endast de fält du vill ändra (`title`, `description`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` måste vara ett nummer.

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

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

---

## Flytta en affär till ett annat stadium

`POST /deals/{dealId}/move` — body `{ "new_stage_id": "stage-3", "new_position": 0 }`. Position `0` placerar kortet högst upp i kolumnen.

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

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

---

## Ta bort en affär

`DELETE /deals/{dealId}` — tar bort affären. **Detta går inte att ångra.**

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

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

---

## Nästa steg

- [Försäljningspipeline](../deals/sales-pipeline.md) — hur stadier, stadie-taggar och tavlan fungerar.
- [Tasks API](tasks.md) — uppgifter kan kopplas till en affär med `deal_id`.
- [Automatiseringar](../automations/automations.md) — stegen **Hitta affärer** och **Hitta affär** läser samma data i ett arbetsflöde.