Cotações
CotacaoService — Web Service SOAP de Cotações
Visão Geral
O CotacaoService é um Web Service SOAP que expõe operações para integração de cotações com sistemas externos. Ele permite criar cotações com seus respectivos itens, listar registros aprovados e notificar o resultado de uma integração ao banco de dados.
URL Base:
{base_url}/api/cotacaoserviceWSDL:
{base_url}/api/cotacaoservice?wsdlEncoding:
UTF-8
Autenticação
Todos os métodos expostos exigem obrigatoriamente o parâmetro de validação token.
Chamadas efetuadas com um token inválido retornam o código numérico
'0'.Chamadas originadas de contas sem permissão de acesso à funcionalidade retornam o código
'35'.
Envio de Parâmetros
IMPORTANTE: Sempre envie todas as chaves mapeadas no envelope SOAP, mesmo que o valor de determinado campo seja vazio (nulo). A omissão de uma chave estrutural pode causar comportamentos inesperados ou falhas na interpretação dos parâmetros pelo servidor.
Métodos
gravaCotacao
Responsável por persistir uma nova cotação com seus itens associados. Se o parâmetro cotacao for populado e corresponder a um registro já existente, o sistema gera automaticamente uma nova versão incremental do documento.
Parâmetros de Entrada
Parâmetro | Tipo | Obrigatório | Descrição |
|
| Sim | Token de autenticação de API. |
|
| Não | Número de uma cotação existente (gera nova versão). Se omitido/vazio, o sistema gera uma nova cotação. |
|
| Sim | Código numérico identificador do emitente. |
|
| Sim | Código numérico identificador da filial. |
|
| Sim | Código numérico identificador do responsável. |
|
| Sim | Código numérico da oportunidade vinculada. Deve existir, estar com status aberto e pertencer ao mesmo emitente. |
|
| Não | Data da cotação em qualquer formato reconhecido pelo PHP (ex.: |
|
| Não | Observações gerais textuais da cotação. |
|
| Condicional | Tipo do desconto: |
|
| Não | Valor numérico do desconto a ser aplicado. |
|
| Sim | Nome literal da tabela de preços. Deve constar na base e estar ativa. |
|
| Sim | Código numérico da forma de pagamento escolhida. |
|
| Sim | Quantidade de parcelas. Deve ser numérico e respeitar o teto permitido pela forma de pagamento. |
|
| Sim | Array estruturado contendo os itens. Mínimo de 1 item. Códigos duplicados são consolidados automaticamente. |
Estrutura de cada item
Campo | Obrigatório | Descrição |
| Sim | Código do item. Deve existir e estar associado à tabela de preços informada. |
| Sim | Quantidade solicitada. Deve ser maior que zero. Aceita frações conforme configuração do item. |
| Sim | Preço unitário praticado. Deve ser numérico e maior que zero. |
| Não | Preço original de tabela antes do desconto. Deve ser numérico. |
| Não | Unidade de medida associada. |
| Não | Percentual de desconto específico para este item. |
| Não | Descrição detalhada ou narrativa adicional do produto/serviço. |
| Não | Observações internas do item. |
Códigos de Retorno
Código | Significado / Causa |
| Token inválido |
| Sucesso — cotação gravada com êxito |
| Emitente inválido: não informado, não numérico ou não encontrado |
| Filial (empresa) inválida: não informada, não numérica ou não encontrada |
| Responsável inválido: não informado ou não numérico |
| Oportunidade inválida: não informada, não numérica ou não encontrada |
| Oportunidade com status diferente de aberto |
| Emitente informado não pertence à oportunidade indicada |
|
|
| Tabela de preços não informada ou não encontrada |
| Tabela de preços inativa |
| Forma de pagamento inválida: não informada, não numérica ou não encontrada |
| Quantidade de parcelas não informada ou não numérica |
| Quantidade de parcelas excede o limite máximo da forma de pagamento |
| Número de cotação informado não é numérico |
| Nenhum item informado no array de itens |
| Um dos itens não possui código informado |
| Código de item não encontrado na tabela de preços informada |
| Quantidade do item inválida: não numérica, zero ou negativa |
| Preço do item inválido: não numérico, zero ou negativo |
| Valor de desconto não numérico |
| Conta sem acesso à funcionalidade |
| Erro interno inesperado |
Exemplos de Comunicação XML
Requisição:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
<SOAP-ENV:Body>
<tns:gravaCotacao>
<token>SEU_TOKEN</token>
<cotacao></cotacao>
<emitente>123</emitente>
<empresa>1</empresa>
<responsavel>45</responsavel>
<oportunidade>789</oportunidade>
<data>2024-01-31</data>
<obs>Observação da cotação</obs>
<tipo_desconto>P</tipo_desconto>
<desconto>10</desconto>
<tab_preco>TABELA PADRÃO</tab_preco>
<forma_pagamento>2</forma_pagamento>
<qtd_parcelas>3</qtd_parcelas>
<moeda></moeda>
<situacao></situacao>
<itens SOAP-ENC:arrayType="tns:CotacaoItem[2]" xsi:type="tns:CotacaoItemArray">
<item xsi:type="tns:CotacaoItem">
<codigo>PROD001</codigo>
<unidade></unidade>
<quantidade>5</quantidade>
<preco_original></preco_original>
<preco>120.00</preco>
<desc_perc></desc_perc>
<narrativa_item></narrativa_item>
<obs_item></obs_item>
</item>
<item xsi:type="tns:CotacaoItem">
<codigo>PROD002</codigo>
<unidade></unidade>
<quantidade>2</quantidade>
<preco_original></preco_original>
<preco>350.50</preco>
<desc_perc></desc_perc>
<narrativa_item></narrativa_item>
<obs_item></obs_item>
</item>
</itens>
</tns:gravaCotacao>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Resposta de Sucesso:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:gravaCotacaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
<return xsi:type="xsd:string">1</return>
</ns1:gravaCotacaoResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
listaCotacao
Realiza a listagem de todas as cotações que possuem status de aprovação sistêmica a partir de uma determinada data/hora de corte fornecida.
Parâmetros de Entrada
Parâmetro | Tipo | Obrigatório | Descrição |
|
| Sim | Token de autenticação de API. |
|
| Não | Data/hora limite de corte (ex.: |
Estrutura do Retorno
O retorno mapeado é composto estritamente por um array indexado contendo duas posições:
Índice | Tipo | Descrição |
|
| Código indicador de erro. O valor |
|
| Array tipado com as cotações encontradas. Retorna |
Códigos de Retorno
Código | Significado |
| Sucesso — O índice |
| Token de autenticação inválido. |
| Nenhuma cotação localizada para o filtro de data especificado. |
| Conta sem acesso habilitado à funcionalidade. |
Exemplos de Comunicação XML
Requisição:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
<SOAP-ENV:Body>
<tns:listaCotacao>
<token>SEU_TOKEN</token>
<dt_aprovacao>2024-01-01 00:00:00</dt_aprovacao>
</tns:listaCotacao>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Resposta de Sucesso:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:listaCotacaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
<mensagem xsi:type="xsd:string"></mensagem>
<return xsi:type="tns:CotacaoArray">
<item xsi:type="tns:Cotacao">
<cotacao>1001</cotacao>
<versao>1</versao>
<emitente>123</emitente>
<empresa>1</empresa>
<nome_emitente>Empresa Exemplo LTDA</nome_emitente>
<responsavel>45</responsavel>
<oportunidade>789</oportunidade>
<processo_venda>Processo A</processo_venda>
<estagio_venda>Proposta</estagio_venda>
<data>2024-01-31</data>
<obs></obs>
<tipo_desconto>P</tipo_desconto>
<desconto>10</desconto>
<valor_total>1107.00</valor_total>
<tab_preco>5</tab_preco>
<forma_pagamento>2</forma_pagamento>
<qtd_parcelas>3</qtd_parcelas>
<moeda>1</moeda>
<situacao>1</situacao>
<itens_cotacao xsi:type="tns:CotacaoItem2Array">
<item xsi:type="tns:CotacaoItem2">
<codigo>PROD001</codigo>
<nome>Produto Exemplo 1</nome>
<unidade>UN</unidade>
<quantidade>5</quantidade>
<preco_original></preco_original>
<preco>120.00</preco>
<preco_total>600.00</preco_total>
<desc_perc></desc_perc>
<narrativa_item></narrativa_item>
<obs_item></obs_item>
</item>
<item xsi:type="tns:CotacaoItem2">
<codigo>PROD002</codigo>
<nome>Produto Exemplo 2</nome>
<unidade>UN</unidade>
<quantidade>2</quantidade>
<preco_original></preco_original>
<preco>350.50</preco>
<preco_total>701.00</preco_total>
<desc_perc></desc_perc>
<narrativa_item></narrativa_item>
<obs_item></obs_item>
</item>
</itens_cotacao>
</item>
</return>
</ns1:listaCotacaoResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
gravaDtIntegracao
Registra no banco de dados o resultado da tentativa de processamento da cotação no ecossistema externo. Se não houver mensagens de erro associadas, a data da integração é persistida no documento. Caso ocorram falhas impeditivas, o sistema armazena a stack de erro no log.
Parâmetros de Entrada
Parâmetro | Tipo | Obrigatório | Descrição |
|
| Sim | Token de autenticação de API. |
|
| Sim | Número de identificação da cotação alvo. |
|
| Sim | Código da versão da cotação a ser atualizada. |
|
| Não | Texto descritivo da falha retornada pelo parceiro. Se vazio, assume-se sucesso e grava o timestamp. |
Códigos de Retorno
Código | Significado / Causa |
| Token inválido |
| Sucesso — Registro da data ou log de erro efetuado com êxito |
| Cotação não localizada com o par Número/Versão fornecido |
| Falha interna ao tentar persistir o estado da data de integração |
| Conta sem acesso habilitado à funcionalidade |
| Erro interno inesperado |
Exemplos de Comunicação XML
Requisição (Cenário de Sucesso da Integração):
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
<SOAP-ENV:Body>
<tns:gravaDtIntegracao>
<token>SEU_TOKEN</token>
<num_cotacao>1001</num_cotacao>
<versao>1</versao>
<mensagem_erro></mensagem_erro>
</tns:gravaDtIntegracao>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Requisição (Cenário com Registro de Log de Erro):
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
<SOAP-ENV:Body>
<tns:gravaDtIntegracao>
<token>SEU_TOKEN</token>
<num_cotacao>1001</num_cotacao>
<versao>1</versao>
<mensagem_erro>Falha ao localizar cliente no ERP: código 123 não encontrado</mensagem_erro>
</tns:gravaDtIntegracao>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Resposta Padrão do Servidor:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:gravaDtIntegracaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
<return xsi:type="xsd:string">1</return>
</ns1:gravaDtIntegracaoResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>