Importar oportunidade completa

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<object> | 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<object> | 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": "[email protected]", "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.