--- title: Pipeline & deal description: Pipeline e stage, deal con righe prodotto e termini di pagamento, attività e relativi template — la parte operativa del CRM Audin. --- Il gruppo **Pipeline & deal** è il cuore operativo del CRM: le **pipeline** (con i loro **stage**) definiscono il percorso di una **deal** (opportunità); ogni deal può avere **righe prodotto** e **termini di pagamento**; le **attività** (call, meeting, task) scandiscono il lavoro commerciale. ## Le risorse | Path | Descrizione | |------|-------------| | `/pipelines` | Pipeline (`type` `DEAL` o `LEAD`) con i relativi stage | | `/deals` | Opportunità di vendita | | `/deals/{id}/products` | Righe prodotto di una deal | | `/deals/{id}/payment-terms` | Termini di pagamento di una deal | | `/activities` | Attività commerciali (call, meeting, task) | | `/pipelines/{pipelineId}/activity-templates` | Template di attività agganciati agli stage | Tutte le rotte richiedono l'header `X-API-Key`. Lo schema completo resta sullo [Swagger](https://api.audin.ai/docs/partners). ## Pipeline e stage Una **pipeline** ha un `type` (`DEAL` per le opportunità, `LEAD` per la qualifica dei lead) e contiene una lista ordinata di **stage**. Per aprire una deal ti servono l'`id` della pipeline e l'`id` di uno stage. Filtra le pipeline per tipo con il query parameter `type`: ```bash curl "https://api.audin.ai/pipelines?type=DEAL" \ -H "X-API-Key: $API_KEY" ``` ```js const res = await fetch("https://api.audin.ai/pipelines?type=DEAL", { headers: { "X-API-Key": process.env.AUDIN_API_KEY }, }); const pipelines = await res.json(); const firstStageId = pipelines[0].stages[0].id; ``` Operazioni: `GET /pipelines`, `POST /pipelines`, `GET /pipelines/{id}`, `PUT /pipelines/{id}`, `DELETE /pipelines/{id}`. Gli stage si gestiscono con `POST /pipelines/{id}/stages` e relative rotte di update/reorder. ## Deal Una **deal** è un'opportunità collocata in uno stage di una pipeline. Campi chiave alla creazione: | Campo | Tipo | Obbligatorio | Note | |-------|------|:---:|------| | `title` | string | sì | Titolo dell'opportunità | | `pipelineId` | string | sì | Pipeline di destinazione | | `stageId` | string | no | Stage iniziale (se omesso, primo stage) | | `amount` | number | no | Valore della deal | | `currency` | string | no | Valuta (es. `EUR`) | | `expectedCloseDate` | string | no | Data attesa di chiusura (ISO-8601) | | `primaryContactId` | string | no | Lead di contatto principale | | `companyIds` | string[] | no | Aziende collegate | | `contactIds` | string[] | no | Contatti collegati | | `tags` | string[] | no | Tag | Le deal sincronizzate da un'integrazione (es. **HubSpot**) popolano anche alcuni **campi nativi** dedicati, in sola lettura (altrimenti `null`): | Campo | Tipo | Note | |-------|------|------| | `dealType` | string | Tipologia dell'opportunità dal sistema di origine | | `description` | string | Descrizione | | `priority` | string | Priorità dal sistema di origine | Le proprietà personalizzate e le altre native non mappate sono conservate sotto `customFields.hubspot` (`custom` e `native`), con la stessa convenzione descritta per i [lead](/docs/api-rest/crm). ### Creare una deal L'ordine tipico: recupera la pipeline `DEAL`, prendi il primo stage, crea la deal. ```bash # 1. Recupera pipeline DEAL e primo stage PIPELINES=$(curl -s "https://api.audin.ai/pipelines?type=DEAL" \ -H "X-API-Key: $API_KEY") PIPELINE_ID=$(echo "$PIPELINES" | jq -r '.[0].id') STAGE_ID=$(echo "$PIPELINES" | jq -r '.[0].stages[0].id') # 2. Crea la deal curl -X POST https://api.audin.ai/deals \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"title\": \"Opportunità Acme\", \"pipelineId\": \"$PIPELINE_ID\", \"stageId\": \"$STAGE_ID\", \"amount\": 5000, \"currency\": \"EUR\" }" ``` ```js const headers = { "X-API-Key": process.env.AUDIN_API_KEY, "Content-Type": "application/json", }; // 1. Recupera pipeline DEAL e primo stage const pipelines = await ( await fetch("https://api.audin.ai/pipelines?type=DEAL", { headers }) ).json(); const { id: pipelineId, stages } = pipelines[0]; // 2. Crea la deal const res = await fetch("https://api.audin.ai/deals", { method: "POST", headers, body: JSON.stringify({ title: "Opportunità Acme", pipelineId, stageId: stages[0].id, amount: 5000, currency: "EUR", }), }); const deal = await res.json(); ``` `GET /deals` supporta paginazione (`page`, `pageSize`) e filtri come `pipelineId`, `stageId`, `status`, `tags`, `search`. Una deal si fa avanzare di stage con `PATCH /deals/{id}/stage` e si chiude con `PATCH /deals/{id}/close-won` o `/close-lost`. ## Righe prodotto e termini di pagamento Su una deal puoi aggiungere **righe prodotto** e **termini di pagamento** come sub-risorse: - `GET`/`POST /deals/{id}/products` — righe prodotto (collegate a un `productId` del catalogo o definite inline con `name`, `quantity`, `oneTimePrice`/`recurringPrice`, ecc.). - `GET`/`PUT`/`DELETE /deals/{id}/payment-terms` — termini di pagamento della deal. ```bash curl -X POST "https://api.audin.ai/deals//products" \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productId": "", "quantity": 2, "oneTimePrice": 1500 }' ``` ```js const res = await fetch(`https://api.audin.ai/deals/${dealId}/products`, { method: "POST", headers: { "X-API-Key": process.env.AUDIN_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ productId, quantity: 2, oneTimePrice: 1500 }), }); const dealProduct = await res.json(); ``` I campi delle righe prodotto (prezzi una-tantum vs ricorrenti, `billingPeriod`, sconti) e dei termini di pagamento sono articolati: lo schema esatto è sullo [Swagger](https://api.audin.ai/docs/partners). ## Attività Un'**attività** è un'azione commerciale tracciata (`CALL`, `EMAIL`, `MEETING`, `TASK`, `NOTE`), opzionalmente legata a una deal, a un contatto o a un'azienda. Campi chiave: | Campo | Tipo | Obbligatorio | Note | |-------|------|:---:|------| | `type` | enum | sì | `CALL`, `EMAIL`, `MEETING`, `TASK`, `NOTE` | | `subject` | string | sì | Oggetto dell'attività | | `dueDate` | string | no | Scadenza (ISO-8601) | | `dealId` / `contactId` / `companyId` | string | no | Entità collegata | | `priority` | enum | no | Priorità dell'attività | ```bash curl -X POST https://api.audin.ai/activities \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "CALL", "subject": "Chiamata di follow-up", "dealId": "", "dueDate": "2026-06-15T10:00:00.000Z" }' ``` ```js const res = await fetch("https://api.audin.ai/activities", { method: "POST", headers: { "X-API-Key": process.env.AUDIN_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ type: "CALL", subject: "Chiamata di follow-up", dealId, dueDate: "2026-06-15T10:00:00.000Z", }), }); const activity = await res.json(); ``` `GET /activities` supporta filtri ricchi (`status`, `priority`, `type`, `dealId`, `dueDateFrom`/`dueDateTo`, …). Completa un'attività con `PATCH /activities/{id}/complete`. ### Template di attività I **template di attività** sono agganciati agli stage di una pipeline e servono a creare attività ricorrenti coerenti. Si leggono e gestiscono a partire dalla pipeline: - `GET /pipelines/{pipelineId}/activity-templates` - `GET`/`POST /pipelines/{pipelineId}/stages/{stageId}/activity-templates` - `PUT`/`DELETE /activity-templates/{id}` Schema completo (tutti i campi e parametri): [Swagger](https://api.audin.ai/docs/partners). ## Prossimo passo