A IdealSoft disponibiliza uma área de homologação com uma base de testes para clientes em processo de integração realizarem os testes das requisições antes de utilizar o módulo Integrações em produção. Ao requisitar o módulo com o setor comercial, você deverá receber o código da filial de homologação para autenticar o serviço.
Caso deseje seguir o roteiro de homologação, leia a seção Roteiro de Testes.
Todas as requisições que foram processadas e respondidas pelo servidor retornarão o status HTTP 200 OK, independente do sucesso da resposta. Todas as respostas serão retornadas no padrão JSON e terão o seguinte formato:
{
“sucesso”: [bool],
“mensagem”: [string],
“tipo”: [string],
“complementoTipo”: [string],
“statusCode”: [int],
“dados”: [json]
}
Descrição dos campos:
“sucesso”: Esse campo boolean diz que a resposta pode ser considerada como válida para processamento pelo consumidor do serviço. Caso seja falso, o campo “dados” virá sem valor e os campos “mensagem” e “tipo” serão preenchidos com mais informações a respeito do problema.
“mensagem”: Campo string com informações do erro da requisição, caso o campo “sucesso” seja falso. Pode ser uma mensagem simples de validação das regras de negócio do serviço ou uma mensagem de erro retornada pelo servidor (algumas vezes em inglês). Utilizar em conjunto com os campos “tipo”, “complementoTipo” e “statusCode” para fazer o tratamento de erros e sistema de logs.
“tipo”: Campo string com uma informação técnica do tipo do erro para auxiliar o consumidor do serviço a depurar e tratar os problemas. Atualmente os tipos possíveis são:
“complementoTipo”: Campo string, só virá preenchido caso o campo “tipo” seja ambíguo ou complexo a ponto de precisar de um complemento.
“statusCode”: Campo integer, trará o código 200 OK nos casos de sucesso no processamento da requisição. Nos casos de erro, trará um código HTTP relativo ao problema apresentado para que o consumidor do serviço possa apurar seu tratamento de erros (como por exemplo: 401 Não autorizado, para o caso de o token informado seja inválido, etc.).
“dados”: Campo JSON, será o campo onde as informações requisitadas serão apresentadas. Poderá ser um objeto simples ou uma lista, dependendo do tipo da requisição. Para mais informações acerca do tipo de retorno para cada uma das requisições consulte a seção Serviços.
Todas as requisições devem passar uma série de parâmetros no header da requisição:
“Signature”: Para garantir que as informações enviadas na requisição para o módulo estejam concisas e não tenham sofrido modificações durante a requisição até o servidor, é necessário que no header da requisição seja enviado o campo “signature”, que deve ser calculado da seguinte forma:
1 – Concatenar os seguintes campos:
Método HTTP* + Timestamp + Conteúdo BODY* (se houver)
* O método HTTP precisa ser em minúsculo, por exemplo, get, post, put, delet
* O conteúdo do body precisa ser sem espaços no começo e no fim e estar em Base64
2- Encriptar os dados concatenados com o algoritmo HMAC SHA256, utilizando a senha informada nas configurações do módulo.
3- Passar os dados encriptados para Base64.
“CodFilial”: passar o código da filial do Shop Control 9 para que o token foi gerado.
“Authorization”: deve ser passado o token gerado pela requisição Autenticação, no seguinte modelo:
Token [tokenGerado]
“Timestamp”: passar o timestamp utilizado para gerar o campo Signature, para questões de conferência.
A arquitetura da API do módulo Integrações é separada pela requisição de autenticação e as demais requisições. A requisição de autenticação trará o token a ser utilizado em todas as outras requisições. O token deverá ser gerado a cada $HORAS horas para que as validações de data e hora com o servidor e licenciamento do módulo ocorram.
