# 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.youraiconnector.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",
  "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` är id:t för ett av dina pipelinesteg — läs dem med `GET /pipelines` (se [Pipelines](#pipelines) nedan). Steg-id:n är unika för alla dina pipelines, så `pipeline_id` härleds från steget och är skrivskyddat: `default` är din huvudpipeline, och den är `null` när steget inte längre finns. Tidsstämplar är ISO 8601.

En affär lagrar endast fälten som visas ovan. När du skapar eller uppdaterar en, nekas alla andra fält med ett `400` som namnger dem, så att inget du skickar går förlorat i tysthet. Spara extra data i den länkade kontaktens anpassade fält.

---

## Lista affärer

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

**Frågeparametrar** (alla valfria): `stage` (ett steg-id), `pipeline_id` (endast affärer i den pipelinen), `contact_id`, `limit` (standard 50, max 200), `cursor` (från föregående sidas `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 }
```

---

## Hämta en affär

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

---

## Uppdatera en affär

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

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

---

## 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.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 }`

---

## Ta bort en affär

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

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

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

---

## Pipelines

Varje konto har en huvudpipeline (`id: "default"`); du kan lägga till upp till nio till, var och en med sina egna steg. Steg-id:n och trigger-taggar måste vara unika för alla pipelines på kontot, och varje pipeline kan markera ett steg som sitt `won` och ett som sitt `lost` resultat.

### Lista pipelines

`GET /pipelines` — varje pipeline, huvudpipelinen först, var och en med sina steg sorterade 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" }
        ]
      }
    ]
  }
}
```

### Skapa en pipeline

`POST /pipelines` — brödtext `{ "id"?, "name", "stages"?, "settings"? }`. Lämna `id` tomt för att få ett genererat. Varje steg använder samma fält som dialogrutan Steg: `id`, `name`, `color`, `position`, valfritt `trigger_tag` (en taggsökväg, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (ett steg i samma pipeline) och `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": { ... } } }`. Ett steg-id eller en trigger-tagg som redan används av en annan pipeline är en `400` som namnger den pipelinen; ett id som redan finns är en `409`.

### Uppdatera en pipeline

`PUT /pipelines/{pipelineId}` — brödtext `{ "name"?, "stages"?, "settings"? }`. `stages` ersätter hela listan, precis som i dialogrutan Steg. Använd `default` för huvudpipelinen. Själva pipeline-id:t kan inte ändras.

### Ta bort en pipeline

`DELETE /pipelines/{pipelineId}` — tar bort en extra pipeline (huvudpipelinen kan inte tas bort). Om det fortfarande finns affärer i dess steg svarar anropet `409` med `deal_count`; lägg till `?delete_deals=true` för att ta bort dessa affärer tillsammans med pipelinen. **Detta kan inte ångras.**

**Svar** (`204`).

---

## Nästa steg

- [Försäljningspipeline](../deals/sales-pipeline.md) — hur stadier, stadieetiketter, flera pipelines 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.