Skip to navigation

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

CampoTipoObrigatórioDescrição
namestringSimTítulo da oportunidade.
external_idstringNãoIdentificador da oportunidade no sistema de origem, usado para localizar importações existentes.
sourcestringNãoNome 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.
codestringNãoCódigo comercial.
descriptionstringNãoDescrição da proposta.
notestringNãoObservação.
statestringNãoEstado comercial: pending, earned ou lost.
state_datestringNãoData de alteração do estado.
statusintegerNãoID da etapa.
modelintegerNãoID do modelo de documento.
paymentintegerNãoID da condição de pagamento.
company_idintegerNãoID da empresa emissora.
agent_emailstringNãoE-mail do responsável.
create_datestringNãoData no formato YYYY-MM-DD.
expiration_datestringNãoData no formato YYYY-MM-DD.
payment_datestringNãoData no formato YYYY-MM-DD.
approval_datestringNãoData no formato YYYY-MM-DD.
metadataobjectNãoCampos personalizados da oportunidade.
clientobjectNãoDados do cliente. Quando enviado, client.name é obrigatório.
client.idstring ou integerNãoIdentificador do cliente na origem. Com source=internal, é o ID do cliente WBudget.
client.namestringNãoNome; obrigatório quando client é enviado.
client.emailstringNãoE-mail válido.
client.phonestringNãoTelefone.
client.docstringNãoDocumento fiscal.
client.sponsorstringNãoContato principal.
client.addressobjectNãoEndereço: street, neighborhood, number, zipcode, state, city e country.
client.metadataobjectNãoCampos personalizados do cliente.
companyobjectNãoDados da empresa emissora: name, sponsor, doc, phone, email, address e metadata.
itemsarray<object>NãoLista 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[].idstringNãoIdentificador do item na origem. Com source=internal, envie o ID do produto WBudget como string.
items[].budget_item_idstring ou integerNãoIdentificador da linha de proposta na origem, quando disponível.
items[].qtynumberNãoQuantidade; obrigatória para cada item.
items[].namestringNãoDado do produto ou serviço: nome.
items[].unitstringNãoDado do produto ou serviço: unidade.
items[].descriptionstringNãoDado do produto ou serviço: descrição.
items[].typestringNãoDado do produto ou serviço: tipo.
items[].valuenumberNãoPreço unitário.
items[].discountnumberNãoDesconto monetário da linha, não percentual. Ex.: qty=2, value=100 e discount=10 resultam em 190 antes de outros ajustes comerciais.
items[].metadataobjectNãoCampos personalizados do item.
optionsobjectNãoOpções de importação, quando necessárias.
options.client_updateintegerNãoControle de atualização do cliente: 0 desativa; 1 ativa. Padrão: 1.
options.item_updateintegerNãoControle de atualização do produto ou serviço: 0 desativa; 1 ativa. Padrão: 0.
options.budget_updateintegerNão1 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_updateintegerNão1 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_linkintegerNão1 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.
signstringNãoIdentificador da configuração de assinatura.
options.company_sponsor_modestringNãocompany_sponsor usa o contato da empresa (padrão); agent usa o nome do responsável pela proposta.
variationsarray<object>NãoAjustes comerciais da proposta, identificados por id ou name.
variations[].idintegerNãoID de uma variação já associada à proposta.
variations[].namestringNãoNome da variação, obrigatório quando não há id.
variations[].typestringNãoTipo de valor da variação; padrão double (valor monetário).
variations[].modestringNãoModo de cálculo da variação; padrão pre.
variations[].valuenumberNãoValor da variação.

Exemplo de JSON enviado

{
"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:

CampoTipoDescrição
idintegerID criado ou atualizado.
external_idstringIdentificador enviado pela integração.
namestringTítulo da proposta.
codestringCódigo comercial.
linkstringLink da proposta.
shortstringLink curto.
budget_linkstringLink retornado pela importação.
{
"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

HTTPCódigoSituação
422VALIDATION_FAILEDThe name field is required.

Consulte a introdução da collection para o formato de erros e a configuração das variáveis.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
clientobjectOptional
company_iddoubleOptional
external_idstringOptional
itemslist of objectsOptional
namestringOptional
optionsobjectOptional
sourcestringOptional
statestringOptional

Response

201 — Sucesso — exemplo ilustrativo

dataobjectOptional

Errors

422
Unprocessable Entity Error