Tracking

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:

Criando um pedido e gerando o link de rastreamento

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 contendo dados do estado do local de destino.
      • code – Sigla do estado.
      • name – Nome do estado.
    • mainLocation – Objeto contendo as coordenadas do local de destino.
      • lat – Coordenada da latitude em graus decimais.
      • lon – Coordenada da latitude em graus decimais.

Exemplo 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
  • origin – Objeto contendo os dados do local de origem.
    • road – (Opcional) Nome da rua do local de origem.
    • number – (Opcional) Número do local de origem.
    • city – (Opcional) Cidade do local de origem.
    • zipCode – (Opcional) CEP do local de origem.
    • state – (Opcional) Objeto contendo dados do local de origem.
      • code – Sigla do estado.
      • name – Nome do estado.
    • mainLocation – Objeto contendo as coordenadas do local de origem.
      • lat – Coordenada da latitude em graus decimais.
      • lon – Coordenada da latitude em graus decimais.
  • 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.

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

Exemplo 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

O modelo da página de rastreamento white-label pode ser conferido abaixo:

Consultar pedido

Para consultar o pedido, basta enviar uma requisição com o método GET para o seguinte endpoint: https://api.maplink.global/tracking/v1/orders/{{trackingId}}

Onde o termo {{trackingId}} deve ser substituído pelo ID do pedido a ser consultado.

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, basta enviar uma requisição com o método DELETE para o seguinte endpoint:

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

Onde o termo {{trackingId}} deve ser substituído pelo ID do pedido a ser excluido.