IT Integração de Edição de Ocorrências

1. Objetivo.

O objetivo desta Instrução de Trabalho (IT) é apresentar o modo e como funciona a integração de edição de ocorrências.

2. Modo Proceder.

Utilizamos o SOAP (Protocolo Simples de Acesso a Objetos) para realizar as integrações, facilitando a comunicação com qualquer tipo de aplicação disponível no mercado seja ela Web ou Client Server.

As informações dos serviços disponíveis ficam em https://www.[caminho do seu sistema]/webservices.

Neste endereço, irá encontrar diversos métodos de integrações. Para a Integração de Abertura de Ocorrência, utilizaremos o Método Dados ServiceDesk.

Ao clicar no método poderá verificar todos os parâmetros disponíveis.

No final do documento há um link para a Página de Teste dos Formulários.

A página de testes permite simular um envio à API sem utilização de nenhum software adicional. Ao final do formulário são listados todos os campos do webservice com suas descrições.

Ao gerar o XML de comunicação, é importante não alterar a ordem dos campos, nem tampouco removê-los. Deixe-os com valor nulo ou no máximo como uma string vazia se não for possível manda-los como nulo.

Atente-se à obrigatoriedade de certos campos. Caso tenha dúvida sobre quais informações devem ser passadas, entre em contato com a consultoria da Multidados.

Diferente das demais APIs, esta precisa que os dados sejam encodados no formato de Query String (https://en.wikipedia.org/wiki/Query_string) como é feito na função urlencode do php (https://www.php.net/manual/pt_BR/function.urlencode.php) ou urllib.parse.quote_plus do Python (https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote_plus).

Estes dados devem ser passados dentro de PARAMS em um bloco CDATA.

3. Exemplo de XML de envio.

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:server.Multidados">
<soapenv:Header/>
<soapenv:Body>
<urn:EditOC soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<USUARIO_WS xsi:type="xsd:string">usuario_webservice</USUARIO_WS>
<SENHA_WS xsi:type="xsd:string">senha_webservice</SENHA_WS>
<PARAMS xsi:type="xsd:string"><![CDATA[numero=8559&status=2&campos_adicionais%5Bclientes%5D%5B737%5D=cod_atendido&campos_adicionais%5Bhd_ocorrencias%5D%5B720%5D=texto+livre&responsavel=153&narrativa=Este+é+o+corpo+do+texto+da+narrativa]]></PARAMS>
</urn:EditOC>
</soapenv:Body>
</soapenv:Envelope>

4. Exemplo de Retorno de Sucesso.

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:EditOCResponse xmlns:ns1="urn:server.Multidados">
<return xsi:type="xsd:string">{"idassentamento":9859,"avoidLoss":false,"success":true,"msg":"Ocorr\u00eancia 8559 editada com sucesso","idstatus":"2","sys_msgs":"","_line":3637,"eh_boa_vista":false}</return>
</ns1:EditOCResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

5. Segurança da Informação.

Para utilizar os métodos de nosso webservice é necessário um usuário e senha cadastrados no sistema e a liberação dos IP que farão a comunicação com o serviço. Com isso eliminamos qualquer tipo de comunicação externa que não tenhamos conhecimento prévio. A Liberação dos IPs que utilizam os webservices é realizada pela Equipe Técnica da Multidados.