Pipelines e etapas

Descubra os IDs de pipeline e etapa usados ao criar e mover leads (além dos motivos de perda) e crie, altere, apague ou instale funis prontos. Leitura = `pipelines:read` · escrita = `pipelines:write`.

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

Listar pipelines e etapas

GET/pipelines

Permissão: pipelines:read

Retorna todos os pipelines da conta com suas etapas (em ordem) e a lista de motivos de perda.

Requisição

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

Resposta

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

Campo	Descrição
`is_won`	`true` em etapas de ganho (usadas em `PUT /leads/{id}/won`)
`is_lost`	`true` em etapas de perda (usadas em `PUT /leads/{id}/lost`)

Os lost_reasons alimentam o parâmetro reason_id de PUT /leads/{id}/lost.

Criar e alterar pipelines

Além de listar, dá para criar, alterar, apagar e instalar funis prontos.

Spec re-importável. GET /pipelines/{id} devolve {name, color, auto_create_*, stages:[{name, is_won, is_lost, required_tasks:[...]}]} — o mesmo objeto que POST/PUT aceitam de volta.
Auto-captura nasce DESLIGADA via API (auto_create_from_whatsapp / auto_create_from_instagram). Ligue explicitamente para o funil capturar leads de WhatsApp/Instagram.
validate_only: true = dry-run (responde 200 com errors/warnings, sem gravar).
PUT substitui tudo. Etapas casadas por nome, tarefas por assunto — as que ficam mantêm o vínculo dos leads; uma etapa com leads que você remover é rejeitada (stage_has_leads), mova os leads antes.
Nome duplicado no POST retorna 422 name_conflict — o POST nunca sobrescreve; use o PUT para alterar.
Recomendado incluir uma etapa is_won e uma is_lost: sem elas os leads não podem ser marcados como ganhos ou perdidos (é um aviso, não um erro).

Detalhar um pipeline

GET/pipelines/1

Permissão: pipelines:read

Devolve o status do pipeline mais o spec re-importável (o mesmo objeto aceito no POST/PUT).

Requisição

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

Resposta

{
  "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": []
        }
      ]
    }
  }
}

Criar pipeline

POST/pipelines

Permissão: pipelines:write

Parâmetros do body

namestringobrigatório

Nome do funil. Se já existir, retorna 422 name_conflict

stagesarrayobrigatório

Etapas do funil, em ordem

stages[].namestringobrigatório

Nome da etapa (é a chave usada pelo PUT para casar etapas)

stages[].is_wonbooleanopcional

Marca a etapa de ganho

stages[].is_lostbooleanopcional

Marca a etapa de perda

stages[].required_tasksarrayopcional

Tarefas obrigatórias da etapa: { subject, task_type, priority } (casadas por subject no PUT)

colorstringopcional

Cor do funil (hex)

auto_create_from_whatsappbooleanopcional

Captura leads de WhatsApp automaticamente. Padrão false via API

auto_create_from_instagrambooleanopcional

Captura leads de Instagram automaticamente. Padrão false via API

validate_onlybooleanopcional

Dry-run: valida e devolve errors/warnings sem gravar nada

Requisição

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
      }
    ]
  }'

Resposta

{
  "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": []
        }
      ]
    }
  }
}

Atualizar pipeline

PUT/pipelines/7

Permissão: pipelines:write

Substitui o spec inteiro — envie o objeto completo (faça um GET antes).

Etapas são casadas por nome e tarefas por assunto: as que permanecem mantêm o vínculo dos leads.

Remover uma etapa que ainda tem leads é rejeitado com stage_has_leads — mova os leads antes.

Requisição

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
      }
    ]
  }'

Excluir pipeline

DELETE/pipelines/7

Permissão: pipelines:write

Requisição

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

Resposta

{
  "success": true
}

Descobrir o que é válido

GET/pipelines/capabilities

Permissão: pipelines:read

Devolve os campos aceitos, os enums (task_type, priority), os limites e as regras de atualização — sempre em sincronia com o servidor. Consulte antes de montar um funil.

Requisição

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

Listar modelos prontos

GET/pipelines/templates

Permissão: pipelines:read

Lista os modelos de funil oficiais, organizados por nicho.

Requisição

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

Instalar um modelo

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

Permissão: pipelines:write

Instala um modelo na conta. É idempotente por nome — instalar duas vezes não duplica o funil.

Requisição

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