Documentação API Web

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 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

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: Alterações de horários Inclusão de novos participantes Exclusão de participantes Alteração de endereços etc
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.

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:

exemplo-recusa.json

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