Melhores práticas de uso da API para fazer chamadas e automatizar o lançamento e acompanhamento de pedidos na Loggi para corridas de Ponto-a-Ponto em contratos do tipo Presto

Parametrização do serviço em produção

Para integração em Locais, o cliente pode obter as informações da seguinte forma:
Habilitar serviço de Locais: cliente deve solicitar ao Executivo de Vendas, caso possua um Executivo designado, ou [email protected] caso não tenha.

  • Método de Pagamento: cliente deve acessar www.loggi.com > Configurações > Meios de Pagamento. Criar Centro de Custo. Acessar a tela de edição e copiar o código do método de pagamento da URL. Por exemplo, na URL loggi.com/presto/app/configuracoes/pagamentos/centro-custo/2168299 o código do Centro de Custo é 2168299.

  • E-mail: cliente deve acessar www.loggi.com > Configurações > Usuários cadastrados e criar uma conta com perfil de Administrador.

  • API Key: cliente deve acessar www.loggi.com > Configurações > Configurações de API.

Caso esteja com dificuldade de encontrar estas informações, o cliente ou a Intelipost com o cliente em cópia devem entrar em contato com seu Executivo de Vendas. Caso o cliente não possua um Executivo designado, as informações podem ser solicitadas pelo e-mail [email protected]

Tipos de acesso para a API

Para realizar a integração o cliente necessita ter uma conta Pessoa Jurídica ou o cadastro necessita ser do tipo CorporateUser. Caso o mesmo tente realizar a integração com uma conta de Pessoa Física, será retornado o erro “Forbidden. User should be a corporate user to access”.

Sendo assim necessária a criação de uma nova conta do tipo PJ pelo links abaixo:
Ambiente de Staging = https://staging.loggi.com/contas/criar/
Ambiente de Prod = https://www.loggi.com/contas/criar/

Configuração do Header

Uma forma correta de configuração:

Exemplo do header:

Header Value
======== =================
Authorization ApiKey email:api_key

Dica: Sempre verificar se o value não possui espaços em excesso.

Como formular uma boa string de endereço

Uma boa string de endereço conterá o máximo de informações capazes de serem lidas por um humano para o máximo de contexto possível.

e.g. de uma boa string de endereço:

e.g. de uma boa string de endereço:

R. Minas Gerais, 236 - Higienópolis, São Paulo - SP, 01244-010, Brasil
-   ----------   ---    ----------    -------   ---   -------    ----
1       2         3         4            5       6       7         8
  1. R.: tipo de logradouro
  2. Minas Gerais: logradouro, nesse caso, o nome da rua
  3. 236: número
  4. Higienópolis: bairro
  5. São Paulo: cidade
  6. SP: estado
  7. 01244-010: cep, código postal
  8. Brasil: país

Dica: se você usa o serviço de localização do Google Maps (geocoding), o campo formatted_address tende a ser uma ótima string de endereço.

Endereço ruim

Caso seja enviado uma string de endereço ruim, pode ser retornado alguns dos seguintes erros:

  • CEP inválido, tente novamente.
  • Local fora da área de cobertura para a cidade São Paulo, caso você esteja fazendo pedidos fora de São Paulo, o nome da sua cidade virá aqui
  • Não deve ser enviado complemento dentro do endereço. Para isso existe o campo “complement” exclusivo para isso. Exemplo de endereço que NÃO deve ser enviado:R. Minas Gerais, 236 Bloco 3 ap 63 - Higienópolis, São Paulo - SP, 01244-010, Brasil

Otimizando endereços

Para obter maior precisão e mitigar possíveis erros, recomendamos o uso de Latitude e Longitude em conjunto com o endereço completo. Nossa API usa os dois dados para resolver melhor o endereço.

Abrangência e amplitude de entrega

No momento da criação do pedido, recomendamos que o endereço de coleta e endereço das entregas, estejam dentro do mesmo município. Dependendo do município, não há garantia de entrega nas cidades vizinhas.
Grande SP é 100% coberta pickup dentro desta área.

