Documentação API Web
Introdução
O iDrake Logistics 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 e também enviar previas de fatura que podem ser avalidadas pelos clientes.
A seguir os casos de uso das funcionalidades que podem ser realizadas pelo cliente e pelo fornecedor na API Web do iDrake Logistics:
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. |
Fornecedor | Informar uso do serviço | Fornecedor realiza este caso de uso quando deseja informar que o serviço foi utilizado pelo trabalhador. |
Fornecedor | Informar não utilização do serviço | Fornecedor realiza este caso de uso quando deseja informar que o serviço não foi utilizado pelo trabalhador (ocorreu no show). |
Fornecedor | Solicitar aprovação de fatura | Fornecedor realiza este caso de uso quando deseja que o cliente valide uma prévia da fatura. |
Cliente | Aprovar fatura | Cliente realiza este caso de uso quando deseja aprovar a fatura enviada pelo fornecedor. |
Cliente | Reprovar fatura | Cliente realiza este caso de uso quando deseja reprovar a fatura enviada pelo fornecedor. |
Cliente/Fornecedor | Ler novas mensagens | Fornecedor ou cliente realiza este caso de uso quando deseja ler as mensagens que foram enviadas para eles. |
Cliente/Fornecedor | Confirmar leitura de mensagem | Fornecedor ou cliente realiza este caso de uso quando deseja confirmar que leu uma mensagem. Ao fazer essa ação, a mensagem é removida da caixa de mensagens. |
Segurança
A autenticação com a API Web do iDrake Logistics deve ser realizada através de um Bearer Token.
Para obter o Bearer Token, 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.
Após gerar o Bearer Token, basta usa-lo no cabeçalho "Authorization" das requisições HTTP.
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.
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. |
Fatura aprovada (Type = 15) | | Representa uma aprovação da fatura. Quando uma mensagem desta for recebida, significa que o cliente aprovou a fatura que foi enviada anteriormente. |
Fatura reprovada (Type = 16) | | Representa uma reprovação de fatura. Quando uma mensagem desta for recebida, significa que o cliente reprovou a fatura que foi enviada anteriormente. Dentro dessa mensagem é possível verificar quais itens ou valores extras foram reprovados pelo cliente através do status do item ou do valor extra.
Código dos Status: 0 = Aprovação Solicitada 1 = Aprovado 2 = Reprovado |
Exemplos de mensagens que são recebidas pelos fornecedores:
Exemplo de uma solicitação de necessidade logística do tipo aéreo:
Exemplo de uma recusa de fatura:
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:
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:
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:
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:
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:
Solicitar aprovação de fatura
Para solicitar uma aprovação de uma fatura, basta enviar uma requisição do tipo POST para /Send, informando o ID do fornecedor (SenderId), o tipo da mensagem (Type 14 = solicitar aprovação de fatura), o código da fatura (ExternalId). A seguir um exemplo:
Código das mensagems que podem ser recebidas/enviadas pelos fornecedores
🔹 0 – ServiceRequest
Mensagem enviada pelo Cliente sempre que necessitar de atendimento logístico por parte do fornecedor.
🔹 1 – ConfirmService
Mensagem enviada pelo Fornecedor em resposta a uma ServiceRequest, confirmando que poderá atender à solicitação.
🔹 2 – RefuseRequest
Mensagem enviada pelo Fornecedor para cada necessidade que não poderá ser atendida.
🔹 3 – CancelationRequest
Mensagem enviada pela Empresa Cliente para solicitar o cancelamento de uma necessidade previamente atendida.
🔹 4 – CancelationConfirmation
Mensagem enviada pelo Fornecedor em resposta a uma solicitação de cancelamento, quando o cancelamento for possível sem custo.
🔹 5 – CancelationConfirmationWithRefund
Mensagem enviada pelo Fornecedor em resposta a uma solicitação de cancelamento, quando o cancelamento for possível, mas sujeito a reembolso.
🔹 6 – RefuseCancelation
Mensagem enviada pelo Fornecedor em resposta a uma solicitação de cancelamento, quando o cancelamento não for possível.
🔹 7 – ChangeRequest
Mensagem enviada pela Cliente para solicitar a alteração de um atendimento anteriormente solicitado.
🔹 9 – CancelService
Mensagem enviada pelo Fornecedor para informar que um atendimento previamente confirmado não poderá mais ser fornecido.
🔹 10 – NotifyUse
Mensagem enviada pelo Fornecedor para informar que a necessidade foi efetivamente utilizada pelo trabalhador.
🔹 11 – NotifyNoShow
Mensagem enviada pelo Fornecedor para informar que a necessidade não foi utilizada devido à ausência da pessoa que deveria utilizá-la.
🔹 12 – GetUnconfirmedServiceRequest
Mensagem enviada pelo Fornecedor quando precisar da lista de mensagens ainda não confirmadas como recebidas.
🔹 13 – ConfirmReceivedMessage
Mensagem enviada pelo Cliente ou pelo Fornecedor para confirmar o recebimento de uma mensagem.
🔹 14 – InvoiceApprovalRequest
Mensagem enviada pelo Fornecedor para solicitar a aprovação de uma nota fiscal para faturamento.
🔹 15 – ApproveInvoice
Mensagem enviada pelo Cliente para aceitar uma nota fiscal enviada pelo fornecedor.
🔹 16 – RefuseInvoice
Mensagem enviada pelo Cliente para recusar uma nota fiscal enviada pelo fornecedor.
🔹 17 – Acknowledgment
Mensagem gerada automaticamente pelo serviço, quando o remetente de uma mensagem original solicitou receber uma notificação de leitura.
🔹 18 – GetBillEntries
Mensagem utilizada para solicitar as entradas de cobrança (bill entries).
🔹 19 – CancelationConfirmationWithFee
Mensagem enviada pelo Fornecedor para confirmar o cancelamento de um serviço, porém com cobrança de taxa (cancelamento com pagamento).
🔹 20 – ConfirmProcessing
Mensagem enviada para indicar que uma outra mensagem foi processada com sucesso.