> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.wbudget.app/w-budget/oportunidades/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.wbudget.app/_mcp/server. # 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 | Campo | O que representa | | -------------------- | -------------------------------------------------------------------------------- | | `state` | Situação comercial: `pending` (em aberto), `earned` (ganha) ou `lost` (perdida). | | `status` | ID da **etapa** do funil em que a oportunidade está. Não confundir com `state`. | | `pipe` | ID do funil. As etapas de cada funil vêm de [Funis](/w-budget/funis). | | `client` / `company` | IDs do cliente e da empresa emissora. | | `agent` | ID do responsável pela oportunidade. | | `budget_value` | Valor 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](/w-budget/produtos-e-servicos). ## Rotas | Método | Rota | Para quê | | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `GET` | `/budgets` | [Listar oportunidades](/w-budget/oportunidades/listar-oportunidades) com filtros de estado, período, funil, etapa, etiqueta e responsável. | | `POST` | `/budgets` | [Criar oportunidade](/w-budget/oportunidades/criar-oportunidade) a partir de cliente, modelo e produtos já cadastrados. | | `POST` | `/budgets/import` | [Importar oportunidade completa](/w-budget/oportunidades/importar-oportunidade-completa), com cliente e itens numa só chamada. | | `GET` | `/budgets/{id}` | [Detalhar oportunidade](/w-budget/oportunidades/detalhar-oportunidade). | | `PATCH` | `/budgets/{id}` | [Atualizar oportunidade](/w-budget/oportunidades/atualizar-oportunidade) (dados comerciais). | | `PATCH` | `/budgets/{id}/status` | [Mover oportunidade de etapa](/w-budget/oportunidades/mover-oportunidade-de-etapa). | | `GET` | `/budgets/{id}/pdf` | [Baixar PDF da oportunidade](/w-budget/oportunidades/baixar-pdf-da-oportunidade). | | `GET` | `/budgets/{id}/items` | [Listar itens da oportunidade](/w-budget/oportunidades/listar-itens-da-oportunidade). | | `POST` | `/budgets/{id}/items` | [Adicionar itens do catálogo](/w-budget/oportunidades/adicionar-itens-do-catalogo). | | `PUT` | `/budgets/{id}/items/{itemId}` | [Editar item da oportunidade](/w-budget/oportunidades/editar-item-da-oportunidade). | | `PUT` | `/budgets/{id}/items/{itemId}/include` | [Incluir ou excluir item do total](/w-budget/oportunidades/incluir-ou-excluir-item-do-total). | | `DELETE` | `/budgets/{id}/items/{itemId}` | [Remover item da oportunidade](/w-budget/oportunidades/remover-item-da-oportunidade). | ## Fluxo típico 1. Obtenha os IDs de apoio: [empresas](/w-budget/empresas), [clientes](/w-budget/clientes), [modelos](/w-budget/modelos), [funis](/w-budget/funis) e [produtos e serviços](/w-budget/produtos-e-servicos). 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](/w-budget/etapas) 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. ## API Docs - [Listar oportunidades](https://developers.wbudget.app/w-budget/oportunidades/listar-oportunidades.md): Oportunidades - [Criar oportunidade](https://developers.wbudget.app/w-budget/oportunidades/criar-oportunidade.md): Oportunidades - [Importar oportunidade completa](https://developers.wbudget.app/w-budget/oportunidades/importar-oportunidade-completa.md): Oportunidades - [Detalhar oportunidade](https://developers.wbudget.app/w-budget/oportunidades/detalhar-oportunidade.md): Oportunidades - [Atualizar oportunidade](https://developers.wbudget.app/w-budget/oportunidades/atualizar-oportunidade.md): Oportunidades - [Mover oportunidade de etapa](https://developers.wbudget.app/w-budget/oportunidades/mover-oportunidade-de-etapa.md): Oportunidades - [Baixar PDF da oportunidade](https://developers.wbudget.app/w-budget/oportunidades/baixar-pdf-da-oportunidade.md): Oportunidades - [Listar itens da oportunidade](https://developers.wbudget.app/w-budget/oportunidades/listar-itens-da-oportunidade.md): Oportunidades - [Adicionar itens do catalogo](https://developers.wbudget.app/w-budget/oportunidades/adicionar-itens-do-catalogo.md): Oportunidades - [Editar item da oportunidade](https://developers.wbudget.app/w-budget/oportunidades/editar-item-da-oportunidade.md): Oportunidades - [Remover item da oportunidade](https://developers.wbudget.app/w-budget/oportunidades/remover-item-da-oportunidade.md): Oportunidades - [Incluir ou excluir item do total](https://developers.wbudget.app/w-budget/oportunidades/incluir-ou-excluir-item-do-total.md): Oportunidades ## OpenAPI Specification - [OpenAPI JSON](https://developers.wbudget.app/openapi.json): raw OpenAPI 3.1 specification for this API, JSON format - [OpenAPI YAML](https://developers.wbudget.app/openapi.yaml): raw OpenAPI 3.1 specification for this API, YAML format