Introdução
...
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:
...
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.
...
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 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.
...
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:
...
POST: /Send
...
{
...
"SenderId" : 123
...
"Type" : 1,
...
"DrakeId": 12344,
...
"ExternalId" : "COD-FORNECEDOR-100",
...
"Value" : 200.50,
...
"Fees" : 10,
...
"Commission" : 5.30,
...
"ReservationNumber" : "X123",
...
"Details" : "Retirar bilhete na rodoviária"
...
}
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:
POST: /Send |
{ |
"SenderId" : 123, |
"Type" : 4, |
"DrakeId" : 12346 |
} |
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 (FeeValueValue). A seguir um exemplo:
POST: /Send |
{ |
"SenderId" : 123, |
"Type" : 19, |
"FeeValue" : 10.50, |
"DrakeId" : 12347 |
} |
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:
...
POST: /Send
...
{
...
"SenderId" : 123,
...
"Type" : 5,
...
"RefundValue" : 90.30,
...
"DrakeId" : 12348
...
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:
...
POST: /Send
...
{
...
"SenderId" : 123,
...
"Type" : 6,
...
"DrakeId" : 12349
...
exemplo-de-recusa-de-cancelamento.json