---
title: "Negócios"
slug: deals
group: "Referência da API"
source: https://linkzap.orion.moe/developers/deals
openapi: https://linkzap.orion.moe/openapi.json
---

# Negócios

O funil do CRM. Um negócio pertence a um contato, mora numa etapa de um funil e está em aberto, ganho ou perdido. O valor é sempre em centavos de real.

## Funis e etapas

### `GET /api/v1/pipelines`
Lista os funis da conta, cada um com as etapas na ordem do quadro. Não é paginada. **Comece por aqui:** é daqui que sai o `stageId` que criar e mover negócio pedem.

Pedido:

```bash
curl https://linkzap.orion.moe/api/v1/pipelines \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

Resposta:

```json
{
  "data": [
    {
      "id": "ppl_10aa...",
      "name": "Vendas",
      "isDefault": true,
      "stages": [
        { "id": "stg_1a01...", "name": "Novo", "position": 0 },
        { "id": "stg_77b0...", "name": "Proposta", "position": 1 }
      ]
    }
  ]
}
```

`isDefault` marca o funil que recebe o negócio criado sem `stageId`. Os nomes das etapas são da equipe e mudam; guarde o `id`.

## Listar negócios

### `GET /api/v1/deals`
Lista os negócios, do mexido mais recentemente para o mais antigo. Paginada. **Uma chave de canal vê todos os negócios da conta** — negócio, como contato, não pertence a canal.

**Parâmetros da URL**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `status` | texto | Um de `open`, `won` ou `lost`. Qualquer outro valor responde 422. |
| `pipelineId` | texto | Os negócios de um funil. |
| `stageId` | texto | Os negócios de uma etapa. |
| `contactId` | texto | Os negócios de um contato. |
| `page` | inteiro | A partir de 1. |
| `limit` | inteiro | De 1 a 200. Padrão 50. |

Pedido:

```bash
curl "https://linkzap.orion.moe/api/v1/deals?status=open&limit=20" \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

Resposta:

```json
{
  "data": [
    {
      "id": "dea_81c2...",
      "title": "Plano anual",
      "valueCents": 299000,
      "status": "open",
      "pipelineId": "ppl_10aa...",
      "stageId": "stg_77b0...",
      "contact": { "id": "ctt_3c81...", "phone": "5592999990000", "name": "Maria Souza" },
      "ownerId": "usr_44e1...",
      "expectedCloseOn": "2026-10-31",
      "lostReason": null,
      "conversationId": null,
      "closedAt": null,
      "createdAt": "2026-10-06T13:00:00.000Z",
      "updatedAt": "2026-10-06T13:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}
```

`valueCents: 299000` é R$ 2.990,00. Zero quer dizer que o negócio não tem valor informado.

## Criar um negócio

### `POST /api/v1/deals`
Cria um negócio para um contato **que já existe** (crie o contato antes, com `POST /contacts`). Responde 201 com o negócio.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `contactId` | texto | — | O contato do negócio. Use este **ou** `phone` — um dos dois, nunca os dois. |
| `phone` | texto | — | O telefone do contato. 404 se não houver contato com ele. |
| `title` | texto | obrigatório | O que está sendo negociado. Até 120 caracteres; acima disso, 422. |
| `valueCents` | inteiro | — | O valor em **centavos**: R$ 1.250,00 é `125000`. |
| `stageId` | texto | — | A etapa de entrada. Sem ela, o negócio entra na primeira etapa do funil padrão. Etapa que não existe responde 404. |
| `ownerId` | texto | — | O id de uma pessoa da equipe, como responsável. 422 se não for da equipe. |
| `expectedCloseOn` | data | — | A previsão de fechamento, `AAAA-MM-DD`. Dia que não existe no calendário (30 de fevereiro) responde 422. |
| `conversationId` | texto | — | A conversa de onde o negócio nasceu. Só é guardada se for daquele contato; de outro, é ignorada. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/v1/deals \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5592999990000",
    "title": "Plano anual",
    "valueCents": 299000,
    "expectedCloseOn": "2026-10-31"
  }'
```

Resposta:

```json
{
  "data": {
    "id": "dea_81c2...",
    "title": "Plano anual",
    "valueCents": 299000,
    "status": "open",
    "pipelineId": "ppl_10aa...",
    "stageId": "stg_77b0...",
    "contact": { "id": "ctt_3c81...", "phone": "5592999990000", "name": "Maria Souza" },
    "ownerId": "usr_44e1...",
    "expectedCloseOn": "2026-10-31",
    "lostReason": null,
    "conversationId": null,
    "closedAt": null,
    "createdAt": "2026-10-06T13:00:00.000Z",
    "updatedAt": "2026-10-06T13:00:00.000Z"
  }
}
```

> [!WARNING]
> **Não é idempotente**
>
> Cada chamada cria um negócio. Se o seu sistema pode repetir o pedido (uma fila que reentrega, um formulário enviado duas vezes), confira antes com `GET /deals?contactId=…&status=open`.

## Mover, ganhar, perder e editar

### `POST /api/v1/deals/{id}`
Muda um negócio. Mande só o que quer mudar; **tudo ou nada** — se um dos campos é recusado, nenhum é gravado. Responde 200 com o negócio como ficou.

**Corpo (JSON)**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `stageId` | texto | Move para esta etapa (o negócio entra no topo dela). Só com o negócio em aberto: mover um fechado responde 409. A etapa em que ele já está não é um movimento: o negócio fica onde estava. |
| `status` | texto | `won` ou `lost` fecha o negócio; `open` reabre um fechado. Fechar o que já está fechado responde 409. |
| `lostReason` | texto | Por que se perdeu, até 80 caracteres. **Obrigatório** com `status: lost` — é o dado que diz por que a conta perde venda. Sem `status: lost` no mesmo pedido, responde 422. |
| `title` | texto | Novo título. |
| `valueCents` | inteiro | Novo valor, em centavos. |
| `ownerId` | texto ou nulo | Novo responsável; `null` tira. |
| `expectedCloseOn` | data ou nulo | Nova previsão; `null` tira. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/v1/deals/dea_81c2... \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "won" }'
```

Resposta:

```json
{
  "data": {
    "id": "dea_81c2...",
    "title": "Plano anual",
    "valueCents": 299000,
    "status": "won",
    "pipelineId": "ppl_10aa...",
    "stageId": "stg_77b0...",
    "contact": { "id": "ctt_3c81...", "phone": "5592999990000", "name": "Maria Souza" },
    "ownerId": "usr_44e1...",
    "expectedCloseOn": "2026-10-31",
    "lostReason": null,
    "conversationId": null,
    "closedAt": "2026-10-07T14:10:00.000Z",
    "createdAt": "2026-10-06T13:00:00.000Z",
    "updatedAt": "2026-10-07T14:10:00.000Z"
  }
}
```

Criar dispara o webhook `deal.created`; mudar de etapa, `deal.stage_changed`; fechar, `deal.won` ou `deal.lost`. Os mesmos eventos saem quando a mudança é feita por uma pessoa no painel, por um fluxo ou pela Aura — então, se o seu sistema escuta e escreve, lembre que a sua própria chamada os provoca.