Pipelines y etapas

Descubre los IDs de pipeline y etapa usados al crear y mover leads (además de los motivos de pérdida) y crea, modifica, elimina o instala embudos listos. Lectura = `pipelines:read` · escritura = `pipelines:write`.

Base URLhttps://app.syncro.chat/api/v1AuthX-API-Key: crm_SUA_CHAVE_AQUI

Listar pipelines y etapas

GET/pipelines

Permiso: pipelines:read

Devuelve todos los pipelines de la cuenta con sus etapas (en orden) y la lista de motivos de pérdida.

Solicitud

curl "https://app.syncro.chat/api/v1/pipelines" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "pipelines": [
    {
      "id": 1,
      "name": "Vendas",
      "stages": [
        {
          "id": 5,
          "name": "Prospecção",
          "color": "#FF6B6B",
          "is_won": false,
          "is_lost": false
        },
        {
          "id": 6,
          "name": "Proposta",
          "color": "#4ECDC4",
          "is_won": false,
          "is_lost": false
        },
        {
          "id": 10,
          "name": "Ganho",
          "color": "#95E1D3",
          "is_won": true,
          "is_lost": false
        },
        {
          "id": 11,
          "name": "Perdido",
          "color": "#9CA3AF",
          "is_won": false,
          "is_lost": true
        }
      ]
    }
  ],
  "lost_reasons": [
    {
      "id": 1,
      "name": "Preço alto"
    },
    {
      "id": 3,
      "name": "Escolheu concorrente"
    }
  ]
}

Campos de las etapas

Campo	Descripción
`is_won`	`true` en etapas de ganado (usadas en `PUT /leads/{id}/won`)
`is_lost`	`true` en etapas de pérdida (usadas en `PUT /leads/{id}/lost`)

Los lost_reasons alimentan el parámetro reason_id de PUT /leads/{id}/lost.

Crear y modificar pipelines

Además de listar, puedes crear, modificar, eliminar e instalar embudos listos.

Spec reimportable. GET /pipelines/{id} devuelve {name, color, auto_create_*, stages:[{name, is_won, is_lost, required_tasks:[...]}]} — el mismo objeto que POST/PUT aceptan de vuelta.
La autocaptura nace APAGADA vía API (auto_create_from_whatsapp / auto_create_from_instagram). Actívala explícitamente para que el embudo capture leads de WhatsApp/Instagram.
validate_only: true = dry-run (responde 200 con errors/warnings, sin guardar).
PUT sustituye todo. Las etapas se emparejan por nombre y las tareas por asunto — las que permanecen mantienen el vínculo de los leads; una etapa con leads que elimines es rechazada (stage_has_leads), mueve los leads antes.
Un nombre duplicado en el POST devuelve 422 name_conflict — el POST nunca sobrescribe; usa el PUT para modificar.
Se recomienda incluir una etapa is_won y una is_lost: sin ellas los leads no pueden marcarse como ganados o perdidos (es un aviso, no un error).

Detallar un pipeline

GET/pipelines/1

Permiso: pipelines:read

Devuelve el estado del pipeline más el spec reimportable (el mismo objeto aceptado en POST/PUT).

Solicitud

curl "https://app.syncro.chat/api/v1/pipelines/1" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "data": {
    "id": 1,
    "is_default": true,
    "stage_count": 3,
    "lead_count": 128,
    "spec": {
      "name": "Funil de Vendas",
      "color": "#007DFF",
      "auto_create_from_whatsapp": false,
      "auto_create_from_instagram": false,
      "stages": [
        {
          "name": "Novo",
          "is_won": false,
          "is_lost": false,
          "required_tasks": [
            {
              "subject": "Ligar",
              "task_type": "call",
              "priority": "high"
            }
          ]
        },
        {
          "name": "Ganho",
          "is_won": true,
          "is_lost": false,
          "required_tasks": []
        },
        {
          "name": "Perdido",
          "is_won": false,
          "is_lost": true,
          "required_tasks": []
        }
      ]
    }
  }
}

Crear pipeline

POST/pipelines

Permiso: pipelines:write

Parámetros del body

