Negócios

Um negócio (deal) é uma oportunidade dentro de uma etapa. Ele sempre aponta para um Lead real — os dados de contato vêm do Lead, não são copiados.

O objeto Negócio

string

UUID do negócio

number

integer

Número sequencial legível do negócio (ex: 1042)

pipeline_id

string

UUID da pipeline

stage_id

string

UUID da etapa atual

lead_id

string

UUID do Lead vinculado

owner_id

string

UUID do usuário responsável, ou null

value

number

Valor manual do negócio. Só é usado quando o negócio não tem produtos.

total

number

Total calculado: soma de price × qty dos produtos, ou value quando não há produtos

origin

string

Origem do negócio (manual por padrão)

loss_reason

string

Motivo da perda. Presente apenas em negócios perdidos.

note

string

Observação livre

won_at

string

Data em que entrou na etapa de ganho (ISO 8601)

lost_at

string

Data em que entrou na etapa de perda (ISO 8601)

lead_name

string

Nome do Lead vinculado (resolvido na leitura)

lead_surname

string

Sobrenome do Lead

lead_company

string

Empresa do Lead

lead_email

string

Email do Lead

lead_phone

string

Telefone do Lead

lead_avatar

string

URL do avatar do Lead

lead_status_id

string

UUID do status do Lead

products

DealProduct[]

Linhas de produto do negócio

Quadro (board)

GET /backend/pipelines/{id}/board

Retorna os metadados do quadro: a pipeline com suas etapas e, por coluna, a contagem de negócios e o total em dinheiro. Não retorna os negócios em si — use Listar negócios para carregar cada coluna.

Query Parameters

string

Busca pelo número do negócio ou pelo nome/empresa do Lead vinculado

stage_id

string

Restringe a uma etapa específica

sort

string

padrão:"recent"

recent (mais novos primeiro) ou oldest

mode

string

padrão:"created"

Qual data o filtro de período considera: created, won ou lost

period

string

7d, 30d, 1y ou custom. Com custom, informe também from e to.

from

string

Início do período (ISO 8601). Usado apenas com period=custom.

string

Fim do período (ISO 8601). Usado apenas com period=custom.

{
  "pipeline": {
    "id": "bb0e8400-e29b-41d4-a716-446655440000",
    "group_id": "aa0e8400-e29b-41d4-a716-446655440000",
    "name": "Vendas Inbound",
    "description": "Leads vindos do site",
    "position": 0,
    "stages": [
      { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%", "position": 0 }
    ],
    "loss_reasons": ["Sem orçamento"],
    "created_at": "2026-07-16T09:00:00Z"
  },
  "stages": [
    {
      "stage": { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%", "position": 0 },
      "deal_count": 12,
      "total": 48500.00
    }
  ],
  "total_deals": 12,
  "total_amount": 48500.00
}

Listar negócios

GET /backend/pipelines/{id}/deals

Retorna uma página de negócios. O quadro pagina por coluna — passe stage_id para carregar uma etapa de cada vez em vez de toda a pipeline.

Query Parameters

Aceita todos os filtros do quadro, mais:

page

integer

padrão:"1"

Página desejada

limit

integer

padrão:"20"

Itens por página. Valores fora de 1–100 voltam ao padrão de 20.

curl -X GET "https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/deals?stage_id=cc0e8400-e29b-41d4-a716-446655440000&limit=20" \
  -H "Authorization: Bearer sua_chave_aqui"

const params = new URLSearchParams({
  stage_id: 'cc0e8400-e29b-41d4-a716-446655440000',
  limit: '20'
});

const response = await fetch(
  `https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/deals?${params}`,
  { headers: { 'Authorization': 'Bearer sua_chave_aqui' } }
);

{
  "data": [
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "number": 1042,
      "pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "stage_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "lead_id": "550e8400-e29b-41d4-a716-446655440000",
      "owner_id": null,
      "value": 0,
      "total": 4500.00,
      "origin": "manual",
      "note": "",
      "created_at": "2026-07-16T09:30:00Z",
      "updated_at": "2026-07-16T09:30:00Z",
      "lead_name": "João Silva",
      "lead_company": "Empresa XYZ",
      "lead_email": "joao@exemplo.com",
      "lead_phone": "+5511999999999",
      "products": [
        {
          "id": "ee0e8400-e29b-41d4-a716-446655440000",
          "product_id": "ff0e8400-e29b-41d4-a716-446655440000",
          "name": "Plano Premium",
          "price": 1500.00,
          "qty": 3,
          "custom": false,
          "total": 4500.00
        }
      ],
      "tags": [],
      "pending_todos": 1,
      "overdue_todos": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 12,
    "has_next": false,
    "has_prev": false
  }
}

Obter um negócio

GET /backend/pipeline/deals/{id}

Retorna o negócio completo, com produtos, tags e dados do Lead.

Criar negócio

POST /backend/pipeline/deals

Requer a permissão pipeline.deals.create.

Request Body

pipeline_id

string

obrigatório

UUID da pipeline

stage_id

string

obrigatório

UUID da etapa inicial. Precisa pertencer à pipeline informada, senão a resposta é 400.

lead_id

string

UUID de um Lead existente

new_lead

object

Dados para criar um Lead novo junto com o negócio

Mostrar Propriedades de new_lead

name

string

obrigatório

Nome do lead

phone

string

obrigatório

Telefone do lead

string

Email do lead

company

string

Empresa do lead

Informe lead_id ou new_lead. Sem nenhum dos dois, a resposta é 400 — um negócio nunca existe sem um Lead.

owner_id

string

UUID do usuário responsável

loss_reason

string

Motivo da perda. Obrigatório quando stage_id aponta para a etapa de perda.

lead_status_id

string

Status a aplicar no Lead vinculado

products

DealProduct[]

Linhas de produto do negócio

Mostrar Propriedades de uma linha de produto

product_id

string

UUID de um produto do catálogo. Nome e preço são copiados no momento da inclusão.

name

string

Nome da linha avulsa. Obrigatório quando custom é true.

price

number

Preço unitário. Não pode ser negativo.

qty

integer

Quantidade. Valores menores que 1 são tratados como 1.

custom

boolean

true para uma linha avulsa, que existe só neste negócio e não entra no catálogo global

tag_ids

string[]

UUIDs de tags a associar

origin

string

Origem do negócio. Padrão: manual.

curl -X POST "https://api.leavo.ai/backend/pipeline/deals" \
  -H "Authorization: Bearer sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
    "stage_id": "cc0e8400-e29b-41d4-a716-446655440000",
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "products": [
      { "product_id": "ff0e8400-e29b-41d4-a716-446655440000", "qty": 3 },
      { "custom": true, "name": "Implantação", "price": 800.00, "qty": 1 }
    ],
    "tag_ids": ["880e8400-e29b-41d4-a716-446655440000"]
  }'

const response = await fetch('https://api.leavo.ai/backend/pipeline/deals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pipeline_id: 'bb0e8400-e29b-41d4-a716-446655440000',
    stage_id: 'cc0e8400-e29b-41d4-a716-446655440000',
    new_lead: {
      name: 'Maria Souza',
      phone: '+5511988887777',
      company: 'ACME'
    }
  })
});

