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.

Pedidocurl

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

RespostaJSON

{
  "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

statustexto
Um de open, won ou lost. Qualquer outro valor responde 422.
pipelineIdtexto
Os negócios de um funil.
stageIdtexto
Os negócios de uma etapa.
contactIdtexto
Os negócios de um contato.
pageinteiro
A partir de 1.
limitinteiro
De 1 a 200. Padrão 50.

Pedidocurl

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

RespostaJSON

{
  "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)

contactIdtexto
O contato do negócio. Use este ou phone — um dos dois, nunca os dois.
phonetexto
O telefone do contato. 404 se não houver contato com ele.
titletextoobrigatório
O que está sendo negociado. Até 120 caracteres; acima disso, 422.
valueCentsinteiro
O valor em centavos: R$ 1.250,00 é 125000.
stageIdtexto
A etapa de entrada. Sem ela, o negócio entra na primeira etapa do funil padrão. Etapa que não existe responde 404.
ownerIdtexto
O id de uma pessoa da equipe, como responsável. 422 se não for da equipe.
expectedCloseOndata
A previsão de fechamento, AAAA-MM-DD. Dia que não existe no calendário (30 de fevereiro) responde 422.
conversationIdtexto
A conversa de onde o negócio nasceu. Só é guardada se for daquele contato; de outro, é ignorada.

Pedidocurl

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"
  }'

RespostaJSON

{
  "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"
  }
}

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)

stageIdtexto
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.
statustexto
won ou lost fecha o negócio; open reabre um fechado. Fechar o que já está fechado responde 409.
lostReasontexto
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.
titletexto
Novo título.
valueCentsinteiro
Novo valor, em centavos.
ownerIdtexto ou nulo
Novo responsável; null tira.
expectedCloseOndata ou nulo
Nova previsão; null tira.

Pedidocurl

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" }'

RespostaJSON

{
  "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.