> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.wbudget.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.wbudget.app/_mcp/server.

# WBudget Api

## Começar

1. Configure `url` com o endereço da sua instalação, sem barra final e sem `/api/v1`. Exemplo: `https://app.example.com/WBud`.
2. Configure `token` com seu token da API **WBudget**. A chave da API do Postman não autentica chamadas ao WBudget.
3. Consulte empresas, clientes, produtos, modelos e funis para obter IDs válidos.
4. Abra uma requisição, substitua os IDs fictícios e envie. Ative em **Params** os filtros opcionais desejados.

Base das requisições: `{{url}}/api/v1`.

## Autenticação e acesso

Todas as requisições desta collection herdam a autenticação Bearer:

`Authorization: Bearer {{token}}`

O acesso depende das permissões do usuário e dos recursos habilitados na conta. Importação de oportunidades e listagem de responsáveis exigem permissão administrativa. Use variáveis locais ou de ambiente para credenciais.

## Requisições e respostas

Envie corpos JSON com `Content-Type: application/json`. As respostas de sucesso usam `{ "data": ... }`: listas retornam arrays, consultas individuais retornam objetos e gravações podem retornar IDs ou o recurso atualizado. O download de PDF retorna `application/pdf`.

Os exemplos são fictícios e ilustram os campos principais, sem representar dados reais de uma conta. Identificadores numéricos devem ser substituídos por IDs válidos. Datas de entrada usam `YYYY-MM-DD` ou `YYYY-MM-DD HH:mm:ss` conforme o campo. Datas de resposta podem conter horário e fuso; preserve o deslocamento informado. Valores monetários são números JSON, sem símbolos de moeda. Campos sem valor podem ser nulos.

Estados comerciais: `pending` (em aberto), `earned` (ganha), `lost` (perdida). A etapa do funil é identificada pelo campo `status`. Atividades usam seus próprios estados, como `open`, `late` e `done`.

## Erros

```json
{
  "error": {
    "message": "Client not found.",
    "code": "CLIENT_NOT_FOUND"
  }
}
```

Use o status HTTP e `error.code` para tratar falhas; o texto de `error.message` pode variar. Validações podem incluir `error.validation_errors` com detalhes por campo.

| HTTP | Significado                                            |
| ---- | ------------------------------------------------------ |
| 200  | Consulta ou alteração concluída.                       |
| 201  | Criação ou importação concluída.                       |
| 400  | Requisição não processada; consulte o código do erro.  |
| 401  | Falha de autenticação ou acesso negado.                |
| 404  | Recurso não encontrado ou indisponível para o usuário. |
| 405  | Método não permitido para a rota.                      |
| 409  | Conflito, como exclusão de cliente com histórico.      |
| 422  | Dados inválidos ou obrigatórios ausentes.              |
| 500  | Falha ao processar a solicitação.                      |
| 502  | Falha ao gerar o PDF.                                  |

## Fluxo de exemplo

Consulte os cadastros → crie ou selecione um cliente → crie uma oportunidade → adicione itens → agende atividades → mova a etapa → obtenha o PDF. Para importar cliente e itens em uma única chamada, use `POST /budgets/import`.