deal.stage.changed - SocialSell API

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

Campo	Tipo	Descrição
`data.from_stage`	object	Etapa de origem: `{id, name, order}`
`data.to_stage`	object	Etapa de destino: `{id, name, order}`
`data.moved_by`	object\|null	Membro que fez a movimentação: `{id, name}`
`data.moved_at`	string	Timestamp exato da movimentação
`data.pipeline`	object	Funil: `{id, name}`
`data.contact`	object\|null	Contato 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}`
    });
  }
}