Suivi de flotte

Ce que ça fait

• Véhicules et conducteurs : vos motos, voitures et camionnettes, avec qui les conduit et leur dernière position connue.
• Positions : votre appli livreur envoie ses positions GPS par lots ; N-Ways les garde comme historique de trajet.
• Livraisons (tâches) : un enlèvement et un point de livraison, assignés à un véhicule, avec une heure d’arrivée que N-Ways tient à jour d’après la position du livreur, le trafic en direct et les incidents signalés.
• Liens de suivi : une page que votre client ouvre pour voir arriver le livreur, sans appli ni connexion.
• Webhooks : votre serveur est prévenu quand une livraison est assignée, que le livreur arrive, que la livraison est faite ou a échoué, ou qu’un véhicule ne donne plus de nouvelles.
• Alertes : prévenu par e-mail, notification ou webhook quand un véhicule sort de sa zone, entre dans une zone, ne donne plus de nouvelles ou s’arrête trop longtemps ; transmises vers Excel, Google Sheets ou Telegram.

Adresse de base : https://nways.ng/maps/v1/fleet. Les appels Flotte modifient vos données : utilisez donc une clé restreinte aux adresses IP de vos serveurs, ou à votre appli livreur (package Android et SHA-1, ou bundle ID iOS). N’utilisez jamais une clé Flotte dans une page web.

Une livraison du début à la fin

1. Ajoutez vos véhicules une fois, avec vos propres identifiants : POST /vehicles {"id": "bike-17", "mode": "motorcycle"}. motorcycle désigne un okada commercial : ses heures d’arrivée respectent les interdictions d’okada.
2. Créez la livraison avec votre numéro de commande comme identifiant : POST /tasks, avec le dropoff (et un pickup si le livreur doit d’abord récupérer le colis). Donnez vehicleId pour l’assigner tout de suite, ou plus tard avec POST /tasks/{id}/assign. Gardez vos boutiques et entrepôts comme lieux de retrait et envoyez pickupPlaceId au lieu d’un pickup. Vos clients et leurs adresses reviennent avec GET /customers, pour leur prochaine livraison.
3. Modifiez-la si les plans changent : PATCH /tasks/{id} avec seulement ce qui change (le lieu de livraison, l’heure limite, le destinataire…). Tout peut changer jusqu’au retrait ; ensuite, seulement notes et dueAt. Le lien de suivi reste le même, l’heure d’arrivée est recalculée, le livreur est prévenu et vous recevez task.updated.
4. Envoyez les positions depuis l’appli livreur toutes les 5 à 15 secondes pendant une livraison : POST /locations avec jusqu’à 1 000 positions. Une appli restée hors connexion envoie ce qu’elle a gardé en mémoire (jusqu’à 24 heures en arrière).
5. Partagez le lien : le trackingUrl de la tâche (ou POST /tasks/{id}/share pour en obtenir un nouveau) va dans votre SMS ou votre message WhatsApp au client.
6. Marquez les étapes : POST /tasks/{id}/pickup quand le livreur a le colis, puis /complete (ou /fail, /cancel). La tâche passe d’elle-même à arriving quand le livreur est proche.

# Créer une livraison, assignée à bike-17
curl -X POST "https://nways.ng/maps/v1/fleet/tasks" \
  -H "X-NWays-Api-Key: VOTRE_CLE_SERVEUR" -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"}}'

# L’appli livreur envoie sa position
curl -X POST "https://nways.ng/maps/v1/fleet/locations" \
  -H "X-NWays-Api-Key: VOTRE_CLE_APPLI" -H "Content-Type: application/json" \
  -d '{"updates": [{"vehicleId": "bike-17", "lat": 6.5981, "lng": 3.3460, "speedMps": 6.2, "heading": 80}]}'

# Où est-il, et quand arrivera-t-il ?
curl "https://nways.ng/maps/v1/fleet/tasks/order-1041" -H "X-NWays-Api-Key: VOTRE_CLE_SERVEUR"

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('À envoyer au client :', task.trackingUrl)

Heures d’arrivée

L’eta d’une tâche donne l’heure d’arrivée (at), le temps et la distance restants, la part du temps due au trafic (trafficDelayS) et, avant l’enlèvement, l’heure à laquelle le livreur atteint le lieu d’enlèvement (pickupAt). Elle est recalculée à chaque nouvelle position (au plus toutes les 10 secondes par tâche), avec le trafic en direct et les incidents signalés, et vaut null tant qu’aucune position n’est arrivée.

Liens de suivi

Un lien de suivi comme https://nways.ng/t/3fT9kQ2xVbN7LmP0aZc4RwYe ouvre une page avec le livreur sur la carte, le point de livraison et l’heure d’arrivée, en anglais ou en français (le lang de la tâche), sous votre brandName (PUT /settings). Elle n’affiche ni nom ni numéro de téléphone, et ne montre le livreur que pendant la livraison. Un lien fonctionne 72 heures, ou jusqu’à une heure après la fin de la livraison. Pour construire plutôt votre propre page, voyez l’exemple de suivi de livraison.

Vos données

• Les positions sont gardées comme historique de trajet pendant retentionDays (30 par défaut, de 1 à 90), puis supprimées. GET /vehicles/{id}/history les renvoie.
• Les heures d’arrivée et les données de trafic ne servent qu’à ce trajet : elles sont effacées quand la tâche se termine.
• Vos positions n’alimentent le trafic en direct public de N-Ways que si vous activez shareTraffic ; elles sont alors utilisées de façon anonyme, comme celles de n’importe quel téléphone. C’est désactivé tant que vous ne l’activez pas.
• Dites à vos livreurs que leur position est partagée pendant leur travail, comme l’exige votre loi locale sur la protection des données.

Limites

6 000 appels Flotte par minute et par clé par défaut ; jusqu’à 1 000 positions dans un seul POST /locations ; jusqu’à 10 points de réception de webhooks. Les identifiants sont les vôtres : de 1 à 64 lettres, chiffres et _ . : -, uniques dans votre projet. Quotas et limites