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/cotacaoservice

  • WSDL: {base_url}/api/cotacaoservice?wsdl

  • Encoding: 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

token

string

Sim

Token de autenticação de API.

cotacao

string

Não

Número de uma cotação existente (gera nova versão). Se omitido/vazio, o sistema gera uma nova cotação.

emitente

string

Sim

Código numérico identificador do emitente.

empresa

string

Sim

Código numérico identificador da filial.

responsavel

string

Sim

Código numérico identificador do responsável.

oportunidade

string

Sim

Código numérico da oportunidade vinculada. Deve existir, estar com status aberto e pertencer ao mesmo emitente.

data

string

Não

Data da cotação em qualquer formato reconhecido pelo PHP (ex.: 2024-01-31). Se vazio, adota a data atual.

obs

string

Não

Observações gerais textuais da cotação.

tipo_desconto

string

Condicional

Tipo do desconto: 'P' (percentual) ou 'V' (valor fixo). Obrigatório se desconto for informado. Padrão: 'P'.

desconto

string

Não

Valor numérico do desconto a ser aplicado.

tab_preco

string

Sim

Nome literal da tabela de preços. Deve constar na base e estar ativa.

forma_pagamento

string

Sim

Código numérico da forma de pagamento escolhida.

qtd_parcelas

string

Sim

Quantidade de parcelas. Deve ser numérico e respeitar o teto permitido pela forma de pagamento.

itens

CotacaoItemArray

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

codigo

Sim

Código do item. Deve existir e estar associado à tabela de preços informada.

quantidade

Sim

Quantidade solicitada. Deve ser maior que zero. Aceita frações conforme configuração do item.

preco

Sim

Preço unitário praticado. Deve ser numérico e maior que zero.

preco_original

Não

Preço original de tabela antes do desconto. Deve ser numérico.

unidade

Não

Unidade de medida associada.

desc_perc

Não

Percentual de desconto específico para este item.

narrativa_item

Não

Descrição detalhada ou narrativa adicional do produto/serviço.

obs_item

Não

Observações internas do item.

Códigos de Retorno

Código

Significado / Causa

'0'

Token inválido

'1'

Sucesso — cotação gravada com êxito

'2'

Emitente inválido: não informado, não numérico ou não encontrado

'3'

Filial (empresa) inválida: não informada, não numérica ou não encontrada

'4'

Responsável inválido: não informado ou não numérico

'5'

Oportunidade inválida: não informada, não numérica ou não encontrada

'6'

Oportunidade com status diferente de aberto

'7'

Emitente informado não pertence à oportunidade indicada

'8'

tipo_desconto inválido — deve ser 'V' ou 'P'

'9'

Tabela de preços não informada ou não encontrada

'10'

Tabela de preços inativa

'11'

Forma de pagamento inválida: não informada, não numérica ou não encontrada

'12'

Quantidade de parcelas não informada ou não numérica

'14'

Quantidade de parcelas excede o limite máximo da forma de pagamento

'15'

Número de cotação informado não é numérico

'16'

Nenhum item informado no array de itens

'17'

Um dos itens não possui código informado

'19'

Código de item não encontrado na tabela de preços informada

'20'

Quantidade do item inválida: não numérica, zero ou negativa

'21'

Preço do item inválido: não numérico, zero ou negativo

'25'

Valor de desconto não numérico

'35'

Conta sem acesso à funcionalidade

'99'

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

token

string

Sim

Token de autenticação de API.

dt_aprovacao

string

Não

Data/hora limite de corte (ex.: 2024-01-31 10:00:00). Se omitido, retorna o histórico completo de aprovados.

Estrutura do Retorno

O retorno mapeado é composto estritamente por um array indexado contendo duas posições:

Índice

Tipo

Descrição

[0]

string | null

Código indicador de erro. O valor null explicita uma execução com Sucesso.

[1]

CotacaoArray | null

Array tipado com as cotações encontradas. Retorna null se houver erros.

Códigos de Retorno

Código

Significado

null

Sucesso — O índice [1] conterá a coleção de dados mapeada.

'0'

Token de autenticação inválido.

'9'

Nenhuma cotação localizada para o filtro de data especificado.

'35'

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

token

string

Sim

Token de autenticação de API.

num_cotacao

string

Sim

Número de identificação da cotação alvo.

versao

string

Sim

Código da versão da cotação a ser atualizada.

mensagem_erro

string

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

'0'

Token inválido

'1'

Sucesso — Registro da data ou log de erro efetuado com êxito

'2'

Cotação não localizada com o par Número/Versão fornecido

'3'

Falha interna ao tentar persistir o estado da data de integração

'35'

Conta sem acesso habilitado à funcionalidade

'99'

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>