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ção1=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>
                    <empresa xsi:type="xsd:string">Empresa Matriz</empresa>
                    <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

O campo “mensagem” só deverá ser preenchido caso ocorra algum erro. Os erros serão gravados em “Log de integração” e os usuários marcados como “Responsável técnico” receberão uma notificação por e-mail sobre o erro. Os registros com erros não sairão mais no método listaOportunidade enquanto estiver no “Log de integração”.

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 Vencida2= 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>

Métodos

Método: listaOportunidade

Retorno

Exemplo

Método: gravaCodOportunidade

Retorno

Exemplo

Método: encerraOportunidade

Retorno

Exemplo

Artigos relacionados

Clicksign: como utilizar a integração de assinatura digital

Webservice de Tabela de preço

Webservice de Contatos

Webservice de Extrato de Serviço

Webservice de Tarefas

Webservice de Cotação de vendas