Introdução
...
Para garantir a segurança na troca de mensagens entre fornecedor e o iDrake Service, existem alguns procedimentos de de segurança que precisam ser seguidos. Há duas opções.
- Usar par de chaves de criptografia para assinar as mensagens.
- Usar Bearer Token no cabeçalho HTTP das requisições para a API
Sobre os 2 meios acima é uma questão de escolher entre um ou outro. Vale lembrar que o 1º é o modo mais antigo e o 2º foi implementado mais recentemente.
1. Usar par de chaves de criptografia para assinar as mensagens.
Obtenção do ID e da chave privada do fornecedor
Para obter o ID e a chave privada do fornecedor, basta entrar em contato com a Sapiensia informando um e-mail de um responsável. Este e-mail receberá uma mensagem explicando o passo-a-passo para a geração do ID e da chave privada.
...
Exemplo:
POST |
x-Drake-SenderId:12 |
user-agent:Drake.Integration.Client 1.0 |
date:Wed, 29 Jan 2014 22:06:51 GMT |
content-type:application/json |
[{"Id":0,"ClientGuid":"b3c671cb-12ae-4ec3-9524-4928a8b86442","SenderId":12,"RecipientId":15,"Type":2,"DrakeId":4825709,"Details":"Não é permitido mais de um participante em solicitações Rodoviárias."}] |
...
public static string SignData(string message, string privateKey) |
{ |
//// The array to store the signed message in bytes |
byte[] signedBytes; |
using (var rsa = new RSACryptoServiceProvider()) |
{ |
rsa.ImportCspBlob(Convert.FromBase64String(privateKey)); |
//// Write the message to a byte array using UTF8 as the encoding. |
var encoder = new UTF8Encoding(); |
byte[] originalData = encoder.GetBytes(message); |
try |
{ |
//// Sign the data, using SHA512 as the hashing algorithm |
signedBytes = rsa.SignData(originalData, CryptoConfig.MapNameToOID("SHA512")); |
} |
catch (CryptographicException e) |
{ |
return null; |
} |
finally |
{ |
//// Set the keycontainer to be cleared when rsa is garbage collected. |
rsa.PersistKeyInCsp = false; |
} |
} |
//// Convert the a base64 string before returning |
return Convert.ToBase64String(signedBytes); |
} |
...
Após gerar a assinatura da mensagem, basta adicioná-la no cabeçalho da requisição HTTP utilizando a chave x-Drake-Signature.
...
2. Usar Bearer Token no cabeçalho HTTP das requisições para a API
Esta é uma maneira mais conhecida e mais fácil de implementar.
Da mesma maneira que o método 1, para obter o Bearer Tolean, basta entrar em contato com a Sapiensia informando um e-mail de um responsável. Este e-mail receberá uma mensagem explicando o passo-a-passo para a geração do Bearer Token.
Atenção: O Bearer Token deve ser mantido sob sigilo e deverá ser usada pelo fornecedor para autenticar todas as requisições com a API.
Tendo como exemplo fitício o seguinte Bearer Token jzBGCZUJpWNpO7srW/FhpZuZvYo0ZUtIWE1yVUhrTHBtSy9jenpPVWIrN7uqyw62OWJRU1dwRWZvY2dXaEV6TTZ6WXRVa1dlV3RrclFrRXpTSFYrAEVudGl0eUlkNNbNs7==
Uma requisição através do aplicativo Postman seria feita dessa maneira.
Link da base de homologação: https://logistic-integrator-tst.drake.bz/MessageService/
Link da base de produção: https://i.drake.bz/MessageService/
...
Operações
Ler todas as mensagens disponíveis
...
Para obter as mensagens disponíveis, basta enviar uma requisição do tipo POST para /Receive, informando o ID do fornecedor (RecipientId) e o tipo de mensagem (Type 12 = obter mensagens disponíveis). A seguir um exemplo:
POST: /Receive |
[{ |
"RecipientId" : 123, |
"Type" : 12 |
}] |
Como resposta a esta requisição, serão retornadas todas as mensagens disponíveis na caixa de saída do fornecedor. A seguir os diferentes tipos que podem ser retornados:
...
Tipo | Estrutura | Descrição |
| Solicitação de serviço (Type = 0) | | Representa uma solicitação de serviço enviada pelo cliente. Quando uma mensagem desta for recebida, significa que o cliente está solicitando um determinado serviço ao fornecedor. Este serviço pode ser uma hospedagem, um carro, uma passagem aérea etc. |
| Solicitação de alteração de serviço (Type = 7) | | Representa uma solicitação de alteração de serviço enviada pelo cliente. Quando uma mensagem desta for recebida, significa que o cliente gostaria de solicitar a alteração de algum serviço requisitado anteriormente. Diversos tipos de alterações podem ser feitas, como:
|
| Solicitação de cancelamento de serviço (Type = 3) | | Representa uma solicitação de cancelamento de um serviço. Quando uma mensagem desta for recebida, significa que o cliente gostaria de solicitar o cancelamento de algum serviço requisitado anteriormente. |
.png?version=1&modificationDate=1559047971143&cacheVersion=1&api=v2)
Exemplo de uma solicitação de necessidade logística do tipo aéreo:
exemplo-solicitacao-aereo.json
Confirmar processamento de mensagem
Para confirmar o processamento de uma mensagem, basta enviar uma requisição do tipo POST para /Control, informando o ID do fornecedor (SenderId), o tipo de mensagem (Type 13 = confirmar processamento) e o ID da mensagem que deseja confirmar o processamento (Id). A seguir um exemplo:
POST: /Control |
[{ |
"SenderId" : 123, |
"Type": 13, |
"Id" 10000 |
}] |
Após realizar esta operação, a mensagem será excluída da caixa de mensagens do fornecedor e não será mais retornada.
...