# 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.youraiconnector.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", "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` è l'id di una delle fasi della tua pipeline: leggile con `GET /pipelines` (vedi [Pipeline](#pipelines) di seguito). Gli id delle fasi sono univoci in tutte le tue pipeline, quindi `pipeline_id` deriva dalla fase ed è in sola lettura: `default` è la tua pipeline principale, ed è `null` quando la fase non esiste più. I timestamp sono in formato ISO 8601. Un deal memorizza solo i campi mostrati sopra. Quando ne crei o ne aggiorni uno, qualsiasi altro campo viene rifiutato con un `400` che lo indica, così nulla di ciò che invii viene perso silenziosamente. Mantieni i dati aggiuntivi nei campi personalizzati del contatto collegato. --- ## 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 di fase), `pipeline_id` (solo le trattative su quella pipeline), `contact_id`, `limit` (predefinito 50, massimo 200), `cursor` (dalla `next_cursor` della pagina precedente). **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"] ``` **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.youraiconnector.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.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" }' ``` **Risposta** (`201`) ```json { "success": true, "deal_id": "deal_abc123" } ``` --- ## Aggiorna una trattativa `PUT /deals/{dealId}` — invia solo i campi che desideri modificare (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` deve essere un numero. ```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" }' ``` **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.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 }' ``` **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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Risposta** (`200`): `{ "success": true }` --- ## Pipeline Ogni account ha una pipeline principale (`id: "default"`); puoi aggiungerne fino ad altre nove, ognuna con le proprie fasi. Gli id delle fasi e i tag di attivazione devono essere univoci in tutte le pipeline dell'account e ogni pipeline può contrassegnare una fase come suo esito `won` e una come suo esito `lost`. ### Elenca pipeline `GET /pipelines` — ogni pipeline, prima quella principale, ciascuna con le proprie fasi ordinate per posizione. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Risposta** (`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" } ] } ] } } ``` ### Crea una pipeline `POST /pipelines` — corpo `{ "id"?, "name", "stages"?, "settings"? }`. Lascia `id` vuoto per farne generare uno. Ogni fase accetta gli stessi campi della finestra di dialogo Fasi: `id`, `name`, `color`, `position`, `trigger_tag` facoltativo (un percorso tag, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (una fase della stessa pipeline) e `outcome` (`"won"` o `"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" } ] }' ``` **Risposta** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Un id fase o un tag di attivazione già utilizzato da un'altra pipeline è un `400` che nomina quella pipeline; un id già esistente è un `409`. ### Aggiorna una pipeline `PUT /pipelines/{pipelineId}` — corpo `{ "name"?, "stages"?, "settings"? }`. `stages` sostituisce l'intero elenco, come nella finestra di dialogo Fasi. Usa `default` per la pipeline principale. L'id della pipeline stessa non può essere modificato. ### Elimina una pipeline `DELETE /pipelines/{pipelineId}` — rimuove una pipeline aggiuntiva (quella principale non può essere eliminata). Se ci sono ancora trattative nelle sue fasi, la chiamata risponde `409` con `deal_count`; aggiungi `?delete_deals=true` per eliminare tali trattative insieme alla pipeline. **Questa operazione non può essere annullata.** **Risposta** (`204`). --- ## Passaggi successivi - [Sales Pipeline](../deals/sales-pipeline.md) — come funzionano le fasi, i tag di fase, le diverse pipeline 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.