# API delle trattative

Una trattativa è un'opportunità di vendita sulla tua bacheca [Sales Pipeline](../deals/sales-pipeline.md): un titolo, un valore, la fase in cui si trova e, facoltativamente, il contatto a cui appartiene e il membro del team a cui è assegnata. Questa guida illustra come leggere e gestire le trattative tramite l'API.

- **URL di base** — `https://api.dmchamp.com/v1`
- **Autenticazione** — la tua chiave API (vedi [Autenticazione](authentication.md))
- **Errori e paginazione** — vedi [Errori e paginazione](errors-and-pagination.md)

Tutti gli esempi seguenti mostrano il formato di query `?apiKey=` in cURL e l'intestazione `X-API-Key` in JavaScript e Python; entrambi funzionano su ogni endpoint.

---

## L'oggetto trattativa

```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` è l'id di una delle fasi della tua pipeline: leggili dalle impostazioni della tua pipeline (`GET /users/me/pipeline-settings`). I timestamp sono in formato ISO 8601.

---

## Elenca le trattative

`GET /deals` — restituisce le trattative del tuo account, dalla più recente alla meno recente.

**Parametri di query** (tutti facoltativi): `stage` (un id fase), `contact_id`, `limit` (predefinito 50, massimo 200), `cursor` (dalla `next_cursor` della pagina precedente).

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

**Risposta** (`200`)

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

---

## Ottieni una trattativa

`GET /deals/{dealId}`

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

**Risposta** (`200`)

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

Una trattativa che non esiste, o che appartiene a un altro account, restituisce `404`.

---

## Crea una trattativa

`POST /deals` — `title` e `stage` sono obbligatori; `stage` deve essere uno degli id fase della tua pipeline.

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

**Risposta** (`201`)

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

---

## Aggiorna una trattativa

`PUT /deals/{dealId}` — invia solo i campi che desideri modificare (`title`, `description`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` deve essere un numero.

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

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

---

## Sposta una trattativa in un'altra fase

`POST /deals/{dealId}/move` — corpo `{ "new_stage_id": "stage-3", "new_position": 0 }`. La posizione `0` posiziona la scheda in cima alla colonna.

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

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

---

## Elimina una trattativa

`DELETE /deals/{dealId}` — rimuove la trattativa. **Questa operazione non può essere annullata.**

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

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

---

## Passaggi successivi

- [Pipeline di vendita](../deals/sales-pipeline.md) — come funzionano le fasi, i tag di fase e la bacheca.
- [API Attività](tasks.md) — le attività possono essere collegate a una trattativa con `deal_id`.
- [Automazioni](../automations/automations.md) — i passaggi **Trova trattative** e **Trova trattativa** leggono gli stessi dati all'interno di un flusso di lavoro.