API delle trattative

Una trattativa è un’opportunità di vendita sulla tua bacheca Sales Pipeline: 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)
Errori e paginazione — vedi Errori e paginazione

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

{
  "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 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

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

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

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)

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

Ottieni una trattativa

GET /deals/{dealId}

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

Risposta (200)

{ "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.

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)

{ "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.

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.

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.

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.

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

Risposta (200):

{
  "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").

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 — come funzionano le fasi, i tag di fase, le diverse pipeline e la bacheca.
API Attività — le attività possono essere collegate a una trattativa con deal_id.
Automazioni — i passaggi Trova trattative e Trova trattativa leggono gli stessi dati all’interno di un flusso di lavoro.

API delle trattative #

L’oggetto trattativa #

Elenca le trattative #

Ottieni una trattativa #

Crea una trattativa #

Aggiorna una trattativa #

Sposta una trattativa in un’altra fase #

Elimina una trattativa #

Pipeline #

Elenca pipeline #

Crea una pipeline #

Aggiorna una pipeline #

Elimina una pipeline #

Passaggi successivi #