Funis e etapas

É daqui que sai o column_id para mover negócio.

{
  "id": "…", "name": "Ativação", "position": 1, "created_at": "…",
  "columns": [
    { "id": "…", "name": "Entrada", "position": 1, "role": "open", "is_universal": true, "universal_key": "entry" },
    { "id": "…", "name": "Fechado Ganho", "position": 6, "role": "won", "is_universal": true, "universal_key": "won" }
  ]
}
Método Escopo Descrição
GET/api/funnels funnels:read Funis com suas etapas, em ordem
POST/api/funnels funnels:write Cria (201) — já cria as 4 etapas universais
PATCH/api/funnels/{id} funnels:write Edita name, position
DELETE/api/funnels/{id} funnels:write Exclui (204)
POST/api/funnels/{id}/columns funnels:write Cria etapa (201), sempre antes da primeira etapa de fechamento
PATCH/api/funnels/{id}/columns/{columnId} funnels:write Edita name, position
DELETE/api/funnels/{id}/columns/{columnId} funnels:write Exclui (204); os negócios daquela etapa vão para a Entrada

É daqui que sai o column_id para mover negócio.

Use role e universal_key para entender o que cada etapa significa — nunca o name. O dono da conta renomeia as etapas quando quiser, e uma integração amarrada no texto quebra em silêncio no dia da renomeação.

Campo Onde Regras
name funil 1–120
position funil (só edição) inteiro ≥ 1 — a ordem dos demais é recalculada
name etapa 1–60
position etapa (só edição) inteiro ≥ 1

Erros:

Situação Código e motivo
Criar funil além de 100 na conta 409 — "Você já atingiu o número máximo de funis desta conta."
Criar etapa além de 50 no mesmo funil 409 — "Limite de 50 etapas por funil atingido."
Excluir o único funil da conta 409 — toda conta precisa de pelo menos um funil
Excluir funil com negócios 409 — mova os negócios antes
Excluir o funil padrão da conta 409 — torne outro funil o padrão antes
Excluir funil ou etapa que ainda recebe leads ou é usado por outra coisa — link de captação, formulário publicado, formulário de Lead Ads, número de WhatsApp ou planilha ligados direto numa etapa, agente de IA atuando nas etapas, automação ativa ou comando de chat ativo que move negócio pra lá 409 — a mensagem diz quantos são e o que ajustar antes. A exclusão nunca desliga essas coisas em silêncio
Excluir etapa aberta num funil sem etapa de Entrada 409 — não há pra onde mover os negócios dela
Editar posição ou excluir uma etapa universal ou de fechamento 409 — as 4 etapas de fábrica são fixas
Excluir etapa aberta comum 204 — os negócios dela vão para a Entrada

GET/api/funnels devolve tudo sem paginação (next_cursor: null).