Seguimento de frota

O que faz

• Veículos e condutores: as suas motas, carros e carrinhas, com quem os conduz e a última posição conhecida.
• Posições: a sua aplicação de estafeta envia as posições GPS em lotes; o N-Ways guarda-as como histórico de viagem.
• Entregas (tarefas): uma recolha e um ponto de entrega, atribuídos a um veículo, com uma hora de chegada que o N-Ways mantém atualizada a partir da posição do estafeta, do trânsito em tempo real e dos incidentes comunicados.
• Ligações de seguimento: uma página que o seu cliente abre para ver o estafeta chegar, sem aplicação nem início de sessão.
• Webhooks: o seu servidor é avisado quando uma entrega é atribuída, o estafeta está a chegar, a entrega é concluída ou falha, ou um veículo deixa de dar sinal.
• Alertas: avisado por e-mail, notificação ou webhook quando um veículo sai da sua área, entra numa zona, deixa de dar sinal ou para tempo demais; reencaminhados para o Excel, o Google Sheets ou o Telegram.

Endereço base: https://nways.ng/maps/v1/fleet. As chamadas Frota alteram os seus dados, por isso use uma chave restrita aos endereços IP dos seus servidores, ou à sua aplicação de estafeta (pacote Android e SHA-1, ou bundle ID iOS). Nunca use uma chave Frota numa página web.

Uma entrega do início ao fim

1. Adicione os seus veículos uma vez, com os seus próprios identificadores: POST /vehicles {"id": "bike-17", "mode": "motorcycle"}. motorcycle designa uma okada comercial: as suas horas de chegada respeitam as proibições de okadas.
2. Crie a entrega com o seu número de encomenda como identificador: POST /tasks, com o dropoff (e um pickup se o estafeta tiver de recolher primeiro). Indique vehicleId para a atribuir de imediato, ou mais tarde com POST /tasks/{id}/assign. Guarde as suas lojas e armazéns como locais de recolha e envie pickupPlaceId em vez de um pickup. Os seus clientes e os endereços de cada um voltam com GET /customers, para a próxima entrega.
3. Altere-a se os planos mudarem: PATCH /tasks/{id} apenas com o que muda (o ponto de entrega, a hora limite, o destinatário…). Tudo pode mudar até à recolha; depois, apenas notes e dueAt. A ligação de seguimento mantém-se, a hora de chegada é recalculada, o estafeta é avisado e recebe task.updated.
4. Envie as posições a partir da aplicação de estafeta a cada 5 a 15 segundos durante uma entrega: POST /locations com até 1 000 posições. Uma aplicação que esteve sem ligação envia o que guardou (até 24 horas para trás).
5. Partilhe a ligação: o trackingUrl da tarefa (ou POST /tasks/{id}/share para obter uma nova) vai no seu SMS ou mensagem de WhatsApp ao cliente.
6. Marque as etapas: POST /tasks/{id}/pickup quando o estafeta tiver a encomenda, depois /complete (ou /fail, /cancel). A tarefa passa sozinha a arriving quando o estafeta está perto.

# Criar uma entrega, atribuída a bike-17
curl -X POST "https://nways.ng/maps/v1/fleet/tasks" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_DE_SERVIDOR" -H "Content-Type: application/json" \
  -d '{"id": "order-1041", "vehicleId": "bike-17", "pickup": {"lat": 6.5965, "lng": 3.3421, "name": "Kitchen, Ikeja GRA"}, "dropoff": {"lat": 6.6018, "lng": 3.3515, "address": "12 Allen Avenue, Ikeja"}}'

# A aplicação de estafeta envia a sua posição
curl -X POST "https://nways.ng/maps/v1/fleet/locations" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_DE_APLICACAO" -H "Content-Type: application/json" \
  -d '{"updates": [{"vehicleId": "bike-17", "lat": 6.5981, "lng": 3.3460, "speedMps": 6.2, "heading": 80}]}'

# Onde está e quando chega?
curl "https://nways.ng/maps/v1/fleet/tasks/order-1041" -H "X-NWays-Api-Key: A_SUA_CHAVE_DE_SERVIDOR"

const fleet = (path, init = {}) =>
  fetch('https://nways.ng/maps/v1/fleet' + path, {
    ...init,
    headers: { 'X-NWays-Api-Key': process.env.NWAYS_SERVER_KEY, 'Content-Type': 'application/json' },
  }).then(async (res) => {
    const data = await res.json()
    if (!res.ok) throw new Error(`${data.error.reason}: ${data.error.message}`)
    return data
  })

const task = await fleet('/tasks', {
  method: 'POST',
  body: JSON.stringify({
    id: 'order-1041',
    vehicleId: 'bike-17',
    pickup: { lat: 6.5965, lng: 3.3421, name: 'Kitchen, Ikeja GRA' },
    dropoff: { lat: 6.6018, lng: 3.3515, address: '12 Allen Avenue, Ikeja' },
  }),
})
console.log('Enviar ao cliente:', task.trackingUrl)

Horas de chegada

O eta de uma tarefa indica a hora de chegada (at), o tempo e a distância que faltam, a parte do tempo devida ao trânsito (trafficDelayS) e, antes da recolha, a hora a que o estafeta chega ao local de recolha (pickupAt). É recalculado a cada nova posição (no máximo a cada 10 segundos por tarefa), com o trânsito em tempo real e os incidentes comunicados, e é null enquanto não chegar nenhuma posição.

Ligações de seguimento

Uma ligação de seguimento como https://nways.ng/t/3fT9kQ2xVbN7LmP0aZc4RwYe abre uma página com o estafeta no mapa, o ponto de entrega e a hora de chegada, em inglês ou francês (o lang da tarefa), com o seu brandName (PUT /settings). Não mostra nomes nem números de telefone, e só mostra o estafeta enquanto a entrega decorre. Uma ligação funciona durante 72 horas, ou até uma hora depois do fim da entrega. Para criar antes a sua própria página, veja o exemplo de seguimento de entrega.

Os seus dados

• As posições são guardadas como histórico de viagem durante retentionDays (30 por omissão, de 1 a 90) e depois apagadas. GET /vehicles/{id}/history devolve-as.
• As horas de chegada e os dados de trânsito servem apenas essa viagem: são apagados quando a tarefa termina.
• As suas posições só alimentam o trânsito público em tempo real do N-Ways se ativar shareTraffic; nesse caso são usadas de forma anónima, como as de qualquer telemóvel. Está desativado enquanto não o ativar.
• Informe os seus estafetas de que a sua posição é partilhada enquanto trabalham, como exige a sua lei local de proteção de dados.

Limites

6 000 chamadas Frota por minuto e por chave por omissão; até 1 000 posições num só POST /locations; até 10 pontos de receção de webhooks. Os identificadores são seus: de 1 a 64 letras, algarismos e _ . : -, únicos no seu projeto. Quotas e limites