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

integer

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

string

UUID da pipeline

string

UUID da etapa atual

string

UUID do Lead vinculado

string

UUID do usuário responsável, ou null

number

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

number

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

string

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

string

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

string

Observação livre

string

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

string

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

string

Nome do Lead vinculado (resolvido na leitura)

string

Sobrenome do Lead

string

Empresa do Lead

string

Email do Lead

string

Telefone do Lead

string

URL do avatar do Lead

string

UUID do status do Lead

DealProduct[]

Linhas de produto do negócio

Tag[]

Tags do negócio — reutilizam o mesmo catálogo de tags dos Leads

integer

Quantidade de atividades pendentes

integer

Quantidade de atividades pendentes e atrasadas

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

string

Restringe a uma etapa específica

string

padrão:"recent"

recent (mais novos primeiro) ou oldest

string

padrão:"created"

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

string

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

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:

integer

padrão:"1"

Página desejada

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

string

obrigatório

UUID da pipeline

string

obrigatório

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

string

UUID de um Lead existente

object

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

Mostrar Propriedades de new_lead

string

obrigatório

Nome do lead

string

obrigatório

Telefone do lead

string

Email do lead

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.

string

UUID do usuário responsável

string

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

string

Status a aplicar no Lead vinculado

DealProduct[]

Linhas de produto do negócio

Mostrar Propriedades de uma linha de produto

string

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

string

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

number

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

integer

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

boolean

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

string[]

UUIDs de tags a associar

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

string

Novo responsável

number

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

string

Observação

string

Origem

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

string

obrigatório

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

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

Base de Conhecimento

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