POST/crm/card/move-by-phone

Mover por telefone

Veja como mover por telefone, com parâmetros e exemplos de requisição e resposta na API do iHelp.

POSThttps://apiv3.ihelpchat.com/api/v2/crm/card/move-by-phone

Endpoint de integração

Move os cards de um contato sem precisar conhecer o cardId. É o caminho mais direto para automações que só têm o número de telefone em mãos.

`POST`

https://apiv3.ihelpchat.com/api/v2/crm/card/move-by-phone

Body (JSON):

{
  "phoneNumber": "5517981259808",
  "funnelId": 12,
  "stageId": 102,
  "forceAll": false,
  "description": "Movido pelo bot de qualificação"
}

Campo	Tipo	Obrigatório	Descrição
`phoneNumber`	string	sim	Telefone do contato, com DDI e DDD
`stageId`	int	sim	Etapa de destino. Precisa ser maior que zero.
`funnelId`	int	não	Restringe a movimentação aos cards deste funil. Sem ele, considera todos os cards do contato.
`forceAll`	bool	não	`true` confirma o movimento mesmo com campos ou tarefas obrigatórias pendentes. Padrão `false`.
`description`	string	não	Texto registrado no histórico de cada card movido

Resposta 200 OK:

Array com uma entrada por card avaliado.

[
  {
    "cardId": 8821,
    "businessId": 3,
    "previousStageId": 101,
    "currentStageId": 102,
    "estimatedValue": 4500.00,
    "moved": true,
    "message": null
  },
  {
    "cardId": 8830,
    "businessId": 3,
    "previousStageId": 103,
    "currentStageId": 103,
    "estimatedValue": 0,
    "moved": false,
    "message": "Campos obrigatórios pendentes"
  }
]

Campo	Significado
`moved`	`true` se o card foi efetivamente movido
`message`	Motivo quando `moved: false`
`previousStageId` / `currentStageId`	Etapa antes e depois. Iguais quando o card não se moveu.

Verifique `moved` em cada item

O status 200 só indica que a chamada foi processada. Cards individuais podem não ter se movido, sempre percorra o array conferindo moved.

Erros

HTTP	Quando
400	`phoneNumber` vazio, `stageId` menor ou igual a zero, ou etapa de destino inativa/excluída
401	Token ausente, inválido ou expirado
409	Conflito de concorrência. Vem com header `Retry-After: 1`, repita a chamada

Contrato de erro diferente

Ao contrário de Mover card, este endpoint responde 400 com a mensagem de erro em texto quando a etapa de destino está inativa, sem o corpo { "error": "stage_inactive" }.