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
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
Fluxo típico
- Obtenha os IDs de apoio: empresas, clientes, modelos, funis e produtos e serviços.
- Crie a oportunidade com
POST /budgets, informandoclient,company,model, a etapa inicial emstatuse, se quiser, os IDs de produtos emitems. - Ajuste as linhas: liste com
GET /budgets/{id}/items, edite quantidade, preço e descrição comPUT /budgets/{id}/items/{itemId}ou tire uma linha do total com.../include. - Avance no funil com
PATCH /budgets/{id}/status. Antes, consulte o formulário da etapa para conhecer os campos e atividades exigidos. - 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. PUTde linha substitui a linha inteira. Envie todos os valores que quer manter, lidos antes emGET /budgets/{id}/items.itemsna criação são IDs, não objetos.POST /budgetsePOST /budgets/{id}/itemsrecebem IDs do cadastro de produtos e serviços.- Importação substitui as linhas. Enviar
itemsem/budgets/importtroca a lista inteira, mesmo combudget_update=0; omitaitemspara preservar as linhas. Usesourceeexternal_idestáveis para não duplicar propostas. - Sem paginação na listagem. Restrinja o volume com
start_date,end_date,pipe,statusestates. - Permissões. Todas as rotas respeitam o acesso do usuário do token; a importação exige permissão administrativa.
