N-WaysRéférence de l’API
Chaque point d’accès de la N-Ways Maps Platform, ses paramètres, sa réponse et ses erreurs, générés à partir de nos fichiers OpenAPI.
Sur cette page
N-Ways Maps Platform — Maps, Places and Routes API
La surface partenaire stable de la N-Ways Maps Platform (/maps/v1). Elle fait foi pour la documentation et les bibliothèques clientes ; les tests de contrat du serveur (fichiers de référence, backend/internal/partnerapi/testdata/golden) figent chaque réponse décrite ici.
Authentification. Chaque appel demande une clé d’API partenaire : X-NWays-Api-Key: nw_… (serveurs, applis) ou ?key=nw_… (navigateurs, styles de carte). Les restrictions d’API d’une clé nomment des produits ; sa restriction d’application (sites, identifiants de bundle iOS, package Android + SHA-1, adresses IP de serveurs) dit où elle peut servir. Les applis envoient X-Ios-Bundle-Identifier, ou X-Android-Package et X-Android-Cert. Les clés ne marchent que si N-Ways a activé la plateforme : quand elle est coupée, chaque appel répond 503 PLATFORM_DISABLED (avec Retry-After ; votre clé va bien), et lorsque N-Ways la réserve aux organisations invitées, la clé de toute autre organisation répond 403 PLATFORM_PREVIEW_ONLY.
Produits et facturation (SKU). tiles (tuiles de carte ; SKU tiles par tuile et map_loads par lecture de style), static_maps, geocode (géocodage, inverse, codes postaux, GhanaPost, Plus Codes ; un lot compte chaque code), autocomplete (facturé par session), address_validation, search (lieux ; SKU search de base, places_contact, places_atmosphere selon les champs demandés), routing (SKU routing, et routing_advanced pour les itinéraires avec trafic, okada/keke/danfo/moto/camionnette/bateau/train, plus de 10 étapes ou les tarifs), route_matrix (facturé par élément), route_optimization, fares, traffic. Les polices sont gratuites avec toute clé Maps.
Conventions. Les coordonnées entrent en {"lat": 6.45, "lng": 3.39} (ou lat,lng dans une requête) et sortent en GeoJSON [lng, lat]. Distances en mètres, durées en secondes, montants dans l’unité principale de la devise. lang=en|fr|pt (pt : portugais européen). fields= (une liste séparée par des virgules ; a.b atteint l’intérieur des objets) ne garde que ces champs de chaque résultat et, pour les lieux, fixe le SKU. Dans v1, des champs sont seulement ajoutés ; les changements incompatibles arrivent en /maps/v2 avec 12 mois de recouvrement.
Erreurs. Une seule enveloppe pour les erreurs de clé, de quota et de produit : {"error": {"code": 400, "status": "INVALID_ARGUMENT", "reason": "LAT_LNG_REQUIRED", "message": "…", "details": […]}}. reason est stable (fiez-vous-y) ; message dit exactement ce qui s’est passé et comment corriger ; details contient l’ErrorInfo de Google (la raison, domain: nways.ng, et metadata avec les faits : docs et, selon la raison, ce qui a été vu et ce qui est permis, quel plafond et quand il se réinitialise) et un lien Help vers l’entrée de la raison sur https://nways.ng/developers/errors. Les refus portent les en-têtes CORS de la page appelante, pour que le code du navigateur puisse les lire. Raisons de plateforme, de clé et de quota, dans l’ordre où elles sont vérifiées : PLATFORM_DISABLED (503), API_KEY_MISSING, API_KEY_INVALID (une clé que N-Ways n’a jamais émise), API_KEY_REVOKED (supprimée, ou l’ancienne valeur d’une clé régénérée) (401) ; PLATFORM_PREVIEW_ONLY, ORGANISATION_CLOSED, ORGANISATION_SUSPENDED, API_ACCESS_OFF (l’organisation gère ses livraisons sur N-Ways sans l’API), API_TURNED_OFF (N-Ways a coupé l’API de l’organisation ; le message en donne la raison), PROJECT_SUSPENDED, API_KEY_PAUSED, API_KEY_SERVICE_BLOCKED, API_KEY_HTTP_REFERRER_BLOCKED, API_KEY_IP_ADDRESS_BLOCKED, API_KEY_IOS_APP_BLOCKED, API_KEY_ANDROID_APP_BLOCKED (403) ; RATE_LIMIT_EXCEEDED, QUOTA_EXCEEDED, TEMPORARILY_BLOCKED (429) ; BILLING_DISABLED (402 : l’allocation gratuite du mois est épuisée et il ne reste pas de crédit : ajoutez du crédit dans la console, Facturation) ; BACKEND_ERROR (503). Les raisons propres aux produits sont listées avec chaque opération. Toute opération peut aussi répondre NOT_FOUND (chemin inconnu), INVALID_JSON et BODY_TOO_LARGE (corps de requête), INTERNAL (500 : envoyez le X-Request-Id) et, là où des itinéraires sont calculés, ROUTING_UNAVAILABLE (503, avec Retry-After). Les trajets en okada, moto, keke et danfo que la loi interdit répondent 422 avec OKADA_BANNED_ORIGIN, OKADA_BANNED_DESTINATION, OKADA_BANNED_STOP, OKADA_BANNED_ROUTE ; MOTORBIKE_BANNED_ORIGIN, MOTORBIKE_BANNED_DESTINATION, MOTORBIKE_BANNED_STOP, MOTORBIKE_BANNED_ROUTE ; KEKE_BANNED_ORIGIN, KEKE_BANNED_DESTINATION, KEKE_BANNED_STOP, KEKE_BANNED_ROUTE ; DANFO_BANNED_ORIGIN, DANFO_BANNED_DESTINATION, DANFO_BANNED_STOP, DANFO_BANNED_ROUTE (l’interdiction figure dans le message).
En-têtes. Chaque réponse porte X-Request-Id (envoyez-le au support). Les appels autorisés portent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes) ; un 429 et PLATFORM_DISABLED portent Retry-After.
Hôtes. api.nways.ng/maps/v1 pour tout. Les styles hébergés lisent les archives PMTiles et les polices sur le CDN tiles.nways.ng/maps/v1 (/tiles/{tileset}.pmtiles, /tiles/countries.json, /fonts/…, mêmes chemins) : une copie publique, sans clé et sans décompte ; votre clé est vérifiée et le chargement de carte compté à la lecture du style. Les URL .mvt d’une tuile restent sur l’API, avec clé. Quand le moteur d’itinéraires est indisponible, itinéraires, matrices et optimisation répondent 503 ROUTING_UNAVAILABLE avec Retry-After : renvoyez la même requête.
Limites de débit (valeurs par défaut, par clé et par minute) : tiles 6 000, static_maps 600, geocode 600, autocomplete 1 200, address_validation 300, search 600, routing 300, route_matrix 3 000 éléments, route_optimization 60, fares 120, traffic 60.
Attribution. Les réponses issues d’OpenStreetMap portent attribution ; affichez « © les contributeurs d’OpenStreetMap » partout où vous montrez les données (l’ODbL l’exige). Voir https://nways.ng/developers/terms.
| Adresse de base | https://nways.ng/maps/v1 |
| Version | 1.0.0 |
| Fichier OpenAPI | partner-v1.openapi.yaml · JSON |
| Points d’accès | Description |
|---|---|
GET /styles/{style}.json | Un style de carte hébergé (un chargement de carte) |
GET /tiles/countries.json | Les archives de tuiles de chaque pays |
GET /tiles/{tileset}.pmtiles | Lire l’archive PMTiles d’un pays (requêtes par plages) |
GET /tiles/{tileset}/{z}/{x}/{y}.mvt | Une tuile vectorielle |
GET /fonts/{stack}/{range}.pbf | Glyphes de police pour les libellés de la carte (gratuit) |
GET /staticmap | Une image de carte |
GET /geocode | Rechercher des lieux, des adresses et des codes |
GET /reverse | Ce qui se trouve à un point |
GET /postcodes/{code} | Un code postal NIPOST |
POST /postcodes/batch | Jusqu’à 100 codes postaux NIPOST à la fois |
GET /ghanapost/{code} | Une adresse GhanaPost GPS |
GET /pluscodes/{code} | La zone d’un Plus Code et ce qui s’y trouve |
GET /autocomplete | Suggestions pendant la saisie (facturées par session) |
POST /addresses/validate | Cette adresse existe-t-elle, où se trouve-t-elle, quelle est sa forme correcte ? |
GET /places/nearby | Commerces et lieux près d’un point |
GET /places/search | Commerces et lieux par texte |
GET /places/{id} | Les détails d’un lieu |
POST /routes/compute | Un itinéraire, avec jusqu’à 25 arrêts intermédiaires |
POST /routes/matrix | Temps de trajet de plusieurs origines vers plusieurs destinations (par élément) |
POST /routes/optimize | Quel véhicule visite quels arrêts, et dans quel ordre |
GET /fares/estimate | Ce que coûte une course |
GET /traffic | Trafic en direct dans une zone |
N-Ways Maps Platform — Fleet and logistics API
La suite logistique de N-Ways Maps Platform (produits partenaires fleet et traffic_feed). Chaque appel exige une clé API partenaire qui inclut le produit ; les clés ne fonctionnent que lorsque N-Ways a activé pour vous l’accès partenaire.
Authentification. Envoyez la clé sous la forme X-NWays-Api-Key: nw_… (serveurs, applications livreur) ou ?key=nw_…. Les appels fleet écrivent vos propres données (véhicules, tâches, webhooks) : utilisez donc une clé restreinte aux adresses IP de vos serveurs ou à votre application livreur (package Android + SHA-1, bundle id iOS). Navigateurs : uniquement la page de suivi publique.
Erreurs. Les erreurs de clé et de quota et les erreurs de produit partagent une seule enveloppe : {"error": {"code": 404, "status": "NOT_FOUND", "reason": "TASK_NOT_FOUND", "message": "…", "details": […]}} (details : l’ErrorInfo de Google avec les faits dans metadata et un lien d’aide vers la raison sur https://nways.ng/developers/errors). Raisons de plateforme et de clé : PLATFORM_DISABLED (503, Retry-After : la plateforme est désactivée, votre clé est valide), PLATFORM_PREVIEW_ONLY, API_KEY_MISSING, API_KEY_INVALID, API_KEY_REVOKED, ORGANISATION_CLOSED, ORGANISATION_SUSPENDED, API_ACCESS_OFF, API_TURNED_OFF, PROJECT_SUSPENDED, API_KEY_PAUSED, API_KEY_SERVICE_BLOCKED, API_KEY_*_BLOCKED, BILLING_DISABLED, RATE_LIMIT_EXCEEDED, QUOTA_EXCEEDED, TEMPORARILY_BLOCKED, BACKEND_ERROR. BILLING_DISABLED est un 402 : le quota gratuit du mois est épuisé et il ne reste plus de crédit (ajoutez du crédit dans la console, Facturation).
Fonctionnalités désactivées par N-Ways. N-Ways peut désactiver une fonctionnalité pour une organisation (403, le message dit pourquoi et qui contacter ; rien d’autre ne change) : DELIVERIES_OFF (nouvelles tâches), CONTRACTORS_OFF (envoi de tâches aux chauffeurs N-Ways, invitation ou recrutement), SMART_PRICE_OFF (suggestions de paie et Smart Price : envoyez vous-même payMax), WEBHOOKS_OFF (aucun envoi de webhook ; ajouter ou tester un point de terminaison est refusé), ERP_OFF (l’export des événements), TRACKERS_OFF (l’ajout de traceurs, leurs positions et alarmes ; les traceurs restent enregistrés). Les nouvelles tâches d’une organisation suspendue sont refusées avec ORGANISATION_SUSPENDED, comme ses clés ; les tâches en cours continuent.
Limites de débit. Valeurs par défaut par clé et par minute : fleet 6 000, traffic_feed 60. Les réponses portent X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Ids. Les véhicules, les conducteurs et les tâches sont désignés par vos propres ids (1 à 64 caractères parmi A–Z a–z 0–9 _ . : -), uniques par projet. Ce que N-Ways crée (webhooks, règles d’alerte et alertes, liens et invitations livreur, preuves, livraisons de webhooks) a un id opaque : un préfixe, _ et 10 lettres ou chiffres (wh_Ub3yH9sLk2, rule_…, alr_…, lnk_…, rin_…, prf_…, dlv_…). Traitez les ids comme des chaînes et ne les décomposez jamais. Les anciennes formes numérotées (wh_12, rule_7, inv_3…) restent acceptées dans les chemins jusqu’au 1er avril 2027. Les heures sont au format RFC 3339 en UTC.
Conditions sur les données. Les positions que vous envoyez sont conservées comme historique de trajets pendant retentionDays (30 par défaut, de 1 à 90), puis supprimées. Les chiffres d’heure d’arrivée estimée et de trafic ne servent qu’au trajet : ils sont effacés à la fin d’une tâche. Vos positions n’alimentent le trafic en direct public de N-Ways que si vous l’acceptez (shareTraffic, désactivé par défaut) ; elles sont alors utilisées de façon anonyme, comme celles de n’importe quel téléphone (une session par véhicule et par jour, jamais vos ids). Le flux de trafic est agrégé sur de nombreux appareils et ne contient jamais de trace.
| Adresse de base | https://nways.ng/maps/v1/fleet |
| Version | 1.0.0 |
| Fichier OpenAPI | partner-fleet.openapi.yaml · JSON |
| Points d’accès | Description |
|---|---|
GET /settings | Obtenir les paramètres de flotte du projet |
PUT /settings | Modifier les paramètres de flotte (les champs omis gardent leur valeur) |
GET /drivers | Lister les conducteurs |
POST /drivers | Ajouter un conducteur |
GET /drivers/{id} | Obtenir un conducteur |
PATCH /drivers/{id} | Modifier un conducteur |
DELETE /drivers/{id} | Supprimer un conducteur (les véhicules continuent de rouler sans conducteur) |
GET /vehicles | Lister les véhicules avec leur dernière position connue |
POST /vehicles | Ajouter un véhicule |
GET /vehicles/{id} | Obtenir un véhicule et sa dernière position connue |
PATCH /vehicles/{id} | Modifier un véhicule (driverId "" retire le conducteur) |
DELETE /vehicles/{id} | Supprimer un véhicule et son historique de trajets |
GET /vehicles/{id}/history | L’historique de trajets d’un véhicule (du plus ancien au plus récent) |
GET /vehicles/{id}/events | La chronologie d’un véhicule selon son traceur (contact mis et coupé, alimentation coupée et rétablie), la plus récente d’abord |
POST /locations | Envoyer des positions (par lots) |
GET /tasks/{id}/proofs | La preuve de livraison de la tâche (photos, signatures) et la note du livreur |
GET /proofs/{proofId} | L’image d’une preuve (JPEG, PNG ou WebP), gardée aussi longtemps que sa tâche |
GET /tasks | Lister les tâches, les plus récentes d’abord |
POST /tasks | Créer une livraison |
GET /tasks/{id} | Obtenir une tâche avec son heure d’arrivée estimée en direct |
PATCH /tasks/{id} | Modifier une livraison |
POST /tasks/{id}/assign | Assigner (ou réassigner) un véhicule — created|assigned → assigned ; événement task.assigned |
POST /tasks/{id}/pickup | Marquer comme enlevé — assigned → picked_up |
POST /tasks/{id}/complete | Marquer comme livré — assigned|picked_up|arriving → completed ; événement task.completed |
POST /tasks/{id}/fail | Marquer comme échoué — tout statut ouvert → failed ; événement task.failed |
POST /tasks/{id}/cancel | Annuler — tout statut ouvert → cancelled |
POST /tasks/{id}/pin-email | Envoyer le code PIN de livraison au client par e-mail |
GET /whatsapp/number | Si un code PIN de livraison peut aller à un numéro sur WhatsApp |
POST /tasks/{id}/area | Définir ou effacer la zone propre d’une livraison |
GET /places | Lister vos lieux de retrait (celui par défaut d’abord) |
POST /places | Ajouter un lieu de retrait (jusqu’à 200) |
GET /places/{placeId} | Obtenir un lieu de retrait |
PATCH /places/{placeId} | Modifier un lieu de retrait |
DELETE /places/{placeId} | Supprimer un lieu de retrait |
GET /customers | Lister vos clients, dernière livraison d’abord |
GET /customers/{customerId} | Obtenir un client |
DELETE /customers/{customerId} | Oublier un client et ses adresses |
GET /customers/{customerId}/addresses | Lister les adresses d’un client, dernière utilisée d’abord |
POST /tasks/{id}/share | Le lien de suivi du destinataire (un nouveau s’il a expiré ; aucun une fois la tâche terminée) |
GET /webhooks | Lister les points de réception |
POST /webhooks | Ajouter un point de réception (10 au plus) ; la réponse contient son secret de signature, affiché une seule fois |
PATCH /webhooks/{id} | Modifier l’url, les events ou le champ active d’un point de réception |
DELETE /webhooks/{id} | Supprimer un point de réception et son journal d’envois |
POST /webhooks/{id}/rotate-secret | Un nouveau secret de signature (affiché une seule fois) ; l’ancien cesse aussitôt de fonctionner |
POST /webhooks/{id}/test | Mettre en file un événement ping vers le point de réception |
GET /webhooks/{id}/deliveries | Le journal d’envois du point de réception, les plus récents d’abord (conservé 30 jours) |
POST /webhooks/{id}/deliveries/{deliveryId}/retry | Renvoyer une livraison maintenant (échouée, ou livrée et voulue de nouveau) ; ses tentatives sont gardées |
GET /alert-rules | Lister les règles d’alerte |
POST /alert-rules | Ajouter une règle d’alerte (100 au plus) |
GET /alert-rules/{ruleId} | Obtenir une règle |
PATCH /alert-rules/{ruleId} | Modifier une règle (le type reste) ; active false la met en pause et résout ses alertes ouvertes |
DELETE /alert-rules/{ruleId} | Supprimer une règle (ses alertes ouvertes sont résolues) |
GET /alert-events | Les alertes levées, de la plus récente à la plus ancienne |
GET /alert-events/{alertId} | Obtenir une alerte |
POST /alert-events/{alertId}/acknowledge | Prendre en compte une alerte ouverte (plus de rappels ; elle reste jusqu’à ce qu’elle cesse ou soit résolue) |
POST /alert-events/{alertId}/resolve | Résoudre une alerte (envoie asset.alert_resolved) |
GET /events/export | Télécharger tous les événements (CSV pour Excel ou Google Sheets, ou JSON) |
GET /traffic-feed | Vitesses routières dans un cadre (produit traffic_feed ; entreprise) |
GET /offline/regions | Régions pour lesquelles des packs hors connexion sont produits |
GET /offline/packs/{region} | Le manifeste du pack d’une région (202 pendant sa production ; redemandez après Retry-After) |
GET /offline/packs/{region}/{file} | Télécharger un fichier de pack (requêtes Range prises en charge ; ETag = son empreinte) |
GET /trackers | Lister vos traceurs, avec le nombre par état |
POST /trackers | Ajouter un traceur par son IMEI (le premier qui l’ajoute le garde) |
GET /trackers/catalog | Le catalogue des appareils, les réseaux SIM de votre pays et leurs APN, et où les appareils envoient |
POST /trackers/import | Ajouter plusieurs traceurs depuis un CSV (vérifiez d’abord avec dryRun) |
GET /trackers/setup.csv | La fiche des installateurs, les SMS de réglage de chaque traceur dans l’ordre (CSV) |
GET /trackers/forwarding | Le transfert depuis votre plateforme de suivi, ses adresses et les unités qu’elle envoie |
POST /trackers/forwarding | Activer le transfert, ou lui donner un nouveau jeton (l’ancien cesse aussitôt) |
DELETE /trackers/forwarding | Désactiver le transfert (les unités restent listées) |
POST /trackers/forwarding/units/{unitId}/add | Ajouter une unité transférée à vos traceurs (un nouveau véhicule à son nom, sauf si vous en donnez un) |
DELETE /trackers/forwarding/units/{unitId} | Oublier une unité transférée (elle revient si votre plateforme l’envoie à nouveau) |
GET /tracker-transfers | Vos demandes de transfert de traceurs ici, et les traceurs partis ailleurs |
POST /tracker-transfers | Demander un traceur qu’une autre organisation détient (propriétaires et administrateurs) |
POST /tracker-transfers/{transferId}/start | Vous faites reconnecter l’appareil maintenant (son SMS de redémarrage) ; une nouvelle connexion dans les 3 minutes le transfère |
DELETE /tracker-transfers/{transferId} | Retirer une demande |
GET /trackers/{trackerId} | Obtenir un traceur, ses étapes de configuration et ce qui ne va pas |
PATCH /trackers/{trackerId} | Modifier un traceur (son véhicule, son modèle, sa SIM) |
DELETE /trackers/{trackerId} | Retirer un traceur (n’importe qui peut alors l’ajouter) |
GET /trackers/{trackerId}/log | Le journal de l’appareil (connexions, trames brutes, champs décodés, réponses envoyées, erreurs), du plus ancien au plus récent |
GET /trackers/{trackerId}/stream | Le journal et l’état de l’appareil au fil de l’eau (server-sent events) |
POST /trackers/{trackerId}/virtual | Faire rouler un traceur virtuel pour celui-ci (son propre protocole, via la passerelle de N-Ways) |
DELETE /trackers/{trackerId}/virtual | Arrêter son traceur virtuel |
GET /trackers/{trackerId}/commands | Les commandes envoyées à un traceur (les 30 dernières), et celles qu’il accepte |
POST /trackers/{trackerId}/commands | Envoyer une commande (propriétaires et administrateurs) ; sa réponse arrive dans le journal de l’appareil |
GET /live | Chaque véhicule en ce moment, avec son livreur, son état, sa livraison en cours et ses zones |
GET /alerts | Ce qui demande votre attention, le plus urgent d’abord |
GET /routes | Où va chaque véhicule en livraison |
GET /zones | Les zones du projet (des cercles), chacune avec le nombre de véhicules qui s’y trouvent |
POST /zones | Ajouter une zone (200 au plus par projet) |
GET /zones/{id} | Obtenir une zone |
PATCH /zones/{id} | Renommer, déplacer ou redimensionner une zone (lat et lng ensemble) |
DELETE /zones/{id} | Supprimer une zone |
GET /vehicles/{id}/links | Les liens livreur du véhicule (jamais leurs adresses), du plus récent au plus ancien |
POST /vehicles/{id}/links | Un lien que le livreur ouvre sur son téléphone pour partager sa position pour ce véhicule (sans application) |
DELETE /links/{linkId} | Arrêter aussitôt un lien livreur (sa page dit alors qu’il a pris fin) |
GET /drivers/{id}/invites | Les invitations du livreur à N-Ways Business (jamais leurs codes), de la plus récente à la plus ancienne |
POST /drivers/{id}/invites | Inviter le livreur dans N-Ways Business |
DELETE /invites/{inviteId} | Retirer une invitation (son code ne marche plus) |
DELETE /drivers/{id}/app | Détacher le compte N-Ways du livreur de ce conducteur |
Fichiers
La même référence en fichiers lisibles par une machine, pour générer votre propre client ou l’importer dans un outil d’API. La collection Postman contient chaque requête avec les variables {{apiKey}} et {{baseUrl}}.