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

> Disparado quando um negócio é marcado como ganho.

## Quando ocorre

Este evento é disparado quando um membro da equipe marca um negócio como ganho — via painel ou pela API (`POST /v1/deals/:id/won`). É um dos eventos mais importantes para integrações de CRM e analytics de receita.

## Casos de uso comuns

* Atualizar a oportunidade no CRM externo para "Fechada Ganha"
* Gerar e enviar a proposta/contrato final automaticamente
* Criar uma assinatura ou pedido no sistema de billing
* Notificar o time de customer success para onboarding
* Registrar a receita em ferramentas de BI ou analytics
* Disparar um e-mail de boas-vindas para o novo cliente

## Payload completo

```json theme={null}
{
  "id": "evt_01jxc4d5e6f7g8h9i0j1k2l3m",
  "event": "deal.won",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "created_at": "2026-06-15T14:30:00.000Z",
  "data": {
    "id": "664g2h3i4j5k6l7m8n9o0p1q",
    "title": "Proposta Empresa XYZ",
    "value": 500000,
    "currency": "BRL",
    "status": "won",
    "pipeline": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Funil Principal"
    },
    "stage": {
      "id": "664e1a2b3c4d5e6f78901233",
      "name": "Fechamento",
      "order": 3
    },
    "contact": {
      "id": "664f1a2b3c4d5e6f78901234",
      "name": "João Silva",
      "email": "joao@empresa.com.br",
      "phone": "+5511999999999"
    },
    "company": {
      "id": "664b1c2d3e4f5a6789012346",
      "name": "Empresa XYZ"
    },
    "assigned_to": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Maria Santos"
    },
    "won_by": {
      "id": "664a1b2c3d4e5f6789012345",
      "name": "Maria Santos"
    },
    "tags": ["enterprise", "inbound"],
    "close_date": "2026-06-15T00:00:00.000Z",
    "won_at": "2026-06-15T14:30:00.000Z",
    "created_at": "2026-06-10T17:00:00.000Z"
  }
}
```

## Referência de campos

| Campo             | Tipo          | Descrição                                            |
| ----------------- | ------------- | ---------------------------------------------------- |
| `data.status`     | string        | Sempre `won` neste evento                            |
| `data.won_at`     | string        | Timestamp do momento em que foi marcado como ganho   |
| `data.won_by`     | object\|null  | Membro que registrou o ganho: `{id, name}`           |
| `data.value`      | integer\|null | Valor do negócio em centavos                         |
| `data.close_date` | string\|null  | Data de fechamento registrada                        |
| `data.contact`    | object\|null  | Contato vinculado com `id`, `name`, `email`, `phone` |
| `data.company`    | object\|null  | Empresa vinculada: `{id, name}`                      |

## Exemplo de handler

```javascript theme={null}
if (event === 'deal.won') {
  const valueInReais = data.value / 100;

  // Atualizar CRM externo
  await salesforce.opportunities.close(data.id, 'Closed Won');

  // Notificar equipe
  await slack.notify('canal-vendas', {
    text: `🏆 NEGÓCIO GANHO! "${data.title}" — R$ ${valueInReais.toFixed(2)} — por ${data.won_by?.name}`
  });

  // Iniciar onboarding do cliente
  if (data.contact?.email) {
    await customerSuccess.startOnboarding({
      contactEmail: data.contact.email,
      contactName: data.contact.name,
      dealValue: data.value,
      accountManager: data.assigned_to?.name,
    });
  }

  // Registrar receita em analytics
  await analytics.track('deal_won', {
    dealId: data.id,
    value: data.value,
    currency: data.currency,
    pipeline: data.pipeline.name,
    closedBy: data.won_by?.id,
  });
}
```