namestringobligatorio

Nombre del embudo. Si ya existe, devuelve 422 name_conflict

stagesarrayobligatorio

Etapas del embudo, en orden

stages[].namestringobligatorio

Nombre de la etapa (es la clave que usa el PUT para emparejar etapas)

stages[].is_wonbooleanopcional

Marca la etapa de ganado

stages[].is_lostbooleanopcional

Marca la etapa de pérdida

stages[].required_tasksarrayopcional

Tareas obligatorias de la etapa: { subject, task_type, priority } (emparejadas por subject en el PUT)

colorstringopcional

Color del embudo (hex)

auto_create_from_whatsappbooleanopcional

Captura leads de WhatsApp automáticamente. Predeterminado false vía API

auto_create_from_instagrambooleanopcional

Captura leads de Instagram automáticamente. Predeterminado false vía API

validate_onlybooleanopcional

Dry-run: valida y devuelve errors/warnings sin guardar nada

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/pipelines" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Funil de Vendas",
    "stages": [
      {
        "name": "Novo",
        "required_tasks": [
          {
            "subject": "Ligar",
            "task_type": "call",
            "priority": "high"
          }
        ]
      },
      {
        "name": "Ganho",
        "is_won": true
      },
      {
        "name": "Perdido",
        "is_lost": true
      }
    ]
  }'

Respuesta

{
  "success": true,
  "warnings": [],
  "data": {
    "id": 7,
    "is_default": false,
    "stage_count": 3,
    "lead_count": 0,
    "spec": {
      "name": "Funil de Vendas",
      "color": "#007DFF",
      "auto_create_from_whatsapp": false,
      "auto_create_from_instagram": false,
      "stages": [
        {
          "name": "Novo",
          "is_won": false,
          "is_lost": false,
          "required_tasks": [
            {
              "subject": "Ligar",
              "task_type": "call",
              "priority": "high"
            }
          ]
        },
        {
          "name": "Ganho",
          "is_won": true,
          "is_lost": false,
          "required_tasks": []
        },
        {
          "name": "Perdido",
          "is_won": false,
          "is_lost": true,
          "required_tasks": []
        }
      ]
    }
  }
}

Actualizar pipeline

PUT/pipelines/7

Permiso: pipelines:write

Sustituye el spec completo — envía el objeto entero (haz un GET antes).

Las etapas se emparejan por nombre y las tareas por asunto: las que permanecen mantienen el vínculo de los leads.

Eliminar una etapa que aún tiene leads se rechaza con stage_has_leads — mueve los leads antes.

Solicitud

curl -X PUT "https://app.syncro.chat/api/v1/pipelines/7" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Funil de Vendas",
    "stages": [
      {
        "name": "Novo",
        "required_tasks": [
          {
            "subject": "Ligar",
            "task_type": "call",
            "priority": "high"
          }
        ]
      },
      {
        "name": "Proposta"
      },
      {
        "name": "Ganho",
        "is_won": true
      },
      {
        "name": "Perdido",
        "is_lost": true
      }
    ]
  }'

Eliminar pipeline

DELETE/pipelines/7

Permiso: pipelines:write

Solicitud

curl -X DELETE "https://app.syncro.chat/api/v1/pipelines/7" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true
}

Descubrir lo que es válido

GET/pipelines/capabilities

Permiso: pipelines:read

Devuelve los campos aceptados, los enums (task_type, priority), los límites y las reglas de actualización — siempre sincronizado con el servidor. Consúltalo antes de montar un embudo.

Solicitud

curl "https://app.syncro.chat/api/v1/pipelines/capabilities" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Listar modelos listos

GET/pipelines/templates

Permiso: pipelines:read

Lista los modelos de embudo oficiales, organizados por nicho.

Solicitud

curl "https://app.syncro.chat/api/v1/pipelines/templates" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Instalar un modelo

POST/pipelines/templates/funil-de-vendas/install

Permiso: pipelines:write

Instala un modelo en la cuenta. Es idempotente por nombre — instalar dos veces no duplica el embudo.

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/pipelines/templates/funil-de-vendas/install" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"