Com o serviço web SOAP (Simple Object Access Protocol), é possível realizar o cadastro, a listagem e a edição de oportunidade 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: oportunidadeservice
Tecnologia: Webservice SOAP
URL WSDL: https://app.procedo.com.br/api/oportunidadeservice?wsdl
Objetivo: Webservice que realiza operações vinculadas a Oportunidade, que é toda possibilidade de negócio futuro encontrada em um cliente ou prospect.
Observação: solicite seu token de segurança para utilizar os métodos do webservice [email protected]
Métodos
Método: listaOportunidade
Descrição: método responsável por retornar uma lista de oportunidades do Procedo.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificado único da empresa para uso do método. |
situação | sim | Int | 0=Retorna todos os registros pendentes de integração
1=Retorna registros pendentes de integração e com situação vencida 2=Retorna registros pendentes de integração e com situação perdida |
Retorno
A tabela abaixo indica os possíveis retornos de erros ou confirmação para o método listaCliente. Esse retorno se está visível no nível 5 do XML.
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 | Situação inválida, somente 0, 1 ou 2 |
9 | Nenhum registro encontrado |
35 | Empresa sem acesso a funcionalidade solicitada |
Exemplo
Exemplo de requisição para obter todas as oportunidades pendentes de integração 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:listaOportunidade> <urn:token>698dc19d489c4e4db73e28a713eab07b</urn:token> <urn:situacao>0</urn:situacao> </urn:listaOportunidade> </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/oportunidadeservice?wsdl"> <SOAP-ENV:Body> <ns1:listaOportunidadeResponse xmlns:ns1="urn:SOAPServerWSDL"> <return xsi:type="xsd:int">1</return> <mensagem xsi:type="xsd:int">OK</mensagem> <return xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:Oportunidade[1]"> <item xsi:type="tns:Oportunidade"> <codigo xsi:type="xsd:string">8</codigo> <nome xsi:type="xsd:string">Projeto abc</nome> <valor xsi:type="xsd:string">9980.00</valor> <data_prevista xsi:type="xsd:string">2017-02-10</data_prevista> <data_gravacao xsi:type="xsd:string">2017-01-29</data_gravacao> <filial xsi:type="xsd:string">Empresa Matriz</filial> <responsavel xsi:type="xsd:string">Ubaldo</responsavel> <nome_cliente xsi:type="xsd:string">Caroline e Breno Financeira Ltda</nome_cliente> <processo_venda xsi:type="xsd:string">Processo de venda padrão</processo_venda> <situacao xsi:type="xsd:string">Ativa</situacao> </item> </return> </ns1:listaOportunidadeResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Uma observação importante é que há um limite de retorno de 50 oportunidades, portanto a integração precisa ser feita de 50 em 50 até que não tenha mais nenhum registro para ser integrado.
Método: gravaCodOportunidade
Descrição: método responsável por atualizar a oportunidade no Procedo após integrá-lo com um sistema ERP. Esse método fará com que o seu registro no Procedo não seja integrado novamente pelo método listaOportunidade.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificado único da empresa para uso do método |
codigo | sim | Int | Código da oportunidade no Procedo |
mensagem | não | String | Informa ao sistema Procedo que não foi possível gravar no sistema externo o cliente correspondente |
Retorno
Código | Retorno |
0 | Token inválido, neste caso é necessário entrar em contato novamente para obter o código de acesso |
1 | Ok, o registro foi inserido ou atualizado |
9 | Oportunidade não encontrado no Procedo |
99 | Erro ao atualizar a oportunidade |
35 | Empresa sem acesso a funcionalidade solicitada |
Exemplo
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:SOAPServerWSDL"> <x:Header/> <x:Body> <urn:gravaCodOportunidade> <urn:token>698dc19d489c4e4db73e28a713eab07b</urn:token> <urn:codigo>8</urn:codigo> <urn:mensagem></urn:mensagem> </urn:gravaCodOportunidade> </x:Body> </x:Envelope>
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:gravaCodOportunidadeResponse xmlns:ns1="urn:SOAPServerWSDL"> <return xsi:type="xsd:string">1</return> <mensagem xsi:type="xsd:string">Registro inserido/atualizado com sucesso</mensagem> </ns1:gravaCodOportunidadeResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Método: encerraOportunidade
Descrição: método responsável por encerrar uma oportunidade. Esse método fará com que a oportunidade no Procedo seja vencida ou perdida. Se for vencida, será obrigatório informar uma cotação e sua versão para que mesma seja vencida também, porém, caso a seja perdida, a observação será obrigatória e também será possível informar o motivo da perda e concorrente que a venceu.
Parâmetro | Obrigatório | Formato | Descrição |
token | sim | String | Identificado único da empresa para uso do método |
oportunidade | sim | Int | Código da oportunidade no Procedo |
situacao | sim | String | 1= Oportunidade Vencida
2= Oportunidade Perdida |
cotacao | parcialmente | Int | Código da cotação que será vencida no Procedo. Esse campo deve ser preenchido caso a oportunidade seja vencida |
versao | parcialmente | Int | Código da versão da cotação no Procedo. Mesma regra que o campo “cotacao“ |
motivoPerda | não | String | Descrição do motivo da perda. Caso o motivo não seja encontrado cadastrado no Procedo, então será cadastrado um novo motivo de perda |
concorrente | não | String | Nome do corrente que venceu a oportunidade.Caso o concorrente não seja encontrado cadastrado no Procedo, então será cadastrado um novo |
observacao | parcialmente | String | Observação de finalização da oportunidade. Somente é obrigatória caso seja perdida |
Ao finalizar uma oportunidade pelo webservice, será criado um histórico oportunidade no Procedo informando que a mesma foi encerrada por esse meio.
Retorno
Código | Retorno |
0 | Token inválido, neste caso é necessário entrar em contato novamente para obter o código de acesso |
1 | Ok, o registro foi inserido ou atualizado |
2 | Situação da oportunidade é inválida, ou seja, é diferente de 1 ou 2 |
3 | O campo de “observacao” não pode ser nulo quando a oportunidade for perdida |
4 | O código da cotação ou a versão da mesma não foi encontrado no Procedo. |
5 | A cotação existe, porém não pertence a oportunidade informada |
6 | Oportunidade não encontrada no Procedo |
7 | Oportunidade já foi encerrada no Procedo. |
8 | Oportunidade encerrada com sucesso, porém ocorreu um erro ao criar o histórico |
99 | Erro inesperado ao encerrar a oportunidade. Entre em contato com o Procedo |
35 | Empresa sem acesso a funcionalidade solicitada |
Exemplo
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:SOAPServerWSDL"> <x:Header/> <x:Body> <urn:encerraOportunidade> <urn:token>1f3f1de7734005f8d2a13f42943881c64355fQA</urn:token> <urn:oportunidade>946</urn:oportunidade> <urn:situacao>2</urn:situacao> <urn:cotacao>2876</urn:cotacao> <urn:versao>2</urn:versao> <urn:motivo_perda>Orçamento com valor elevado</urn:motivo_perda> <urn:concorrente>Concorrente 1</urn:concorrente> <urn:observacao>Concorrente ofereceu orçamento melhor</urn:observacao> </urn:encerraOportunidade> </x:Body> </x:Envelope>
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:encerraOportunidadeResponse xmlns:ns1="urn:SOAPServerWSDL"> <return xsi:type="xsd:string">1</return> <mensagem xsi:type="xsd:string">Oportunidade encerrada com sucesso</mensagem> </ns1:encerraOportunidadeResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>