Skip to navigation

Overview

Uma oportunidade é a proposta comercial do WBudget: pertence a um cliente, é emitida por uma empresa, percorre as etapas de um funil e carrega linhas de produtos ou serviços que formam o valor total. Estas rotas criam, consultam, atualizam e movem oportunidades, editam suas linhas e geram o PDF.

Conceitos

CampoO que representa
stateSituação comercial: pending (em aberto), earned (ganha) ou lost (perdida).
statusID da etapa do funil em que a oportunidade está. Não confundir com state.
pipeID do funil. As etapas de cada funil vêm de Funis.
client / companyIDs do cliente e da empresa emissora.
agentID do responsável pela oportunidade.
budget_valueValor comercial da proposta.

Nas linhas de item há dois identificadores diferentes: itemId é a linha dentro da oportunidade, usada para editar, remover ou excluir do total; item é o produto ou serviço do cadastro, obtido em Produtos e serviços.

Rotas

MétodoRotaPara quê
GET/budgetsListar oportunidades com filtros de estado, período, funil, etapa, etiqueta e responsável.
POST/budgetsCriar oportunidade a partir de cliente, modelo e produtos já cadastrados.
POST/budgets/importImportar oportunidade completa, com cliente e itens numa só chamada.
GET/budgets/{id}Detalhar oportunidade.
PATCH/budgets/{id}Atualizar oportunidade (dados comerciais).
PATCH/budgets/{id}/statusMover oportunidade de etapa.
GET/budgets/{id}/pdfBaixar PDF da oportunidade.
GET/budgets/{id}/itemsListar itens da oportunidade.
POST/budgets/{id}/itemsAdicionar itens do catálogo.
PUT/budgets/{id}/items/{itemId}Editar item da oportunidade.
PUT/budgets/{id}/items/{itemId}/includeIncluir ou excluir item do total.
DELETE/budgets/{id}/items/{itemId}Remover item da oportunidade.

Fluxo típico

  1. Obtenha os IDs de apoio: empresas, clientes, modelos, funis e produtos e serviços.
  2. Crie a oportunidade com POST /budgets, informando client, company, model, a etapa inicial em status e, se quiser, os IDs de produtos em items.
  3. Ajuste as linhas: liste com GET /budgets/{id}/items, edite quantidade, preço e descrição com PUT /budgets/{id}/items/{itemId} ou tire uma linha do total com .../include.
  4. Avance no funil com PATCH /budgets/{id}/status. Antes, consulte o formulário da etapa para conhecer os campos e atividades exigidos.
  5. Gere o documento com GET /budgets/{id}/pdf.

Vindo de outro sistema, com cliente e itens prontos? Use POST /budgets/import: ele cria ou atualiza a proposta numa só chamada e reconhece a reimportação pela combinação source + external_id.

Cuidados

  • Etapa só muda por /status. PATCH /budgets/{id} não altera a etapa; a movimentação respeita a sequência permitida, aprovações e atividades obrigatórias.
  • PUT de linha substitui a linha inteira. Envie todos os valores que quer manter, lidos antes em GET /budgets/{id}/items.
  • items na criação são IDs, não objetos. POST /budgets e POST /budgets/{id}/items recebem IDs do cadastro de produtos e serviços.
  • Importação substitui as linhas. Enviar items em /budgets/import troca a lista inteira, mesmo com budget_update=0; omita items para preservar as linhas. Use source e external_id estáveis para não duplicar propostas.
  • Sem paginação na listagem. Restrinja o volume com start_date, end_date, pipe, status e states.
  • Permissões. Todas as rotas respeitam o acesso do usuário do token; a importação exige permissão administrativa.