Pular para o conteúdo
POST/funis

Criar funil

funil:escrevermódulo Funilaceita Idempotency-Key

Até 20 funis e 30 etapas por funil. Sem etapas, usa o modelo do segmento. Mande Idempotency-Key para poder repetir com segurança.

POST /funis

curl -X POST "https://chat.forsi.com.br/api/v1/funis" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "nome": "Implantes",
    "etapas": [
      {"nome":"Avaliação","cor":"blue"},
      {"nome":"Orçamento enviado","cor":"amber"},
      {"nome":"Fechado","cor":"green","ganha":true},
      {"nome":"Desistiu","cor":"rose","perdida":true}
    ]
  }'
Resposta 201
{
  "dados": {
    "id": "182aeb59-9ecb-47b2-a745-dfa6f21ea385",
    "nome": "Implantes",
    "posicao": 0,
    "etapas": [{"id":"929692a6-7c6e-4f64-988f-e3a786bb5349"}],
    "criado_em": "2026-10-04T13:05:12.481Z",
    "atualizado_em": "2026-10-04T13:05:12.481Z"
  }
}

Corpo da requisição#

JSON. Mande com Content-Type: application/json.

  • nomestringobrigatório
    • até 60 caracteres
  • etapaslista de objectopcional

    Sem etapas, o funil nasce com o modelo do segmento da organização. Precisa de pelo menos uma etapa que não seja de ganho nem de perda.

    • mín. 1 item
    • até 30 itens
  • etapas[].nomestringobrigatório
    • até 40 caracteres
  • etapas[].cor"slate" | "blue" | "violet" | "amber" | "emerald" | "green" | "rose" | "cyan" | "orange"opcional
    —
  • etapas[].ganhabooleanopcional

    Etapa de ganho: negócio que chega aqui vira ganho.

  • etapas[].perdidabooleanopcional

    Etapa de perda: negócio que chega aqui vira perdido.

Resposta#

201 com {"dados": ...}: Funil.

  • iduuidopcional
    —
  • nomestringopcional
    —
  • posicaointegeropcional
    —
  • etapaslista de Etapaopcional
    —
  • criado_emdata e hora ISO 8601opcional
    —
  • atualizado_emdata e hora ISO 8601opcional
    —

Erros#

Todo erro vem como {"erro": {"codigo", "mensagem"}}. Trate pelo codigo: ele não muda.

Status de erro desta operação
StatusQuando
401Chave ausente ou inválida (resposta igual para qualquer motivo).
403Plano sem API, escopo insuficiente ou https/origem recusados.
409Conflito (repetido, Idempotency-Key com outro corpo).
422Dados inválidos ou regra de negócio (ex.: janela_fechada; conta_restrita = a Meta restringiu a conta por spam: erro traz os campos de RestricaoMeta, como ate, escopo, motivo e retry_after_s).
429Limite de requisições. Veja Retry-After.
Códigos de erro que esta área pode devolver13
  • funil_inexistenteFunil não encontrado.
  • etapa_inexistenteEtapa não encontrada (veja GET /funis).
  • negocio_inexistenteNegócio não encontrado.
  • nota_inexistenteNota não encontrada.
  • etapa_fora_do_funilEssa etapa não pertence ao funil informado.
  • etapa_ganha_e_perdidaUma etapa não pode ser de ganho e de perda ao mesmo tempo.
  • estado_invalidoestado deve ser aberto, ganho ou perdido.
  • valor_invalidoO valor não pode ser negativo.
  • limite_de_funisLimite de 20 funis por organização.
  • limite_de_etapasLimite de 30 etapas por funil.
  • limite_de_notasLimite de 500 notas por negócio.
  • contato_inexistenteContato não encontrado.
  • conversa_inexistenteConversa não encontrada.

Os erros que valem para qualquer rota (chave, limite, JSON) estão em Erros.