> 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. # Importar oportunidade completa POST https://wbudget.app/api/v1/api/v1/budgets/import Content-Type: application/json Importa uma proposta completa com cliente e itens em uma chamada. **Autenticação:** Bearer Token da API WBudget. O acesso aos dados respeita as permissões do usuário. Requer permissão administrativa. A combinação source e external\_id identifica a proposta para reimportação; use valores estáveis para evitar duplicatas. A resposta retorna o ID da proposta em data.id e usa HTTP 201 tanto na criação quanto na atualização. Clientes e itens não encontrados podem ser criados. Enviar items substitui toda a lista, incluindo quando budget\_update=0; omita items para preservar as linhas. O valor de budget\_update não torna a operação somente leitura. Os links podem ser nulos quando sua geração estiver desativada. Na reimportação, o conteúdo do modelo pode ser reaplicado: ajuste model\_update conforme sua necessidade. ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | ------------------------------ | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sim | Título da oportunidade. | | `external_id` | string | Não | Identificador da oportunidade no sistema de origem, usado para localizar importações existentes. | | `source` | string | Não | Nome estável da integração de origem; padrão api. O valor reservado internal permite referenciar IDs do WBudget em client.id, items\[].id e external\_id. | | `code` | string | Não | Código comercial. | | `description` | string | Não | Descrição da proposta. | | `note` | string | Não | Observação. | | `state` | string | Não | Estado comercial: pending, earned ou lost. | | `state_date` | string | Não | Data de alteração do estado. | | `status` | integer | Não | ID da etapa. | | `model` | integer | Não | ID do modelo de documento. | | `payment` | integer | Não | ID da condição de pagamento. | | `company_id` | integer | Não | ID da empresa emissora. | | `agent_email` | string | Não | E-mail do responsável. | | `create_date` | string | Não | Data no formato YYYY-MM-DD. | | `expiration_date` | string | Não | Data no formato YYYY-MM-DD. | | `payment_date` | string | Não | Data no formato YYYY-MM-DD. | | `approval_date` | string | Não | Data no formato YYYY-MM-DD. | | `metadata` | object | Não | Campos personalizados da oportunidade. | | `client` | object | Não | Dados do cliente. Quando enviado, client.name é obrigatório. | | `client.id` | string ou integer | Não | Identificador do cliente na origem. Com source=internal, é o ID do cliente WBudget. | | `client.name` | string | Não | Nome; obrigatório quando client é enviado. | | `client.email` | string | Não | E-mail válido. | | `client.phone` | string | Não | Telefone. | | `client.doc` | string | Não | Documento fiscal. | | `client.sponsor` | string | Não | Contato principal. | | `client.address` | object | Não | Endereço: street, neighborhood, number, zipcode, state, city e country. | | `client.metadata` | object | Não | Campos personalizados do cliente. | | `company` | object | Não | Dados da empresa emissora: name, sponsor, doc, phone, email, address e metadata. | | `items` | array\ | Não | Lista completa de linhas desejadas. Na reimportação, enviar items substitui as linhas anteriores; omitir o campo preserva as linhas existentes. Enviar \[] remove as linhas. | | `items[].id` | string | Não | Identificador do item na origem. Com source=internal, envie o ID do produto WBudget como string. | | `items[].budget_item_id` | string ou integer | Não | Identificador da linha de proposta na origem, quando disponível. | | `items[].qty` | number | Não | Quantidade; obrigatória para cada item. | | `items[].name` | string | Não | Dado do produto ou serviço: nome. | | `items[].unit` | string | Não | Dado do produto ou serviço: unidade. | | `items[].description` | string | Não | Dado do produto ou serviço: descrição. | | `items[].type` | string | Não | Dado do produto ou serviço: tipo. | | `items[].value` | number | Não | Preço unitário. | | `items[].discount` | number | Não | Desconto monetário da linha, não percentual. Ex.: qty=2, value=100 e discount=10 resultam em 190 antes de outros ajustes comerciais. | | `items[].metadata` | object | Não | Campos personalizados do item. | | `options` | object | Não | Opções de importação, quando necessárias. | | `options.client_update` | integer | Não | Controle de atualização do cliente: 0 desativa; 1 ativa. Padrão: 1. | | `options.item_update` | integer | Não | Controle de atualização do produto ou serviço: 0 desativa; 1 ativa. Padrão: 0. | | `options.budget_update` | integer | Não | 1 atualiza os dados principais da proposta encontrada (padrão); 0 preserva esses dados. Não bloqueia a substituição dos itens enviados, o tratamento do modelo nem datas e estado enviados. | | `options.model_update` | integer | Não | 1 reaplica o conteúdo do modelo à proposta (padrão); 0 evita reaplicá-lo quando o modelo permanece o mesmo. A troca de modelo também pode renovar o conteúdo do documento. | | `options.auto_link` | integer | Não | 1 gera/atualiza o link público da proposta (padrão); 0 desativa essa geração. Não controla o vínculo do cliente ou dos itens. | | `sign` | string | Não | Identificador da configuração de assinatura. | | `options.company_sponsor_mode` | string | Não | company\_sponsor usa o contato da empresa (padrão); agent usa o nome do responsável pela proposta. | | `variations` | array\ | Não | Ajustes comerciais da proposta, identificados por id ou name. | | `variations[].id` | integer | Não | ID de uma variação já associada à proposta. | | `variations[].name` | string | Não | Nome da variação, obrigatório quando não há id. | | `variations[].type` | string | Não | Tipo de valor da variação; padrão double (valor monetário). | | `variations[].mode` | string | Não | Modo de cálculo da variação; padrão pre. | | `variations[].value` | number | Não | Valor da variação. | ### Exemplo de JSON enviado ```json { "name": "Proposta de implantação", "external_id": "ERP-PROP-1001", "source": "erp-exemplo", "state": "pending", "company_id": 1, "client": { "id": "CLI-101", "name": "Empresa Exemplo", "email": "contato@example.com", "doc": "11222333000181", "address": { "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zipcode": "01000000", "country": "Brasil" } }, "items": [ { "id": "SERV-501", "name": "Implantação", "qty": 1, "value": 1500, "unit": "UN", "discount": 0 } ], "options": { "budget_update": 1, "client_update": 0, "item_update": 0, "model_update": 0, "auto_link": 1 } } ``` ### Resposta HTTP **201**. Os exemplos usam dados fictícios e mostram os campos principais; outros campos podem acompanhar a resposta. Campos sem valor podem ser nulos. Campos principais de `data`: | Campo | Tipo | Descrição | | ------------- | ------- | -------------------------------------- | | `id` | integer | ID criado ou atualizado. | | `external_id` | string | Identificador enviado pela integração. | | `name` | string | Título da proposta. | | `code` | string | Código comercial. | | `link` | string | Link da proposta. | | `short` | string | Link curto. | | `budget_link` | string | Link retornado pela importação. | ```json { "data": { "id": 1001, "name": "Proposta de implantação", "code": "PROP-2026-001", "currency": "BRL", "client_name": "Empresa Exemplo", "external_id": "ERP-PROP-1001", "budget_link": "https://propostas.example.com/p/exemplo", "link": "https://propostas.example.com/proposta-exemplo", "short": "https://propostas.example.com/p/exemplo" } } ``` ### Erros específicos | HTTP | Código | Situação | | ---- | ------------------- | --------------------------- | | 422 | `VALIDATION_FAILED` | The name field is required. | Consulte a introdução da collection para o formato de erros e a configuração das variáveis. Reference: https://developers.wbudget.app/w-budget/oportunidades/importar-oportunidade-completa ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an object. - `name` (string, required) - `external_id` (string, required) - `source` (string, required) - `state` (string, required) - `company_id` (integer, required) - `client` (object, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `doc` (string, required) - `address` (object, required) - `street` (string, required) - `number` (string, required) - `city` (string, required) - `state` (string, required) - `zipcode` (string, required) - `country` (string, required) - `items` (list of object, required) - `id` (string, required) - `name` (string, required) - `qty` (integer, required) - `value` (integer, required) - `unit` (string, required) - `discount` (integer, required) - `options` (object, required) - `budget_update` (integer, required) - `client_update` (integer, required) - `item_update` (integer, required) - `model_update` (integer, required) - `auto_link` (integer, required) ## Response ### 201 Created - `data` (object, required) - `id` (integer, required) - `name` (string, required) - `code` (string, required) - `currency` (string, required) - `client_name` (string, required) - `external_id` (string, required) - `budget_link` (string, required) - `link` (string, required) - `short` (string, required) ## Errors ### 422 Unprocessable Entity Error Unprocessable Entity - `error` (object, required) - `message` (string, required) - `code` (string, required) - `validation_errors` (object, required) - `name` (list of string, required) ## Examples **Request** ```json { "name": "Proposta de implantação", "external_id": "ERP-PROP-1001", "source": "erp-exemplo", "state": "pending", "company_id": 1, "client": { "id": "CLI-101", "name": "Empresa Exemplo", "email": "contato@example.com", "doc": "11222333000181", "address": { "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zipcode": "01000000", "country": "Brasil" } }, "items": [ { "id": "SERV-501", "name": "Implantação", "qty": 1, "value": 1500, "unit": "UN", "discount": 0 } ], "options": { "budget_update": 1, "client_update": 0, "item_update": 0, "model_update": 0, "auto_link": 1 } } ``` **Response** ```json { "data": { "id": 1001, "name": "Proposta de implantação", "code": "PROP-2026-001", "currency": "BRL", "client_name": "Empresa Exemplo", "external_id": "ERP-PROP-1001", "budget_link": "https://propostas.example.com/p/exemplo", "link": "https://propostas.example.com/proposta-exemplo", "short": "https://propostas.example.com/p/exemplo" } } ``` **SDK Code** ```python Oportunidades_Importar oportunidade completa_example import requests url = "https://wbudget.app/api/v1/api/v1/budgets/import" payload = { "name": "Proposta de implantação", "external_id": "ERP-PROP-1001", "source": "erp-exemplo", "state": "pending", "company_id": 1, "client": { "id": "CLI-101", "name": "Empresa Exemplo", "email": "contato@example.com", "doc": "11222333000181", "address": { "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zipcode": "01000000", "country": "Brasil" } }, "items": [ { "id": "SERV-501", "name": "Implantação", "qty": 1, "value": 1500, "unit": "UN", "discount": 0 } ], "options": { "budget_update": 1, "client_update": 0, "item_update": 0, "model_update": 0, "auto_link": 1 } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Oportunidades_Importar oportunidade completa_example const url = 'https://wbudget.app/api/v1/api/v1/budgets/import'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"Proposta de implantação","external_id":"ERP-PROP-1001","source":"erp-exemplo","state":"pending","company_id":1,"client":{"id":"CLI-101","name":"Empresa Exemplo","email":"contato@example.com","doc":"11222333000181","address":{"street":"Rua Exemplo","number":"100","city":"São Paulo","state":"SP","zipcode":"01000000","country":"Brasil"}},"items":[{"id":"SERV-501","name":"Implantação","qty":1,"value":1500,"unit":"UN","discount":0}],"options":{"budget_update":1,"client_update":0,"item_update":0,"model_update":0,"auto_link":1}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Oportunidades_Importar oportunidade completa_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://wbudget.app/api/v1/api/v1/budgets/import" payload := strings.NewReader("{\n \"name\": \"Proposta de implantação\",\n \"external_id\": \"ERP-PROP-1001\",\n \"source\": \"erp-exemplo\",\n \"state\": \"pending\",\n \"company_id\": 1,\n \"client\": {\n \"id\": \"CLI-101\",\n \"name\": \"Empresa Exemplo\",\n \"email\": \"contato@example.com\",\n \"doc\": \"11222333000181\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zipcode\": \"01000000\",\n \"country\": \"Brasil\"\n }\n },\n \"items\": [\n {\n \"id\": \"SERV-501\",\n \"name\": \"Implantação\",\n \"qty\": 1,\n \"value\": 1500,\n \"unit\": \"UN\",\n \"discount\": 0\n }\n ],\n \"options\": {\n \"budget_update\": 1,\n \"client_update\": 0,\n \"item_update\": 0,\n \"model_update\": 0,\n \"auto_link\": 1\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Oportunidades_Importar oportunidade completa_example require 'uri' require 'net/http' url = URI("https://wbudget.app/api/v1/api/v1/budgets/import") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Proposta de implantação\",\n \"external_id\": \"ERP-PROP-1001\",\n \"source\": \"erp-exemplo\",\n \"state\": \"pending\",\n \"company_id\": 1,\n \"client\": {\n \"id\": \"CLI-101\",\n \"name\": \"Empresa Exemplo\",\n \"email\": \"contato@example.com\",\n \"doc\": \"11222333000181\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zipcode\": \"01000000\",\n \"country\": \"Brasil\"\n }\n },\n \"items\": [\n {\n \"id\": \"SERV-501\",\n \"name\": \"Implantação\",\n \"qty\": 1,\n \"value\": 1500,\n \"unit\": \"UN\",\n \"discount\": 0\n }\n ],\n \"options\": {\n \"budget_update\": 1,\n \"client_update\": 0,\n \"item_update\": 0,\n \"model_update\": 0,\n \"auto_link\": 1\n }\n}" response = http.request(request) puts response.read_body ``` ```java Oportunidades_Importar oportunidade completa_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://wbudget.app/api/v1/api/v1/budgets/import") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Proposta de implantação\",\n \"external_id\": \"ERP-PROP-1001\",\n \"source\": \"erp-exemplo\",\n \"state\": \"pending\",\n \"company_id\": 1,\n \"client\": {\n \"id\": \"CLI-101\",\n \"name\": \"Empresa Exemplo\",\n \"email\": \"contato@example.com\",\n \"doc\": \"11222333000181\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zipcode\": \"01000000\",\n \"country\": \"Brasil\"\n }\n },\n \"items\": [\n {\n \"id\": \"SERV-501\",\n \"name\": \"Implantação\",\n \"qty\": 1,\n \"value\": 1500,\n \"unit\": \"UN\",\n \"discount\": 0\n }\n ],\n \"options\": {\n \"budget_update\": 1,\n \"client_update\": 0,\n \"item_update\": 0,\n \"model_update\": 0,\n \"auto_link\": 1\n }\n}") .asString(); ``` ```php Oportunidades_Importar oportunidade completa_example request('POST', 'https://wbudget.app/api/v1/api/v1/budgets/import', [ 'body' => '{ "name": "Proposta de implantação", "external_id": "ERP-PROP-1001", "source": "erp-exemplo", "state": "pending", "company_id": 1, "client": { "id": "CLI-101", "name": "Empresa Exemplo", "email": "contato@example.com", "doc": "11222333000181", "address": { "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zipcode": "01000000", "country": "Brasil" } }, "items": [ { "id": "SERV-501", "name": "Implantação", "qty": 1, "value": 1500, "unit": "UN", "discount": 0 } ], "options": { "budget_update": 1, "client_update": 0, "item_update": 0, "model_update": 0, "auto_link": 1 } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Oportunidades_Importar oportunidade completa_example using RestSharp; var client = new RestClient("https://wbudget.app/api/v1/api/v1/budgets/import"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Proposta de implantação\",\n \"external_id\": \"ERP-PROP-1001\",\n \"source\": \"erp-exemplo\",\n \"state\": \"pending\",\n \"company_id\": 1,\n \"client\": {\n \"id\": \"CLI-101\",\n \"name\": \"Empresa Exemplo\",\n \"email\": \"contato@example.com\",\n \"doc\": \"11222333000181\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zipcode\": \"01000000\",\n \"country\": \"Brasil\"\n }\n },\n \"items\": [\n {\n \"id\": \"SERV-501\",\n \"name\": \"Implantação\",\n \"qty\": 1,\n \"value\": 1500,\n \"unit\": \"UN\",\n \"discount\": 0\n }\n ],\n \"options\": {\n \"budget_update\": 1,\n \"client_update\": 0,\n \"item_update\": 0,\n \"model_update\": 0,\n \"auto_link\": 1\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Oportunidades_Importar oportunidade completa_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Proposta de implantação", "external_id": "ERP-PROP-1001", "source": "erp-exemplo", "state": "pending", "company_id": 1, "client": [ "id": "CLI-101", "name": "Empresa Exemplo", "email": "contato@example.com", "doc": "11222333000181", "address": [ "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zipcode": "01000000", "country": "Brasil" ] ], "items": [ [ "id": "SERV-501", "name": "Implantação", "qty": 1, "value": 1500, "unit": "UN", "discount": 0 ] ], "options": [ "budget_update": 1, "client_update": 0, "item_update": 0, "model_update": 0, "auto_link": 1 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://wbudget.app/api/v1/api/v1/budgets/import")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```