Sendo assim, dentro do mesmo município, através da consulta de estimativa de pedidos (mutation EstimateCreateOrder) ela deverá retornar sem erro.

Entregas em condomínios

Gmaps não resolve endereços internos de condomínios, logo, recomendamos colocar o número do condômino no campo endereço e passar o ponto específico e outros detalhes no campo Instructions.

Monitorando um pedido

Consultar sempre o status do pedido, caso o status do pedido não seja cancelado (cancel), cancelado com cobrança(cancelled with charge) ou perdido(dropped), acompanhar os andamentos da entrega através do histórico dos status dos pacotes.

O estado do pedido pode ser obtido com no nó status dentro do OrderNode. Para isso, você pode usar qualquer query que retorne esse tipo de nó;

query {
    packageOrder(packageId: 80455) {
        status
    }
}

Para obter o histórico do pacote, o método a ser chamado é:

query {
  packageHistory(packageId: 55976765, forCompany: true) {
    signatureUrl
    signedByName
    statuses {
      status
      statusDisplay
      detailedStatusDisplay
      statusCode
      updated
    }
  }
}

Passar o parâmetro forCompany: true para indicar que a chamada deve encontrar por pacotes feito por outros usuários da mesma Company (e não só os do seu usuário)

Dica: Também é possível obter um status do ponto de parada do pacote, passando o campo Waypoint dentro do nó packages.

Diagrama de Status

Pacote

Código

Status

Quando acontece?

Status finalizador?

0

Não disponível

Casos em que o ponto de entrega é finalizado manualmente por algum agente loggi (CX)

S

2

Entregue

Quando o pacote é entregue com sucesso

S

3

Retirado

Pick Up (produto retirado na loja pelo mensageiro)

4

Indo retirar

Quando o entregador aceitou a rota e está indo retirar o pacote

5

Em rota de entrega

Saindo do ponto de coleta indo para os destinos

7

Indo para retorno

Retornando para ponto de coleta (quando necessário)

9

Retornado para o cliente

Pacote em que houve insucesso de entrega para o destinatário e foi devolvido com para o embarcador.

S

11

Recusado pelo destinatário

Destinatário se recusa a receber

12

Destinatário ausente

Ninguém atende o mensageiro no ponto de entrega

13

Endereço errado

Mensageiro informa que o Endereço Não Existe

15

Pacote extraviado

Casos em que o entregador é assaltado durante o percurso

S

16

Falha

Pacote não adicionado a uma rota

17

Pacote cancelado

A empresa cancelou o envio do pacote e ou entregador chegou no local e foi informado que por algum motivo o pedido foi cancelado, seja ele por cliente final ou embarcador

18

Pacote muito grande

Casos em que o entregador chega até o local de retirada e por algum motivo (peso ou tamanho) o mesmo não consegue fazer o transporte

19

Pacote não encontrado

Mensageiro chegou ao local de retirada e o pacote não foi encontrado, situação parecida com a de pacote cancelado

20

Roubo / Furto

Casos em que o entregador é assaltado durante o percurso

23

Entrega prejudicada

O entregador teve algum incidente para entregar o pacote(passou mal, desistiu por causa da distância, acidente e etc)

31

Pacote não retirado

Ninguém retirou no ponto A ou outro ponto de coleta

Waypoints

Código

Status

Quando acontece?

Status finalizador?

waypoint_status_allocating

Allocating

Esse ponto da rota Está em Alocação

waypoint_status_going_to_deliver

Going to deliver

Indo para o ponto em Questão B, C, D, etc

waypoint_status_delivering

Delivering

Chegou no ponto em questão para entrega

waypoint_status_delivered

Delivered

Entregou o pacote do ponto em questão

S

waypoint_status_failed

Failed

Hove uma falha na entrega (ver status do pacote)

S

Pedido

Código

Status

Quando acontece?

Status finalizador?

waiting_slo

Aguardando alocação

Pedido lançado e aguardando o processo de entrar em alocação

allocating

