Documentao API Web

Introduo
O iDrake Service disponibiliza uma API Web que permite aos fornecedores realizarem operaes para obter informaes sobre necessidade
logsticas requisitadas pelos clientes atravs do Drake. Alm de obter informaes sobre as necessidades logsticas, possvel utilizar a API
Web para confirmar ou recusar as solicitaes 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

Descrio

Cliente

Solicitar servio

Cliente realiza este caso de uso quando necessidade solicitar um servio ao fornecedor. Nesta solicitao, o
cliente informa os detalhes da necessidade logstica que gostaria que o fornecedor atendesse, dentre as
informaes temos:
Endereo de origem e destino, data e horrio de incio e trmino, participantes (CPF, RG etc).

Cliente

Solicitar alterao
de servio

Cliente realiza este caso de uso quando necessidade solicitar a alterao de um servio ao fornecedor.
Mudanas de data, horrio, endereos, incluso ou excluso de participantes.

Cliente

Solicitar
cancelamento de
servio

Cliente realiza este caso de uso quando necessidade solicitar o cancelamento de um servio. Em geral isto
ocorre quando um servio solicitado anteriormente no mais necessrio.

Fornecedor

Confirmar servio

Fornecedor realiza este caso de uso quando deseja confirmar a solicitao de servio ou solicitao de
alterao de servio. Quando o cliente confirma o servio, ele est informando ao cliente que o fornecedor
est ciente da solicitao e que o servio j est programado para ser prestado.

Fornecedor

Recusar servio

Fornecedor realiza este caso de uso quando deseja recusar uma solicitao de servio ou solicitao de
alterao de servio.

Fornecedor

Confirmar
cancelamento de
servio

Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um servio sem nus
para o cliente.

Fornecedor

Confirmar
cancelamento de
servio com taxa

Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um servio com cobrana
de uma taxa de cancelamento.

Fornecedor

Confirmar
cancelamento de
servio com
reembolso

Fornecedor realiza este caso de uso quando deseja confirmar o cancelamento de um servio, porm
informa ao cliente que o mesmo dever ser pago e posteriormente ser reembolsado pelo fornecedor
(atravs de crdito ou devoluo).

Fornecedor

Recusar
cancelamento

Fornecedor realiza este caso de uso quando deseja recusar um pedido de cancelamento de um servio.

A seguir, um diagrama de atividades entre cliente e fornecedor:

Segurana
Para garantir a segurana na troca de mensagens entre fornecedor e o iDrake Service, existem alguns procedimentos que precisam ser
seguidos.

Obteno do ID e da chave privada do fornecedor

Para obter o ID e a chave privada do fornecedor, basta entrar em contato com a Constant informando um e-mail de um responsvel. Este e-mail
receber uma mensagem explicando o passo-a-passo para a gerao do ID e da chave privada do fornecedor.
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 informaes (na
ordem a seguir):

Informao

Descrio

Verbo HTTP

Exemplo: POST, GET, DELETE

Cabealho x-drake-senderid

ID do fornecedor

Cabealho user-agent

Nome do agente (em geral o nome+verso do navegador ou sistema que est utilizando o servio)

Cabealho date

Data em que a mensagem est sendo enviada. Deve estar no formato RFC 1123 (referncia)

Cabealho content-type

Tipo do contedo (application/json)

Contedo

Contedo 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,"RecipientI
d":15,"Type":2,"DrakeId":4825709,"Details":"No permitido mais de um participante em
solicitaes Rodovirias."}]

Para gerar a assinatura desta mensagem, utilize a chave privada fornecida pela Constant e o algoritmo de hashing SHA512. A seguir um
exemplo de cdigo 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);
}

Aps gerar a assinatura da mensagem, basta adicion-la no cabealho da requisio HTTP utilizando a chave x-Drake-Signature.

