Visão geral

Endpoints para consultar funis e etapas e movimentar oportunidades (cards) no CRM do iHelp.

Base URL

https://apiv3.ihelpchat.com

Todas as rotas de CRM têm o prefixo /api/v2/crm.

Autenticação

Todos os endpoints exigem um JWT no header Authorization, como no restante da API. Veja Autenticação e Obter token de usuário.

Authorization: Bearer <TOKEN>

Ordem recomendada de uso

Você precisa dos IDs antes de movimentar. O fluxo natural é:

1. GET /crm/funnel - lista os funis, guarde o id do funil desejado
2. GET /crm/funnel/{id}/with-stages - lista as etapas daquele funil, guarde o id da etapa
3. Movimente:
   • Mover card - um card entre etapas do mesmo funil
   • Mover em massa - vários cards de uma vez
   • Trocar de funil - mudar o card de funil
   • Mover por telefone - sem precisar do cardId

Os dois primeiros passos estão em Funis e etapas.

Convenções

• Todos os IDs são inteiros.
• Datas são UTC, formato ISO 8601.
• Não existe exclusão física: registros excluídos ficam com isActive: false.
• Requisições com corpo usam Content-Type: application/json.

Header opcional X-CRM-Connection-Id

Usado pelo app web para que quem originou a ação não receba o próprio evento de tempo real. Integrações externas podem ignorar este header.

Regras de movimentação

• Uma etapa pode exigir campos obrigatórios e/ou tarefas obrigatórias preenchidos antes de o card sair dela. Nesse caso a API responde 409 com a lista de pendências e nada é movido.
• Para confirmar mesmo assim, repita a chamada com force=true (individual) ou "force": true (em massa). O bypass fica registrado no histórico do card.
• force nunca ignora uma etapa de destino excluída ou inativa.
• Cards ganhos, perdidos ou cancelados não podem trocar de funil.
• Mover um card para a etapa em que ele já está é idempotente: responde 200 sem alterar nada. Isso torna o retry seguro.

Erros comuns

Os erros de negócio seguem o formato { "error": "...", "message": "..." }.