> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialsell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# deal.stage.changed

> Disparado quando um negócio é movido de uma etapa para outra no funil.

## 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

```json theme={null}
{
  "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                |

<Note>
  Se o negócio foi movido para outro funil (além de outra etapa), `data.pipeline` refletirá o funil de destino.
</Note>

## Exemplo de handler

```javascript theme={null}
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}`
    });
  }
}
```