Primeiros Passos na API
O TudoEntregue surgiu da necessidade de se criar uma forma simples e eficiente para a comunicação entre Contratante e o Motorista, de forma a proporcionar uma plataforma na qual o Motorista possa receber solicitações de Entrega e/ou Coleta e ser acompanhado pelo seu Contratante em tempo real, informando todas as etapas e eventos relacionados com o transporte.
O Contratante pode enviar ao Motorista solicitação de Entrega e/ou Coleta, relacionando documentos e seus volumes, conforme a necessidade do negócio, bem como receber notificações do motorista sobre os eventos e ocorrências, assim como o registro fotográfico durante qualquer etapa do processo e/ou o comprovante de entrega devidamente assinado.
Toda a informação e ações realizadas ficam armazenadas localmente no celular até que seja enviado para a API do Aplicativo. Ao receber os retornos do Aplicativo, a API já disponibiliza as informações para os sistemas que realizarão a integração da entrega e/ou coleta.
A documentação disponível aqui reflete os métodos disponíveis ao Contratante para integrar seus sistemas à plataforma do TudoEntregue, bem como receber as informações e notificações pertinentes ao processo. Todos os processos descritos podem ser igualmente realizados pelo Portal da Solução e/ou por aplicativos desenvolvidos pela própria Active Corp.
Este artigo é um complemento à documentação técnica, que visa ampliar o entendimento do funcionamento da API e seus respectivos métodos. Trazendo descrições detalhadas, exemplificações, e fluxogramas pertinentes a cada método.
Limites:
Visando favorecer um comportamento otimizado da API, são prescritas as seguintes limitações:
- Envio de informações:
-
- Geral: Limite de 1MB em texto (JSON).
- Método “Inclusão/Edição de Entrega”: Até 50 Entregas por requisição.
- Consulta de informações:
- Processos que devolvam apenas registros ainda não consumidos: É permitido realizar requisições até esgotar a fila. (Exemplo: Utilizar o método “Consulta de Entregas com Ocorrência” até o mesmo devolver todas as Entregas já finalizadas.) Caso sejam realizadas 10 requisições sem retorno consecutivas, acarretará em bloqueio do uso da API por 1 minuto. Ao repetir, o bloqueio será de 10 minutos, e caso persista, será bloqueado por no máximo 1 hora.
- Processos que trabalhem com paginação: É permitido realizar requisições com intervalo de 5 segundos entre elas. (Exemplo: Utilizar o método “Consulta de Entregas com Ocorrência” com o parâmetro “partial” sem informação de uma Entrega específica.)
- Processos que devolvam a partir de uma informação especifica: É permitido realizar apenas 1 requisição a cada 10 minutos. (Exemplo: Utilizar o método “Consulta de Entregas com Ocorrência” para devolver uma Entrega baseado no número da Entrega.)
A ActiveCorp reserva-se o direito de bloquear a qualquer momento, sem prévio aviso, o uso da API do TudoEntregue por parte do Contratante caso seja identificado o uso indevido da mesma e/ou comportamento que não condiz com as boas práticas da ActiveCorp.
Autenticações:
AppKey: Identificador do fornecedor de software que for Homologado junto à ActiveCorp, autorizado a Integrar dados ao TudoEntregue. Essa informação deve ser obtida junto a Active Corp.
RequesterKey: Identificador único da Contratante no TudoEntregue. Essa informação pode ser obtida no Portal do TudoEntregue > Tela de “Empresa” > Token de Integração.
Legenda:
Contratante: Toda vez que for mencionado o termo Contratante, se refere à empresa que contratou o TudoEntregue.
Entrega: Toda vez que for mencionado o termo Entrega, se refere à uma Entrega ou Coleta conforme definição do tipo na mesma.
– Separação de Cargas: Tratado no Portal da aplicação com o mesmo nome. Porém, é conhecido também como “Romaneio”.
Observações:
– Todos os campos não obrigatórios ao método, não precisam estar contidos na requisição.
– Guia básico de utilização do Swagger.
- Começando com um Motorista Novo:
Com a inclusão do motorista no TudoEntregue, é possível realizar o envio de entregas e comunicação em geral.
Para incluir o Motorista, é necessário apenas o Nome, e o Número de celular do mesmo. O Motorista precisa ter um dispositivo móvel (celular ou tablet) com o sistema operacional Android ou iOS, e fazer o download do aplicativo através da loja (Google Play / App Store) de acordo com o tipo do sistema. O cadastro pode ser feito antes ou depois do download do aplicativo.
É possível realizar o cadastro pela API, através deste método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Motorista/post_customers_addDriver
Se o Motorista já utiliza o TudoEntregue: Ao fazer o cadastro, o mesmo será vinculado à nova Contratante, e receberá uma notificação informando que uma nova Empresa o adicionou no TudoEntregue, e estará pronto para receber as Entregas da Contratante.
Se o Motorista ainda não utiliza o TudoEntregue, o mesmo será associado ao Contratante e receberá um link por SMS para download do aplicativo, podendo também fazer o download diretamente da loja, conforme mencionado acima. E após fazer o cadastro no aplicativo informando seu Nome, Número de telefone, e o código recebido por SMS, já estará pronto para receber as Entregas da Contratante.
Caso o Motorista não tenha número de celular, é necessário cadastrá-lo por meio do portal do TudoEntregue. Na tela de Motorista > Menu de Opções > “Novo”, marcando a flag “Dispositivo Sem SimCard”. Com isso, o sistema irá gerar um número de telefone aleatório, e um código SMS, que deverão ser inseridos no aplicativo do Motorista.
- Desativando ou Reativando um Motorista
Caso um Motorista deixe de prestar serviço para sua Contratante, é possível desabilitar a utilização do mesmo através da API utilizando o seguinte método, com o parâmetro “Enable” definido para: “false”:
Com isso, não será mais possível atribuir Entregas a este Motorista.
Caso um Motorista que estava desativado volte a prestar serviços para a Contratante, é possível habilitá-lo novamente, utilizando este mesmo método, com o parâmetro “Enable” definido para: “true”.
- Incluindo uma Solicitação de Entrega
- Requisitos
Para incluir uma Entrega, é necessário ter, ao menos, os dados básicos da entrega. Como por exemplo:
- Dados da Contratante (Tipo e Número do Documento)
- Tipo da Entrega (Entrega ou Coleta);
- Número da Entrega;
- ID da Entrega (Identificador único da Entrega);
- Descrição da entrega (Se trata de uma NF-e, CT-e, MDF-e, ou outro tipo de documento?);
- Nome e Endereço do destinatário.
- Definição de Motorista:
- Para incluir uma Entrega definindo o Motorista: O mesmo precisa estar previamente cadastrado e ativo no sistema. É utilizado o parâmetro “DefineDriverAfter” definido com valor “0”, conforme mencionado na Documentação da API. Com isso, a Entrega será atribuída e enviada para o celular do Motorista.
- Para incluir uma Entrega sem definir o Motorista, é utilizado o parâmetro “DefineDriverAfter” definido com valor “1”.
- Comunicações de situação de Entrega por E-mail / SMS:
- Dentre os dados de destinatário (DestinationAddress), é possível informar o E-mail do mesmo (campo “Email”), e/ou um Celular (campos “PhoneCountrySms” e “PhoneNumberSms”) para que as comunicações de situação de Entrega por E-mail e/ou SMS sejam enviadas automaticamente.Ao deixar estes campos em branco, estas comunicações não são enviadas.
-
- É possível desabilitar estas comunicações de maneira geral, através da tela “Empresa”, através da flag: “Desabilitar Envio de SMS e E-mail para o Destinatário da Entrega”. E também desabilitar individualmente por cliente, utilizando a tela “Clientes”, através da flag de mesmo nome.
- Endereços:
- “DestinationAddress”: Endereço do Destinatário.
Para as Entregas, este é o endereço visível no aplicativo do Motorista. Ou seja, o destino da carga.
- “SourceAddress”: Endereço do Remente.
No caso de Coletas, este é o endereço visível no aplicativo do Motorista da Entrega. Ou seja, onde ele irá buscar a carga.
- Previsão (ou Agendamento) de Entrega:
- Representado pelos Campos:
- “DeliveryDate”: Data de Previsão da Entrega.
- “DeliveryStartTime” e “DeliveryEndTime”: Intervalo de horários da Previsão da Entega.
- No caso de Coletas, são utilizados os campos: “CollectDate”, “CollectStartTime” e “CollectEndTime”, respectivamente.
- Este campo impacta diretamente na situação da Entrega (No prazo/Atrasado), que alimenta os indicadores da tela “Resumo da Operação”.
- Cada vez que a Previsão é alterada, o cliente recebe um E-mail/SMS caso informado e autorizado. (Exceto caso a Previsão informada seja retroativa).
- Representado pelos Campos:
- Visualização no celular do Motorista:
Os campos da Entrega que ficam visíveis no aplicativo do Motorista, são:
- Tipo de documento da Entrega: “OrderDescription”;
- Número da Entrega: “OrderNumber”;
- Telefone: “PhoneNumber”;
- Responsável: “Responsibility”;
- Número da sequência: “Sequence”;
- Observação: “Observation”;
- Dados dos documentos: “DocumentDescription”;
- Dados dos volumes relacionados aos documentos:
- “Count”: Quantidade total de volumes.
- “BarCode”: Código de barras.
- “Description”: Nome do item.
- Para Entregas:
- Destinatário: Campo “Name”, do objeto “DestinationAddress”;
- Endereço completo do destinatário: Todos os campos referentes ao endereço no objeto “DestinationAddress”;
- Data e Hora de Previsão/Agendamento da Entrega: “DeliveryDate”, “DeliveryStartTime” e “DeliveryEndTime”;
- Para Coletas:
- Destinatário: Campo “Name”, do objeto “SourceAddress”;
- Endereço completo do remetente: Todos os campos referentes ao endereço no objeto “SourceAddress”;
- Data e Hora de Previsão/Agendamento da Coleta: “CollectDate”, “CollectStartTime” e “CollectEndTime”.
- Separação de Cargas e Roteirização:
- Ao informar a Rota (Campo “LoadSeparation_RouteName”), a Entrega será vinculada a uma Separação de Cargas com este nome. Caso não haja, será criada uma nova Separação de Carga;
- Ao informar a sequência, não é necessário fazer a roteirização por meio do TudoEntregue;
Bem como é possível enviar todos os demais dados da Entrega utilizando a mesma requisição, dependendo de sua necessidade.
Link deste método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/post_orders
Assim que a Entrega é incluída, a API retorna as informações básicas da mesma.
Juntamente com o código e link de Acompanhamento da Entrega.
- Editando uma Solicitação de Entrega
Para acrescentar, editar ou apagar algum dado de uma Entrega que já foi criada, deve-se enviar a mesma requisição de inclusão da Entrega, porém com os dados atualizados, utilizando o método abaixo:
https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/post_orders
Importante: Caso deixe algum campo vazio ou em branco, ao enviar a edição, a informação que existia será deletada. Ou seja, o campo ficará em branco / vazio.
Não é possível realizar a Edição de uma Entrega que já possua alguma movimentação registrada, bem como não é possível incluir mais de uma Entrega com as mesmas informações de identificação, como “Número da Entrega” e “Tipo da Entrega” pendente de finalização.
Ao incluir o Motorista em uma Entrega que ainda não tinha o Motorista atribuído, a Entrega não é enviada automaticamente pro celular do mesmo. Devendo fazer o envio pelo portal, através do botão “Enviar para o Motorista”, no menu de “Opções” na tela de Entrega.
- Excluindo uma Entrega
Para excluir uma Entrega que foi incluída errada, utiliza-se o método de Exclusão de Entregas. Mas atenção, este método irá excluí-la permanentemente do sistema.
Porém, caso a Entrega já tenha alguma movimentação registrada, não é possível excluí-la do sistema. Devendo, nesse caso, utilizar o método de cancelamento de Entrega.
É necessário apenas os dados da Contratante, Tipo da Entrega, e ID da Entrega.
Link do método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/post_orders_delete
- Cancelando uma Entrega
Para cancelar uma Entrega, mesmo que ela já tenha alguma movimentação registrada, utilize o método de “Cancelamento de Entrega”:
https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/put_orders_cancel
Após a Entrega ser finalizada, não é possível realizar o cancelamento.
É necessário apenas os dados da Contratante, Tipo da Entrega, e ID da Entrega.
Após o cancelamento, a Entrega permanece no TudoEntregue, e tem a Situação alterada para: “Operação Cancelada”. Para excluir uma Entrega permanentemente, utilize o método “Exclusão de Entrega”.
- Consultando a situação de Entregas
Precisa consultar a situação das Entregas perante o sistema? Utilize este método.
Este método consulta a situação atual da Entrega desejada. Conforme lista de Situações abaixo.
Diferentemente do método de Consultando Entregas com Ocorrência, este método não retorna as Ocorrências das Entregas, nem informações da Entrega que sejam pertinentes ao Cliente final obter. (como no método de “Consulta de Acompanhamento de Entrega”).
Para consultar a situação de Entregas, é necessário que as mesmas já tenham sido atribuídas a algum Motorista.
Ao realizar a consulta sem nenhum parâmetro, o resultado reúne as Entregas atribuídas a todos os Motoristas. É possível filtrar para receber apenas as informações de Entrega(s) atribuída(s) a um determinado Motorista, informando o telefone do Motorista. Bem como, filtrar uma Entrega em específico, informando o Tipo e ID da Entrega. Utiliza-se o seguinte método:
https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/get_orders_situation
Com isso, obtém-se as informações básicas da Entrega, Motorista, e a Situação atual da Entrega, sendo alguma das seguintes:
0 – Recebida pela Torre de Controle; (Ainda não foi solicitado o envio da Entrega para o celular do Motorista.)
1 – Enviada ao Motorista; (Já foi enviado para o celular do Motorista, porém o mesmo ainda não aceitou.)
2 – Enviada ao Motorista e Aguardando Confirmação; (*Essa Situação foi descontinuada.*)
3 – Recebida pelo Motorista; (A Entrega foi recebida e confirmada pelo aplicativo do Motorista.)
4 – Enviada ao Motorista e Recusada; (A Entrega foi recusada pelo Motorista. *Essa Situação foi descontinuada, pois não há mais a opção de Recusa por parte do Motorista.*)
5 – Finalizada pelo Motorista; (O Motorista indicou que a Entrega foi Finalizada, lançando alguma Ocorrência Finalizadora na Entrega.)
6 – Finalizada pela Torre de Controle; (O portal indicou que a Entrega foi Finalizada).
7 – Operação Finalizada; (*Essa Situação foi descontinuada.*)
8 – Operação Cancelada ->
Cancelada pela Torre de Controle – Momento em que o usuário pelo portal efetua o cancelamento da entrega, tendo sido enviada ou não ao motorista;
Cancelada pelo Motorista – Momento em que o motorista realiza o cancelamento pelo app;
9 – Notificação de Cancelamento Enviada (Momento em que se cancela pelo portal e a entrega se encontra no celular do motorista. Após o motorista sincronizar, entra o status 8 na entrega no portal (Cancelada pela Torre de Controle);
11 – Transferida
Transferida pelo Motorista – Momento em que o motorista transfere a entrega para outro motorista;
Transferida pela Torre de Controle – Momento em que é efetivada a transferência feita pelo portal, após o status 12.
12 – Notificação de Transferência Enviada – Momento em que a torre de controle efetua a transferência e ainda não foi sincronizada no app do motorista.
Uma vez consultada a Situação de cada Entrega, não é possível retornar a mesma consulta novamente. Ou seja, este método não permite retransmissão.
Porém, assim que a Entrega mudar de Situação, é possível consultar a mesma Entrega novamente.
- Consultando Entregas com Ocorrência
Este método possibilita consultar Entregas que já tenham Ocorrência(s) lançada(s), juntamente com suas respectivas observações, e imagens dos comprovantes de Entrega. Assim como o método de “Consulta de Situação de Entrega”, este método busca informações da Entrega que são pertinentes ao Contratante, porém, além de trazer os dados de Situação das Entregas, traz também os dados das Ocorrências.
Para consultar dados da Entrega pertinentes ao Cliente, utiliza-se o método de “Consulta de Acompanhamento de Entrega”.
Ao realizar a consulta sem nenhum parâmetro, o resultado reúne as Entregas atribuídas a todos os Motoristas. É possível filtrar para receber apenas as informações de Entrega(s) atribuída(s) a um determinado Motorista, informando o telefone do Motorista. Bem como, filtrar uma Entrega em específico, informando o Tipo e ID da Entrega.
Para buscar apenas as Entregas em aberto, é utilizado o parâmetro “partial” com valor “true”. Para buscar apenas as Entregas que já foram finalizadas, não envia-se este parâmetro, ou envia-se com o valor “false”.
Para isso, é utilizado o seguinte método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Entrega/get_orders_finish
Ao realizar a consulta sem parâmetros, ou filtrando apenas pelo telefone do Motorista, não é possível retransmitir a mesma consulta novamente. Porém, assim que o Motorista lançar outra(s) Ocorrência(s), é possível consultar a mesma Entrega novamente. Com isso serão retornadas todas as Ocorrências atribuídas àquela Entrega.
Ao realizar a consulta filtrando com o Tipo e ID de uma Entrega em específico, é possível retransmitir.
- Incluindo / Editando um Tipo de Ocorrência
Este método é utilizado caso seja necessário incluir um novo Tipo de Ocorrência que ainda não exista no seu sistema. Podendo também utilizá-lo para editar um Tipo de Ocorrência já existente. As Ocorrências incluídas, ou editadas por meio deste método, serão atualizadas no lista de Ocorrências do aplicativo do Motorista assim que o mesmo atualizar a lista de Entregas.
Para incluir uma nova ocorrência, é necessário o Código da Ocorrência, Descrição, e informar se a ocorrência é do tipo “Finalizadora” ou não. A partir disto, é possível também informar os demais parâmetros da ocorrência. Utilizando o seguinte método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Ocorrência/post_occurrences
É possível editar a Descrição e os demais parâmetros das Ocorrências já existentes, utilizando como base o número da Ocorrência existente, e enviando a mesma requisição de inclusão da Ocorrência, porém com os dados atualizados (o número da Ocorrência deve permanecer o mesmo).
- Listando as Ocorrências cadastradas
É possível consultar as ocorrências cadastradas no sistema e seus respectivos parâmetros. Por meio do método: https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Ocorrência/get_occurrences
Para consultar todas as Ocorrências cadastradas, é possível enviando apenas os Dados da Contratante (Tipo e Número do Documento).
Para consultar apenas uma Ocorrência em específico, envia-se também o Código da Ocorrência.
- Consultando Acompanhamento de Entrega
O acompanhamento da Entrega, diferentemente dos outros métodos de consulta, traz apenas os dados da Entrega pertinentes ao Cliente (conforme citado abaixo). Inclusive, retorna apenas as Ocorrências que tiverem a configuração “Visível para o cliente” habilitada.
Para consultar os dados de Acompanhamento da Entrega, é necessário que a Entrega esteja cadastrada e informar o código de rastreamento (código único gerado na criação de cada Entrega), através do método:
Com isso, é possível obter os dados básicos da Entrega, como:
- Dados de Agendamento da Entrega;
- Dados do Motorista;
- Nome do Remetente;
- Dados do destinatário;
- Dados das Ocorrências lançadas. (Apenas as que tiverem a configuração “Visível para o cliente” habilitada).
- Avaliação dada pelo Cliente para aquela Entrega.
- Consultando dados do Contratante de listagem de Motoristas
Precisa consultar os dados cadastrais da Contratante no TudoEntregue? Ou ainda, relacionar todos os Motoristas cadastrados na Contratante, e seus respectivos dados? Para isso, aplica-se este método.
Este método, por padrão, retorna os dados cadastrais da Contratante. Para relacionar também a lista de Motoristas, enviar o parâmetro “DriverDetail” com o valor “true”, caso não, enviar “false” (Padrão).
https://app.swaggerhub.com/apis-docs/ActiveCorp/TudoEntregue/#/Empresa/get_customers
Webhook
A ActiveCorp disponibiliza um Webhook que realiza envio de Ocorrências de Entrega para o Contratante. Ou seja, realiza o envio automático de uma requisição POST toda vez que uma nova Ocorrência é lançada em uma Entrega.
Tal funcionalidade evita que seja necessário, por exemplo, programar uma consulta de ocorrências de tempos em tempos na API. E ainda, poupa a utilização de recursos de processamento, e dispensa o tempo de atraso entre o momento real em que a Ocorrência é lançada, e a consulta que seria feita pela API.
A estrutura desta notificação é equivalente à requisição de “Consulta de Entregas com Ocorrência”, disponível na Documentação da API.
Para configurar uma URL para receber as notificações via Webhook, basta acessar o Portal do TudoEntregue > Tela de “Empresa” > Webhook – URL para envio de ocorrências.