Introdução
O iDrake Service disponibiliza uma API Web que permite aos fornecedores realizarem operações para obter informações sobre necessidade logísticas requisitadas pelos clientes através do Drake. Além de obter informações sobre as necessidades logísticas, é possível utilizar a API Web para confirmar ou recusar as solicitações feitas pelos clientes.
A seguir um diagrama de casos de uso das funcionalidades que podem ser realizadas pelo cliente e pelo fornecedor na API Web do iDrake Service:
Ator | Caso de uso | Descrição |
| Cliente | Solicitar serviço | Cliente realiza este caso de uso quando necessidade solicitar um serviço ao fornecedor. Nesta solicitação, o cliente informa os detalhes da necessidade logística que gostaria que o fornecedor atendesse, dentre as informações temos: Endereço de origem e destino, data e horário de início e término, participantes (CPF, RG etc). |
| Cliente | Solicitar alteração de serviço | Cliente realiza este caso de uso quando necessidade solicitar a alteração de um serviço ao fornecedor. Mudanças de data, horário, endereços, inclusão ou exclusão de participantes. |
| Cliente | Solicitar cancelamento de serviço | Cliente realiza este caso de uso quando necessidade solicitar o cancelamento de um serviço. Em geral isto ocorre quando um serviço solicitado anteriormente não é mais necessário. |
| Fornecedor | Confirmar serviço | Fornecedor realiza este caso de uso quando deseja confirmar a solicitação de serviço ou solicitação de alteração de serviço. Quando o cliente confirma o serviço, ele está informando ao cliente que o fornecedor está ciente da solicitação e que o serviço já está programado para ser prestado. |
| Fornecedor | Recusar serviço | Fornecedor realiza este caso de uso quando deseja recusar uma solicitação de serviço ou solicitação de alteração de serviço. |
| Fornecedor | Confirmar cancelamento de serviço | Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um serviço sem ônus para o cliente. |
| Fornecedor | Confirmar cancelamento de serviço com taxa | Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um serviço com cobrança de uma taxa de cancelamento. |
| Fornecedor | Confirmar cancelamento de serviço com reembolso | Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um serviço, porém informa ao cliente que o mesmo deverá ser pago e posteriormente será reembolsado pelo fornecedor (através de crédito ou devolução). |
| Fornecedor | Recusar cancelamento | Fornecedor realiza este caso de uso quando deseja recusar um pedido de cancelamento de um serviço. |
A seguir, um diagrama de atividades entre cliente e fornecedor:
Segurança
Para garantir a segurança na troca de mensagens entre fornecedor e o iDrake Service, existem 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.
Atenção: A chave privada deve ser mantida sob sigilo e deverá ser usada pelo fornecedor para assinar todas as mensagens enviadas a fim de garantir sua autenticidade.
Como assinar uma mensagem
Toda mensagem enviada para o iDrake Service deverá estar assinada. A assinatura da mensagem deve utilizar as seguintes informações (na ordem a seguir):
Informação | Descrição |
| Verbo HTTP | Exemplo: POST, GET, DELETE |
| Cabeçalho x-Drake-SenderId | ID do fornecedor |
| Cabeçalho user-agent | Nome do agente (em geral o nome+versão do navegador ou sistema que está utilizando o serviço) |
| Cabeçalho date | Data em que a mensagem está sendo enviada. Deve estar no formato RFC 1123 (referência) |
| Cabeçalho content-type | Tipo do conteúdo (application/json) |
| Conteúdo | Conteúdo da mensagem (em formato JSON) |
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."}] |
A seguir um exemplo de código em C# usado para assinar a mensagem:
public static string GetDataToSign(IDictionary<string, string> headers, string method, string content) |
{ |
string[] HeadersToSign = { "x-Drake-SenderId", "User-Agent", "Date", "Content-Type" }; |
|
var dataToSign = new StringBuilder(); |
dataToSign.AppendFormat("{0}\n", method); |
string[] HeadersToSign = { "x-Drake-SenderId", "User-Agent", "Date", "Content-Type" } |
foreach (string headerKey in HeadersToSign.OrderBy(h => h).ToList()) |
{ |
dataToSign.AppendFormat("{0}:{1}\n", headerKey.ToLower(), headers[headerKey]); |
} |
|
dataToSign.Append("\n"); |
dataToSign.Append(content); |
return dataToSign.ToString(); |
} |
Para gerar a assinatura desta mensagem, utilize a chave privada fornecida pela Constant e o algoritmo de hashing SHA512. A seguir um exemplo de código em C#:
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: https://logistic-integrator-tst.drake.bz/MessageService/
Operações
Ler todas as mensagens disponíveis
Esta operação deve ser feita para obter as solicitações feitas pelos clientes e endereçadas para o fornecedor. Esta operação em geral deve ser realizada através de pooling. Sugerimos que use o intervalo de pelo menos 2 minutos entre as requisições.
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.
Confirmar serviço
Para confirmar o serviço, envie um requisição do tipo POST para /Send, informando o ID do fornecedor (Senderld), o tipo de mensagem (Type 1= Confirmar serviço) e as informações adicionais sobre o serviço. A seguir um diagrama de classes com a estrutura do conteúdo que deverá estar presente na requisição e em seguida um exemplo:
Estrutura |
|
Exemplos:
Para confirmar uma solicitação de serviço, basta enviar uma requisição do tipo POST para /Send. A seguir exemplos de body para cada tipo de atendimento:
exemplo-confirmacao-atendimento-aereo.json
exemplo-confirmacao-atendimento-hotel.json
exemplo-confirmacao-atendimento-terrestre.json
Recusar serviço
Para recusar uma solicitação de serviço, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo de mensagem (Type 2 = recusar serviço), o código da necessidade (DrakeId) e o motivo da recusa (Details). A seguir um exemplo:
Confirmar cancelamento com taxa
Para confirmar o cancelamento de um serviço, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo da mensagem (Type 19 = confirmar cancelamento com taxa), o código da necessidade (DrakeId) e o valor da taxa (Value). A seguir um exemplo:
exemplo-de-confirmacao-de-cancelamento-com-taxa.json
Confirmar cancelamento com reembolso
Para confirmar o cancelamento de um serviço, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo da mensagem (Type 5 = confirmar cancelamento com reembolso), o código da necessidade (DrakeId) e o valor estimado do reembolso (RefundValue) A seguir um exemplo:
exemplo-de-confirmacao-de-cancelamento-com-reembolso.json
Confirmar cancelamento sem custo
Para confirmar o cancelamento de um serviço sem custo, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo da mensagem (Type 4 = confirmar cancelamento sem custo), o código da necessidade (DrakeId) e o valor estimado do reembolso (RefundValue) A seguir um exemplo:
exemplo-de-confirmacao-de-cancelamento-sem-custo.json
Recusar cancelamento
Para recusar um cancelamento de um serviço, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo da mensagem (Type 6 = recusar cancelamento), o código da necessidade (DrakeId). A seguir um exemplo:
exemplo-de-recusa-de-cancelamento.json