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
roleeuniversal_keypara entender o que cada etapa significa — nunca oname. 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).