Operaes
Ler todas as mensagens disponveis
Esta operao deve ser feita para obter as solicitaes feitas pelos clientes e endereadas para o fornecedor. Esta operao em geral deve ser
realizada atravs de pooling. Sugerimos que use o intervalo de pelo menos 2 minutos entre as requisies.
Para obter as mensagens disponveis, basta enviar uma requisio do tipo POST para /Receive, informando o ID do fornecedor (RecipientId) e o
tipo de mensagem (Type 12 = obter mensagens disponveis). A seguir um exemplo:

POST: /Receive
{
"RecipientId" : 123,
"Type" : 12
}

Como resposta a esta requisio, sero retornadas todas as mensagens disponveis na caixa de sada do fornecedor. A seguir os diferentes
tipos que podem ser retornados:
Tipo

Estrutura

Descrio

Solicitao de
servio (Type =
0)

Representa uma solicitao de servio enviada pelo

cliente. Quando uma mensagem desta for recebida,
significa que o cliente est solicitando um determinado
servio ao fornecedor. Este servio pode ser uma
hospedagem, um carro, uma passagem area etc.

Solicitao de
alterao de
servio (Type =
7)

Representa uma solicitao de alterao de servio

enviada pelo cliente. Quando uma mensagem desta for
recebida, significa que o cliente gostaria de solicitar a
alterao de algum servio requisitado anteriormente.
Diversos tipos de alteraes podem ser feitas, como:
Alteraes de horrios
Incluso de novos participantes
Excluso de participantes
Alterao de endereos
etc

Solicitao de
cancelamento de
servio (Type =
3)

Representa uma solicitao de cancelamento de um

servio. Quando uma mensagem desta for recebida,
significa que o cliente gostaria de solicitar o
cancelamento de algum servio requisitado
anteriormente.

Confirmar processamento de mensagem

Para confirmar o processamento de uma mensagem, basta enviar uma requisio 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
}

Aps realizar esta operao, a mensagem ser excluda da caixa de mensagens do fornecedor e no ser mais retornada.

Confirmar servio

Para confirmar o servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do
fornecedor (SenderId), o tipo de mensagem (Type 1 = confirmar servio) e as informaes adicionais
sobre o servio. A seguir um diagrama de classes com a estrutura do contedo que dever estar
presente na requisio e em seguida um exemplo:
Estrutura

Exemplo

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
rodoviria"
}

Recusar servio
Para recusar uma solicitao de servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo
de mensagem (Type 2 = recusar servio), o cdigo da necessidade (DrakeId) e o motivo da recusa (Details). A seguir um exemplo:

POST: /Send
{
"SenderId" : 123,
"Type" : 2,
"DrakeId" : 12345,
"Details" : "No existe voo para a data solicitada."
}

Confirmar cancelamento
Para confirmar o cancelamento de um servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do fornecedor (SenderId),
o tipo da mensagem (Type 4 = confirmar cancelamento) e o cdigo da necessidade (DrakeId). A seguir um exemplo:

POST: /Send
{
"SenderId" : 123,
"Type" : 4,
"DrakeId" : 12346
}

Confirmar cancelamento com taxa

Para confirmar o cancelamento de um servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do fornecedor (SenderId),
o tipo da mensagem (Type 19 = confirmar cancelamento com taxa), o cdigo da necessidade (DrakeId) e o valor da taxa (FeeValue). A seguir
um exemplo:

POST: /Send
{
"SenderId" : 123,
"Type" : 19,
"FeeValue" : 10.50,
"DrakeId" : 12347
}

Confirmar cancelamento com reembolso

Para confirmar o cancelamento de um servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do fornecedor (SenderId),
o tipo da mensagem (Type 5 = confirmar cancelamento com reembolso), o cdigo 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
}

Recusar cancelamento

Para recusar um cancelamento de um servio, basta enviar uma requisio do tipo POST para /Send, informando o ID do fornecedor (SenderId),
o tipo da mensagem (Type 6 = recusar cancelamento), o cdigo da necessidade (DrakeId). A seguir um exemplo:

POST: /Send
{
"SenderId" : 123,
"Type" : 6,
"DrakeId" : 12349
}