ATENÇÃO

Essa API está obsoleta!

Em fev/2017 lançaremos a documentação da nova API baseda em GraphQL.

Intro

Bem vindo a API da Loggi.

Quaisquer dúvidas, favor encaminhar via email para api@loggi.com

A grosso modo trata-se de uma API Restful, na medida do possível e do pragmático. Via de regra respeitam-se os verbos de HTTP, bem como seus códigos de retorno.

Todos os requests devem ser autenticados pela chave de API.

Todos as respostas são no formato JSON. Exceto em alguns casos de erro (503, 410).

Payloads para POST e PUT devem ser feitos no corpo da requisição codificados como JSON.

A documentação da API do Loggi Pro está em : http://api.docs.dev.loggi.com/spec/. De qualquer maneira todos os tópicos desta página de Intro valem para o pro.

Ambientes

Disponibizamos um ambiente de homologação, no qual você pode e deve testar a sua integração.

Algumas observações sobre esse ambiente:

  • Embora tentemos manter um uptime de 100%, podemos ter outages curtos, em função da execução de outros testes e releases.
  • Ele é um ambiente não transacional. Apesar de funcional nenhuma cobrança é feita. Ou seja, você pode usá-lo sem medo de incorrer em custos reais.
  • O ambiente não dispara emails.
  • Em casos raros podemos zerar ou modificar o banco inteiro. Ou seja, é possível que você tenha que fazer o seu setup mais de uma vez (como criação de contas, etc). Trata-se de um evento raro, mas é possível que ocorra durante seus testes.

Em staging todas as URIs serão: https://staging.loggi.com/[ path da URI]

Produção tem como base: https://www.loggi.com/[ path da URI]

Headers

Todas as requisições devem ter o header:

'Content-Type: application/json;charset=UTF-8'

Autenticação

Todas as requisições, exceto, é claro, as de login e logout deverão estar autenticadas. A autenticação é feita através de um cabeçalho da requisição. O cabeçalho se chama “Authorization” e seu conteudo deve ser:

ApiKey [email da conta]:[chave da API da conta]

Por exemplo, para um usuario com email de arthur@loggi.com e chave de api de 1234 o cabeçalho será:

ApiKey arthur@loggi.com:1234

Obtendo sua Chave de API

Para obter sua chave de api:

  • Crie sua conta normalmente pela UI do site.

  • Logado em sua conta vá até a url:

    https://www.loggi.com/contas/haxor/
    

E você verá sua chave.

Fluxo de Pedidos

O fluxo de pedidos tem duas etapas. Inicialmente, faz-se um orçamento. Se o preço e tempo de ETA forem satisfatório, efetiva-se o orçamento, transformando-o em um pedido.

O orçamento é uma etapa importante: garante que estamos em acordo quanto aos pontos de entrega, os valores e o tempo para finalização.

Um pedido poderá ser acompanhado, obtendo-se um ETA detalhado de cada ponto, bem como o geo posicionamento do motorista.

Fluxo resumido

De ponta a ponta, o fluxo até a finalização de um pedido é:

  1. Login e pegar uma chave de api
  2. Escolher ou criar um meio de pagamento, obtendo um id
  3. Fazer um orçamento, obtendo a identificação do orçamento
  4. Efetivar o orçamento com a identificação obtida em #3
  5. Acompanhar o pedido com o ID do pedido obtido em #4

Para fazer um orçamento / pedido você precisará listar um método de pagamento.

Orçamentos são guardados na base de dados. Assim sendo, pode-se fazer vários pedidos com o mesmo orçamento, por exemplo, para entregas recorrentes.

Uma vez feito o pedido, ele poderá ser cancelado sem taxas, desde que um mensageiro não tenha aceito seu pedido.

Modelos De Dados: Erros de Validação

A API segue algumas convenções.

Em caso de erros ligados a requisição (essencialmente 400) a resposta trará:

  • Uma propriedade boleana “success” como false.
  • Um hash de nome “errors”. As chaves desse hash indicam o nome do campo / dado inválido. Seu valor retorna uma lista de uma ou mais mensagens detalhando o erro.
  • Se o erro não está restrito a um campo, uma chave __all__ será utilizada.

Modelos de Dados: Listas

Para requisições de listagem de recursos o seguinte modelo é utilizado:

{
   "meta":{
      "limit":20,
      "next":null,
      "offset":0,
      "previous":null,
      "total_count":0
   },
   "objects":[
     ... listed objects here....
   ]
}

Aonde:

  • meta.next: a URI da próxima página de resultados, se houver.
  • meta.previous: a URI da página de resultados anterior, se houver.
  • meta.limit: quantos resultados estão sendo retornados por requisição
  • meta.offset: o número absoluto de offset desta página.
  • objects: Uma lista com a representação individual dos recursos.

Com os atributos de meta é possível paginar / iterar sobre um número de resultados grandes. Você poderá tamber enviar como parâmetros na URI os valores de limit e offset, criando assim sua própria lógica de paginação.

Atenção: a representação de cada recurso listado em objects pode ser parcial ou integral, dependendo da complexidade deste.