Retorna 201 Created com o negócio.

Atualizar negócio

PUT /backend/pipeline/deals/{id}

Requer pipeline.deals.edit. Campos omitidos permanecem inalterados.

Request Body

owner_id

string

Novo responsável

value

number

Valor manual. Não pode ser negativo. Só afeta o total quando o negócio não tem produtos.

note

string

Observação

origin

string

Origem

products

DealProduct[]

Quando enviado, substitui a lista inteira de produtos. Envie [] para remover todos.

A etapa não é alterada por este endpoint. Use Mover de etapa.

Mover de etapa

PUT /backend/pipeline/deals/{id}/stage

Move o negócio entre colunas do quadro. Requer pipeline.deals.edit.

Request Body

stage_id

string

obrigatório

UUID da etapa de destino. Precisa pertencer à mesma pipeline do negócio, senão a resposta é 400.

loss_reason

string

Motivo da perda. Obrigatório quando a etapa de destino tem kind: "lost".

Mover para a etapa de perda sem loss_reason retorna 400. Não existe caminho que perca um negócio em silêncio.

Efeitos colaterais da movimentação. Cada movimento sempre limpa won_at e lost_at antes de aplicar o destino, então tirar um negócio de Ganho/Perdido descarta a marcação junto:

Destino	Efeito
`kind: "won"`	Preenche `won_at`; `lost_at` e `loss_reason` ficam nulos
`kind: "lost"`	Preenche `lost_at` e grava `loss_reason`; `won_at` fica nulo
Etapa comum	`won_at`, `lost_at` e `loss_reason` ficam nulos

O motivo pode ser um dos loss_reasons configurados na pipeline ou um texto livre — a opção “Outro” não fica armazenada na lista de motivos.

curl -X PUT "https://api.leavo.ai/backend/pipeline/deals/dd0e8400-e29b-41d4-a716-446655440000/stage" \
  -H "Authorization: Bearer sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "cc3e8400-e29b-41d4-a716-446655440000",
    "loss_reason": "Fechou com concorrente"
  }'

{
  "code": "ERR_INVALID_INPUT",
  "message": "Informe o motivo da perda para marcar o negócio como perdido"
}

Tags do negócio

As tags do negócio reutilizam o mesmo catálogo de tags dos Leads — não há um catálogo separado.

Adicionar tag

POST /backend/pipeline/deals/{id}/tags/{tagID}

Remover tag

DELETE /backend/pipeline/deals/{id}/tags/{tagID}

Ambas exigem pipeline.deals.edit e retornam { "success": true }.

Excluir negócio

DELETE /backend/pipeline/deals/{id}

Requer pipeline.deals.delete.

Exclui o negócio e tudo que pende dele: produtos, tags, atividades, arquivos e histórico. O Lead vinculado não é excluído.

{ "success": true }

Visão Geral

Leads

Status

Tags

Pipeline (CRM)

Webhooks

Campos Personalizados

Cadências

Conversas

Mensagens

Departamentos

Upload de Arquivos

Templates (Meta/Gupshup)

Follow-up

O objeto Negócio

Quadro (board)

Query Parameters

Listar negócios

Query Parameters

Obter um negócio

Criar negócio

Request Body

Atualizar negócio

Request Body

Mover de etapa

Request Body

Tags do negócio

Adicionar tag

Remover tag

Excluir negócio

​O objeto Negócio

​Quadro (board)

​Query Parameters

​Listar negócios

​Query Parameters

​Obter um negócio

​Criar negócio

​Request Body

​Atualizar negócio

​Request Body

​Mover de etapa

​Request Body

​Tags do negócio

​Adicionar tag

​Remover tag

​Excluir negócio

O objeto Negócio

Quadro (board)

Query Parameters

Listar negócios

Query Parameters

Obter um negócio

Criar negócio

Request Body

Atualizar negócio

Request Body

Mover de etapa

Request Body

Tags do negócio

Adicionar tag

Remover tag

Excluir negócio