Skip to main content

​
Quando ocorre

Este evento é disparado sempre que um negócio muda de etapa — seja pelo painel (arrastar no kanban), por outro membro via API (POST /v1/deals/:id/move) ou por uma automação interna.

​
Casos de uso comuns

  • Atualizar o estágio da oportunidade no CRM externo
  • Disparar automações baseadas em etapas específicas (ex: entrou em “Proposta enviada” → gerar documento)
  • Notificar o responsável quando o negócio avançar para uma etapa importante
  • Registrar o tempo que o negócio ficou em cada etapa para análise de pipeline
  • Acionar um follow-up automático quando o negócio estagnar

​
Payload completo

{
  "id": "evt_01jxb3c4d5e6f7g8h9i0j1k2l",
  "event": "deal.stage.changed",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "created_at": "2026-06-11T09:15:00.000Z",
  "data": {
    "id": "664g2h3i4j5k6l7m8n9o0p1q",
    "title": "Proposta Empresa XYZ",
    "value": 500000,
    "currency": "BRL",
    "status": "open",
    "pipeline": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Funil Principal"
    },
    "from_stage": {
      "id": "664e1a2b3c4d5e6f78901230",
      "name": "Novo Lead",
      "order": 0
    },
    "to_stage": {
      "id": "664e1a2b3c4d5e6f78901231",
      "name": "Qualificação",
      "order": 1
    },
    "contact": {
      "id": "664f1a2b3c4d5e6f78901234",
      "name": "João Silva"
    },
    "assigned_to": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Maria Santos"
    },
    "moved_by": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Maria Santos"
    },
    "moved_at": "2026-06-11T09:15:00.000Z"
  }
}

​
Referência de campos

CampoTipoDescrição
data.from_stageobjectEtapa de origem: {id, name, order}
data.to_stageobjectEtapa de destino: {id, name, order}
data.moved_byobject|nullMembro que fez a movimentação: {id, name}
data.moved_atstringTimestamp exato da movimentação
data.pipelineobjectFunil: {id, name}
data.contactobject|nullContato vinculado ao negócio
Se o negócio foi movido para outro funil (além de outra etapa), data.pipeline refletirá o funil de destino.

​
Exemplo de handler

if (event === 'deal.stage.changed') {
  const { from_stage, to_stage, title, id } = data;

  // Sincronizar estágio no CRM externo
  await crm.deals.updateStage(id, {
    stage: to_stage.name,
    previousStage: from_stage.name,
  });

  // Acionar ação específica por etapa
  if (to_stage.name === 'Proposta enviada') {
    await documentService.generateProposal(id);
    await emailService.sendProposalNotification(data.contact?.email);
  }

  if (to_stage.name === 'Negociação') {
    await slack.notify('canal-vendas', {
      text: `🔥 "${title}" entrou em Negociação — ${data.assigned_to?.name}`
    });
  }
}