Pipeline & deal
Pipeline e stage, deal con righe prodotto e termini di pagamento, attività e relativi template — la parte operativa del CRM Audin.
Versione Markdown di questa pagina
Scarica o copia il contenuto di questa pagina in formato .md — utile per fornirlo a un agente AI che integra questa specifica feature.
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.
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:
curl "https://api.audin.ai/pipelines?type=DEAL" \
-H "X-API-Key: $API_KEY"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.
Creare una deal
L'ordine tipico: recupera la pipeline DEAL, prendi il primo stage, crea la
deal.
# 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\"
}"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 unproductIddel catalogo o definite inline conname,quantity,oneTimePrice/recurringPrice, ecc.).GET/PUT/DELETE /deals/{id}/payment-terms— termini di pagamento della deal.
curl -X POST "https://api.audin.ai/deals/<deal-id>/products" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"productId": "<product-id>",
"quantity": 2,
"oneTimePrice": 1500
}'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.
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à |
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": "<deal-id>",
"dueDate": "2026-06-15T10:00:00.000Z"
}'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-templatesGET/POST /pipelines/{pipelineId}/stages/{stageId}/activity-templatesPUT/DELETE /activity-templates/{id}
Schema completo (tutti i campi e parametri): Swagger.
Prossimo passo
CRM anagrafiche
Lead, aziende, commenti e tag — crea e leggi le anagrafiche del tuo CRM Audin con l'API REST partner.
Ingestion webhook
Spingi lead, deal e commenti dal tuo sistema verso Audin con un singolo endpoint tipizzato e idempotente — upsert per external_id, ereditando automazioni e assegnazioni.