Com o serviço web SOAP (Simple Object Access Protocol), é possível cadastrar uma cotação sem a necessidade de estar no sistema. Este recurso é utilizado para fazer integração e/ou automatização de processos de qualquer sistema com o Procedo.
Nome: Cotacaoservice
Tecnologia: Webservice SOAP
URL WSDL: https://app.procedo.com.br/api/cotacaoservice?wsdl
Objetivo: Webservice que realiza operações vinculadas a Cotações, como a integração das cotações do ERP para o Procedo, bem como lista Cotações com a situação de “Aprovado” utilizando como parâmetro a data da aprovação.
Observação: Solicite seu token de segurança para utilizar os métodos do webservice [email protected]
Métodos
Método: gravaCotacao
Descrição: Método responsável por inserir uma cotação no Procedo.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificado único da empresa para uso do método |
cotacao | não | Int | Código numérico da cotação a ser gerada no Procedo. Número já cadastro gera uma nova versão daquela cotação |
emitente | não | Int | Código numérico referente ao cadastro do cliente ou prospect da cotação |
filial | sim | Int | Código numérico referente ao cadastro da filial |
responsavel | sim | Int | Código numérico referente ao responsável pela oportunidade |
oportunidade | sim | Int | Código numérico referente a oportunidade |
data | não | String | Deixar esse campo em branco |
obs | não | String | Observação sobre a cotação |
tipo_desconto | não | String | P (Percentual), V (Valor) ou em branco. Esse é o percentual do cotação e é aplicado sobre o valor final dos itens |
desconto | não | Decimal | Valor do desconto a ser aplicado na cotação de acordo com o tipo. Para percentual, não informar “%”. Formato 99999.99 |
tab_preco | sim | String | Código alfanumérico da tabela de preço a ser utilizada na cotação |
forma_pagamento | sim | Int | Código numérico referente ao cadastro da forma de pagamento a ser utilizada na cotação |
qtd_parcelas | sim | Int | Número inteiro referente à quantidade de parcelas da cotação |
moeda | não | Int | Deixar esse campo em branco |
cond_pagto | sim | Int | Código numérico referente ao cadastro de condição de pagamento a ser utilizado na cotação |
situação | não | String | Deixar esse campo em branco |
Caso o campo “desconto” tenha sido preenchido e o campo “tipo_desconto” não tenha sido informado, o Procedo irá definir por padrão o tipo de desconto “P”.
Para adicionar itens na cotação, use a tag <itens> e, para cada item adicionado, coloque as tags a seguir dentre da tag <item>. Caso tenha dúvida, consulte o exemplo.
Parâmetro | Obrigatório | Formato | Descrição |
item | sim | String | Adiciona um novo item |
codigo | sim | Int | Código alfanumérico referente ao cadastro do item a ser utilizado como item da cotação |
unidade | não | String | Deixar esse campo em branco |
quantidade | sim | Int | Quantidade do item a ser cotado |
preco_original | não | Decimal | Valor original do item |
preco | sim | Decimal | Preço unitário praticado do item. O preço total do item é calculado automaticamente através da regra: Qtde X (Preço Unitário – Desconto em percentual) = Total |
desc_prec | não | Decimal | Deixar esse campo em branco |
narrativa_item | não | String | Narrativa referente ao item. Essa informação se encontra logo abaixo do nome do item |
obs_item | não | String | Observação referente ao item. |
Retorno
Código | Retorno |
0 | Token inválido |
1 | Ok, o registro foi inserido |
2 | O Emitente informado é inválido ou não existe |
3 | A Filial informada é inválida ou não existe |
4 | O Responsável informado é inválido ou não existe |
5 | A Oportunidade informada é inválida ou não existe |
6 | A Oportunidade informada não está “Ativa” |
7 | O Emitente informado na Cotação é diferente da Oportunidade que fora informada |
8 | Tipo do desconto informado é inválido |
9 | Tabela de Preço informado é inválido |
10 | Tabela de Preço informado está inativo |
11 | Forma de Pagamento informado é inválido |
12 | Quantidade de parcelas inválidas |
13 | Condição de Pagamento informado é inválido |
14 | Quantidade de parcelas excede o limite disponível na forma de pagamento |
15 | A cotação informada é inválida |
16 | Não foram encontrados itens na cotação |
17 | Algum item da cotação possuí um código inválido |
18 | [Retorno depreciado] Unidade de Medida informada é inválida |
19 | Verifique se os itens existem na tabelas e condições de pagamento especificado |
20 | Verifique se a quantidade informada em cada item é válido e não é menor ou igual 0 (zero) |
21 | Verifique se os preços atribuído aos itens estão corretos, não poderá ser menor ou igual a 0 (zero) |
22 | Verifique se o percentual de desconto atribuído aos itens estão corretos, não poderá ser maior ou igual a 100% |
23 | Existem itens duplicados na cotação |
25 | Valor do desconto na Cotação é inválido |
26 | [Retorno depreciado]Situação inválida |
35 | Empresa sem acesso a funcionalidade solicitada |
99 | Indefinido. Entre em contato com a Procedo |
Exemplo
Exemplo de requisição para obter as cotações com as informações sendo enviadas através do SoapU:
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:SOAPServerWSDL"> <x:Header/> <x:Body> <urn:gravaCotacao> <urn:token>ser1f432f132de77dd4005fgh8da13f42943881c6455fQ2342</urn:token> <urn:cotacao></urn:cotacao> <urn:emitente>120</urn:emitente> <urn:filial>3</urn:filial> <urn:responsavel>27</urn:responsavel> <urn:oportunidade>1224</urn:oportunidade> <urn:data></urn:data> <urn:obs></urn:obs> <urn:tipo_desconto>P</urn:tipo_desconto> <urn:desconto>30</urn:desconto> <urn:tab_preco>Padrão</urn:tab_preco> <urn:forma_pagamento>1</urn:forma_pagamento> <urn:qtd_parcelas>2</urn:qtd_parcelas> <urn:moeda></urn:moeda> <urn:cond_pagto>1</urn:cond_pagto> <urn:situacao></urn:situacao> <urn:itens soapenc:arrayType="cot:CotacaoItem[]"> <urn:item> <urn:codigo>42</urn:codigo> <urn:unidade></urn:unidade> <urn:quantidade>5</urn:quantidade> <urn:preco_original>10</urn:preco_original> <urn:preco>20</urn:preco> <urn:desc_prec>30</urn:desc_prec> <urn:narrativa_item>A</urn:narrativa_item> <urn:obs_item>B</urn:obs_item> </urn:item> </urn:itens> </urn:gravaCotacao> </x:Body> </x:Envelope>
Agora o exemplo de retorno com sucesso:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 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:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <ns1:gravaCotacaoResponse xmlns:ns1="urn:SOAPServerWSDL"> <return xsi:type="xsd:string">1</return> </ns1:gravaCotacaoResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Método: listaCotacao
Descrição: método responsável por listar cotações e seus respectivos itens que estejam com a situação “Vencida” e que não tenham sido integrados à cotação, porém o cliente/prospect precisa estar integrado. Se o campo “dt_aprovacao” for informado, serão retornadas as cotações dessa data em diante.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificador único da empresa para uso do método |
dt_aprovacao | não | Date | Data da aprovação das cotações, se omitido retorna sempre todas as cotações aprovadas. Caso contrário, retorna todas as cotações a partir da data informada. Formato: AAAA-MM-DD, pode-se adicionar as horas AAAA-MM-DD HH:MM:SS |
Retorno
A tabela abaixo indica os possíveis retornos de erros ou confirmação para o método listaCotação.
Código | Retorno |
0 | Token inválido, neste caso, é necessário entrar em contato novamente para obter o código de acesso |
9 | Nenhum registro encontrado |
35 | Empresa sem acesso a funcionalidade solicitada |
Exemplo
Exemplo de requisição para obter as cotações com as informações sendo enviadas através do SoapUI:
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:SOAPServerWSDL"> <x:Header/> <x:Body> <urn:listaCotacao> <urn:token>1ff1de774005f8dASDFG1a4asd2a5asdasd5hCA</urn:token> <urn:dt_aprovacao>2017-02-09 10:00:25</urn:dt_aprovacao> </urn:listaCotacao> </x:Body> </x:Envelope>
Agora o exemplo de retorno com sucesso
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 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:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://localhost.procedo.com.br/api/cotacaoservice?wsdl"> <SOAP-ENV:Body> <ns1:listaCotacaoResponse xmlns:ns1="urn:SOAPServerWSDL"> <mensagem xsi:nil="true" xsi:type="xsd:string"/> <return xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:Cotacao[1]"> <item xsi:type="tns:Cotacao"> <cotacao xsi:type="xsd:string">10000</cotacao> <versao xsi:type="xsd:string">1</versao> <emitente xsi:type="xsd:string">4792</emitente> <filial xsi:type="xsd:string">1</filial> <nome_emitente xsi:type="xsd:string">Batman</nome_emitente> <responsavel xsi:type="xsd:string">1</responsavel> <oportunidade xsi:type="xsd:string">1383</oportunidade> <processo_venda xsi:type="xsd:string">Processo de venda padrão</processo_venda> <estagio_venda xsi:type="xsd:string">Fechamento</estagio_venda> <data xsi:type="xsd:string">2017-09-04</data> <obs xsi:type="xsd:string"></obs> <tipo_desconto xsi:type="xsd:string"></tipo_desconto> <desconto xsi:type="xsd:string">0.00</desconto> <valor_total xsi:type="xsd:string">0.00</valor_total> <tab_preco xsi:type="xsd:string">Padrão</tab_preco> <forma_pagamento xsi:type="xsd:string">1</forma_pagamento> <qtd_parcelas xsi:type="xsd:string">1</qtd_parcelas> <situacao xsi:type="xsd:string">2</situacao> <cond_pagto xsi:type="xsd:string">75</cond_pagto> <itens_cotacao xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:CotacaoItem2[1]"> <item xsi:type="tns:CotacaoItem2"> <codigo xsi:type="xsd:string">69</codigo> <nome xsi:type="xsd:string">Fantasia do Batman</nome> <quantidade xsi:type="xsd:string">4.00</quantidade> <preco_original xsi:type="xsd:string">0.00</preco_original> <preco xsi:type="xsd:string">15547.00</preco> <preco_total xsi:type="xsd:string">6188.00</preco_total> <desc_perc xsi:type="xsd:string">0</desc_perc> <obs_item xsi:type="xsd:string"></obs_item> </item> </itens_cotacao> </item> </return> </ns1:listaCotacaoResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Método: gravaDtIntegracao
Descrição: método responsável por atualizar a cotação no Procedo após integrá-la com um sistema ERP. Esse método fará com que o registro do cliente no Procedo não seja listado novamente pelo método listaCotação.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificador único da empresa para uso do método |
num_cotacao | sim | String | Número da cotação |
versao | sim | String | Versão da cotação |
mensagem_erro | não | String | A função do campo é informar ao procedo se houve ou não a integração com sucesso. Caso seja preenchido, esta mensagem será gravada no log de integração e enviado aviso aos responsáveis tecnicos. |
A tabela abaixo indica os possíveis retornos de erros ou confirmação para o método.
Código | Retorno |
0 | Token inválido, neste caso é necessário entrar em contato novamente para obter o código de acesso |
1 | OK |
2 | Cotação não encontrada |
3 | Ocorreu um erro ao atualizar a data de integração da cotação |
35 | Empresa sem acesso a funcionalidade solicitada |
Exemplo
Exemplo de requisição para obter as cotações com as informações sendo enviadas através do SoapUI:
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:SOAPServerWSDL"> <x:Header/> <x:Body> <urn:gravaDtIntegracao> <urn:token>1ffdafge56458as1a3fqsafaffawfghcCA</urn:token> <urn:num_cotacao>10000</urn:num_cotacao> <urn:versao>01</urn:versao> <urn:mensagem_erro></urn:mensagem_erro> </urn:gravaDtIntegracao> </x:Body> </x:Envelope>
Agora o exemplo de retorno com sucesso
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 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:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <ns1:gravaDtIntegracaoResponse xmlns:ns1="urn:SOAPServerWSDL"> <return xsi:type="xsd:string">1</return> </ns1:gravaDtIntegracaoResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>