API de Serviços (XML)

Apresentação

A API de serviços da plataforma Sankhya se dispõe a fornecer um meio de integração com outros sistemas de forma fácil e independente de tecnologia.

Essa API é baseada em chamadas HTTP/HTTPS do tipo POST e GET, com corpo no formato XML.
Portanto, qualquer sistema que possuir capacidade de realizar uma chamada HTTP/HTTPS convencional poderá fazer uso dos diversos serviços fornecidos pela API.

📘

Informação Importante

As informações nesse artigo tratam exclusivamente de requisições com estruturação em XML. Para requisições com corpo em JSON acesse o artigo API de Serviços.

URL de chamada

A URL de requisição possui sempre o mesmo padrão, independente do serviço a ser utilizado:

https://api.sankhya.com.br/gateway/v1[modulo]/service.sbr?serviceName=[nomedoserviço]

Padrão do envelope XML

Requisição
Como dito anteriormente, todas as chamadas são do tipo POST e possuem um corpo XML com os parâmetros da chamada. Esses parâmetros são específicos por serviço e são envolvidos por um conjunto de elementos que representam um envelope de chamada, como neste exemplo:

<serviceRequest serviceName="[nome.do.serviço]">
  <requestBody>
    <!-- elementos específicos de cada serviço aqui -->
  </requestBody>
</serviceRequest>

O uso da declaração <?xml> é opcional.

Headers HTTP obrigatórios:
Content-type = text/xml;charset=ISO-8859-1
User-Agent = [qualquer valor, desde que não vazio]

Resposta
Todos os serviços retornam uma resposta no formato XML, como neste exemplo:

<?xml version="1.0" encoding="ISO-8859-1"?>
<serviceResponse serviceName="[nome.do.serviço]" status="1">
    <responseBody>
<!-- 
elemento(s) com o conteúdo da resposta, específico para cada serviço 
-->
    </responseBody>
<!-- elemento opcional de alertas e mensagens -->
    <statusMessage>
        <![CDATA[mensagem de erro ou alerta em formato base64]]>
    </statusMessage>
</serviceResponse>

O exemplo acima mostra uma resposta bem sucedida (status = 1), porém existem outros status com significados específicos:

0 = ERROR
A chamada do serviço terminou no servidor com erro. Neste caso o elemento será retornado com a mensagem de erro em formato base 64.

1 = OK
A chamada foi bem sucedida e a resposta está presente em . Alguns serviços não possuem resposta relevante, portanto o elemento pode ser vazio.

2 = INFO
Mesmo significado de OK (1), no entanto o elemento possui mensagem de aviso ou alerta.

3 = TIMEOUT
A sessão com o servidor terminou por tempo de inoperância excedido. Um outro procedimento de login será necessário para usar serviços.

4 = SERVICE_CANCELED
O serviço se deparou com uma situação onde precisa de mais informações para ser executado. Neste caso um elemento também será retornado. O uso deste tipo de recurso está fora do escopo deste documento, portanto, em casos de ocorrência, a Central Sankhya deverá ser consultada.

Requisições em JSON

Confira no link abaixo a documentação da API de integração em JSON

Como tirar dúvidas?

Para tirar dúvidas e compartilhar informações, use a sala API de Integração da comunidade Sankhya Developer.