Em alocação

Procurando algum mensageiro que aceite a corrida

accepted

Aceita

Mensageiro aceitou a corrida

started

Iniciada

Manifestação de PickUp

finished

Terminada

Pacotes Entregues/Cancelados

S

cancelledWithCharge

Cancelada com cobrança

Rota cancelada após um mensageiro estar alocado (independente do tempo)

S

cancelled

Cancelada

Rota cancelada antes da alocação do mensageiro

S

dropped

Perdida

Rota não foi alocada dentro do tempo limite

S

droppedThenCancelled

Perdida e cancelada

Não foi alocada e foi cancelada

S

awaiting_completion

Aguardando Finalização

Normalmente quando um pacote ainda está com o entregador e irá entregar no outro dia.

merged

Pedido com pacotes agrupados

Quando dois pedidos são acoplados em um (via interface)

Tabela de Verificação

Caminho feliz

status 1

status 2

status 3

status 4

pedido

allocation

accepted

started

fiinished

waypoint

allocation

going to deliver

delivering

delivered

package

allocation

indo retirar

em rota de entrega

entregue

Realizando estimativas

Através da mutation estimateCreateOrder é possível obter o custo total da rota, tempo estimado da entrega e distância total a ser percorrida. O campo originalIndex fornece a ordem informada pelo cliente antes da execução da chamada.

O argumento shouldExecute informa se a mudança descrita na mutation deve ser executada (shouldExecute: true) ou se é apenas uma estimativa (shouldExecute: false).

Ao executar estimativas, é importante notar dois campos principais:

diff: mostra a diferença pós edição, tais como preço e campos originais e novos dentro dos packages
packagesDraft: mostra uma lista dos packages pós edição, com seus respectivos estados (através do campo draftStatus)

Cancelamento de pedidos

Para o cancelamento de pedidos, recomendamos que seja usada a mutation retailEditOrder, passando True para Cancellation e sholdExecute

Cancelamento de pacotes

Um pacote pode ser cancelado até o entregador realizar o check-in no local de entrega. Esta é a regra, mas também há um nó que indica se o package pode ser cancelado, ele se chama isRemovable e fica dentro do PackageNode.

Pontos de retorno

Caso exista pacote para retornar: Ao fazer um EDIT de Cancelamento de Order, adicionar "shouldAddReturn" colocando o ponto de retorno (o mesmo ponto do pickup) assim fica fácil de acompanhar o retorno desse mensageiro com a mercadoria.
vide doc da API:

https://docs.api.loggi.com/reference/pedidos#edi%C3%A7%C3%A3o-de-pedido

Protocolo Digital

O link com a imagem digital da assinatura do cliente expira em 10 min. Logo, o ideal é conseguir baixar a imagem e salvar no mesmo momento que o acesso for feito via API.
Ou fazer uma chamada quando tiver a intenção de buscar a imagem de comprovante de recebimento.
Para o protocolo Digital ser habilitado para a empresa, é necessário entrar em contato com o email do [email protected] informando o ID da company e solicitando a habilitação do mesmo.

Rota otimizada

Quando um pedido com mais de 2 pacotes é criado, a API realiza a roteirização/otimização das entregas por default. Vale ressaltar que não é necessário a criação de um estimateCreateOrder apenas para otimizar a rota, visto que o createOrder realiza este papel.

Definição de Tracking Key

O código de rastreamento é definido pelo usuário no momento da criação do pedido (Create Order), ele é o campo tracking_key (formato String). Exemplo de tracking_key: LR-CD-0301.

Retentativa

Trabalhamos para que erros não aconteçam, mas eles podem acontecer. Caso tenha recebido erros “Ocorreu [...]“, tente implementar a retentativa.
Recomendamos que faça 3 retentativas, com 10 minutos de diferença entre cada requisição. Para evitar duplicidade de pedidos, utilize o campo de tracking_key definido acima para verificar se o pedido foi criado, apesar da mensagem de erro, e refazer a requisição, em caso de fato não tenha sido criado.