13.1. Gerando link de rastreamento

Para gerar um link de rastreamento é preciso realizar a requisição para a API usando método POST para o seguinte endpoint:

https://api.maplink.global/tracking/v1/orders

Os seguintes headers são necessários

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer token'

Onde Token é o access token obtido na autenticação.

Em body são enviados todos os parâmetros necessários para gerar o link.

Body e Parâmetros da Request

Parâmetros obrigatórios

description- Descrição do pedido.
status - Objeto com dados sobre o status do pedido.
- value - Valores
  possíveis: ["PREPARING", "ON_THE_WAY", "DONE", "NOT_DONE", "CANCELLED"].
- label - Texto personalizado para ser exibido na página de rastreio.
destination - Objeto contendo os dados do local de destino.
- road - (Opcional) Nome da rua do local de destino.
- number - (Opcional) Número do local de destino.
- city - (Opcional) Cidade do local de destino.
- zipCode - (Opcional) CEP do local de destino.
- state - (Opcional) Objeto contento dados do local de destino.
  - code - Sigla do estado.
  - name - Nome do estado.
- mainLocation - Objeto contento as coordenadas do local de destino.
  - lat - Coordenada da latitude em graus decimais.
  - lon - Coordenada da latitude em graus decimais.

Exemplo de requisição com parâmetros obrigatórios

{
    "description": "Product Test",
    "status": {
        "value": "PREPARING",
        "label": "Estamos preparando o seu pedido"
    },
    "destination": {
        "mainLocation": {
            "lat": -22.72725697031394,
            "lon": -47.636846753567944
        }
    }
}

Parâmetros opcionais

companyName - Nome da empresa.
number - Número do pedido.
theme - Tema que será usado para personalizar a página de rastreamento. Caso não seja informado, o tema white-label será aplicado.
estimatedArrival - Estimativa de entrega. Formato “yyyy-MM-ddTHH:mm:ss”. Exemplo: "2022-11-22T10:00:00"
totalValue - Objeto contendo o valor total do pedido.
- value - Número inteiro representando o valor total do pedido.
- currency - Tipo de moeda. Para Real, utilize BRL
driver - Objeto contendo os dados do motorista
- name - (Opcional) Nome do motorista
- image- (Opcional) URL da foto do motorista para ser exibida no site
- currentLocation - Objeto com as coordenadas iniciais do motorista.
  - lat - Coordenada da latitude em graus decimais.
  - lon - Coordenada da longitude em graus decimais.

Observação: Se o status do pedido for ON_THE_WAY, o parâmetro driver passa a ser obrigatório.

origin - Objeto contendo os dados do local de origem.
- road - (Opcional) Nome da rua do local de destino.
- number - (Opcional) Número do local de destino.
- city - (Opcional) Cidade do local de destino.
- zipCode - (Opcional) CEP do local de destino.
- state - (Opcional) Objeto contento dados do local de destino.
  - code - Sigla do estado.
  - name - Nome do estado.
- mainLocation - Objeto contento as coordenadas do local de destino.
  - lat - Coordenada da latitude em graus decimais.
  - lon - Coordenada da latitude em graus decimais.

Exemplo de requisição com parâmetros opcionais

{
  "number": "1232132132143438",
  "description": "Product Test",
  "estimatedArrival": "2022-11-22T10:00:00",
  "companyName": "Maplink",
  "totalValue": {
    "value": 23.12,
    "currency": "BRL"
  },
  "status": {
    "value": "ON_THE_WAY",
    "label": "Pedido em trânsito"
  },
  "origin": {
    "road": "Alameda Campinas",
    "number": "579",
    "city": "São Paulo",
    "zipCode": "01419001",
    "state": {
      "code": "SP",
      "name": "São Paulo"
    },
    "mainLocation": {
      "lat": -22.7342864,
      "lon": -47.6480644
    }
  },
  "destination": {
    "road": "R. Menina Rosana",
    "number": "70",
    "city": "Itajaí",
    "zipCode": "88304250",
    "state": {
      "code": "SC",
      "name": "Santa Catarina"
    },
    "mainLocation": {
      "lat": -22.72725697031394,
      "lon": -47.636846753567944
    }
  },
  "driver": {
    "name": "Maplink BR",
    "image": "https://example.com",
    "currentLocation": {
      "lat": -23.564515,
      "lon": -46.652681
    }
  },
  "theme": "DEFAULT"
}

Exemplo de resposta

A resposta irá ter a seguinte estrutura:

{
    "id": "63a1b72fd2b7520ade692253",
    "url": "https://tracking.maplink.global/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjIjoicUJQRVJzWXBHdUJwOWtzeEExRUduY0lZbFZNOFVMZWUiLCJpZCI6IjYzYTFiNzJmZDJiNzUyMGFkZTY5MjI1MyIsImlhdCI6MTY3MTU0MjU3NX0.NzncB9t_1ShqnlbbS3O3gGt8E0_rloxKrMrmVDwcnQU"
}

Onde:

id- ID de referência para o pedido;
url- Link para a página de rastreio

Página de rastreamento

Abaixo o modelo da página de rastreamento white-label:

Consultar pedido

Para consultar o pedido, bastar enviar uma requisição com o método GET para o seguinte endpoint:

https://api.maplink.global/tracking/v1/orders/{{trackingId}}

Onde {{trackingId}} é o ID do pedido.

Os pedidos e os links de rastreamento ficam disponíveis para consulta durante o período de 7 dias.

Excluir pedido

Para excluir um pedido, bastar enviar uma requisição com o método DELETE para o seguinte endpoint:

https://api.maplink.global/tracking/v1/orders/{{trackingId}}

Onde {{trackingId}} é o ID do pedido.