🔗 Branchement NED Logistique

Pour les plateformes et agences partenaires qui confient à NED des livraisons déjà confirmées avec le client. NED attribue un livreur, livre, encaisse, et vous renvoie chaque étape en temps réel.

1. Votre clé

NED vous donne une clé secrète (elle commence par ned_). Mettez-la dans chaque appel :

Authorization: Bearer ned_xxxxxxxxxxxxxxxx

Gardez-la côté serveur, jamais dans une application mobile ni une page web publique.

2. Envoyer une livraison

POST https://nedlogistiqueafrica.com/api/partenaires/commandes
Content-Type: application/json
Authorization: Bearer ned_xxx

{
  "external_id": "ZL-10452",          // obligatoire · votre numéro de commande (unique)
  "customer_name": "Aïcha Moussa",    // obligatoire
  "customer_phone": "+227 90 12 34 56", // obligatoire
  "amount": 12500,                     // obligatoire · F CFA à encaisser chez le client (0 si déjà payé)
  "quartier": "Koira Kano",
  "address": "près de la pharmacie du marché",
  "city": "Niamey",
  "items": [{ "label": "Crème visage", "quantity": 2, "unit_price": 6250 }],
  "note": "Appeler avant d'arriver",
  "delivery_date": "2026-10-22",       // facultatif · AAAA-MM-JJ (vide = aujourd'hui)
  "slot_start": "11:00", "slot_end": "13:00",  // facultatif · créneau
  "lat": 13.5137, "lng": 2.1098        // facultatif · position du client
}

Réponse :

200 { "ok": true, "already_received": false, "ned_reference": 54124, "status": "nouveau" }

• Renvoyer la même livraison (même external_id) ne crée pas de doublon : "already_received": true. Vous pouvez donc réessayer sans risque.
• Plusieurs d'un coup : { "orders": [ {...}, {...} ] } (50 maximum), réponse { "ok": true, "results": [...] }.
• Erreurs : 401 clé invalide · 400 champ manquant ou invalide (le message dit lequel).

3. Recevoir les étapes en temps réel

Donnez à NED une adresse https de votre serveur. À chaque étape, NED y envoie immédiatement :

POST https://votre-serveur/ned
Content-Type: application/json
X-NED-Event: livree
X-NED-Key: ned_xxx      // votre clé : vérifiez-la pour être sûr que c'est NED

{
  "event": "livree",
  "external_id": "ZL-10452",
  "ned_reference": 54124,
  "status": "livre",
  "at": "2026-10-21T14:32:05Z",
  "driver": { "name": "Annas Asoumane", "phone": "90000000" },
  "amount_expected": 12500,
  "amount_collected": 12500,
  "payment_method": "cash",          // cash ou mobile_money
  "delivery_date": null,
  "reason": null                     // motif si annulée, injoignable, reportée…
}

• Répondez 200 rapidement (moins de 8 secondes). Sinon NED réessaie toutes les 2 minutes, jusqu'à 10 fois.
• Un même événement peut arriver deux fois : servez-vous de external_id + event pour l'ignorer.

4. Demander l'état d'une livraison

GET https://nedlogistiqueafrica.com/api/partenaires/commandes?external_id=ZL-10452
Authorization: Bearer ned_xxx

5. Annuler une livraison

POST https://nedlogistiqueafrica.com/api/partenaires/commandes/annuler
Authorization: Bearer ned_xxx
{ "external_id": "ZL-10452", "reason": "Le client a annulé" }

Possible tant que le livreur n'est pas en route ; ensuite, appelez NED.

6. Exemple prêt à copier (Next.js / Node)

Mettez votre clé dans une variable d'environnement NED_API_KEY (jamais dans le code). Puis :

// lib/ned.ts : envoyer une course à NED (côté serveur uniquement)
const NED_URL = 'https://nedlogistiqueafrica.com/api/partenaires/commandes';

export async function envoyerANed(c: {
  id: string; client: string; telephone: string; montant: number;
  quartier?: string; adresse?: string; produits?: { label: string; quantity: number }[];
  note?: string; date?: string; debut?: string; fin?: string;
}) {
  const r = await fetch(NED_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.NED_API_KEY}` },
    body: JSON.stringify({
      external_id: c.id, customer_name: c.client, customer_phone: c.telephone, amount: c.montant,
      quartier: c.quartier, address: c.adresse, items: c.produits, note: c.note,
      delivery_date: c.date, slot_start: c.debut, slot_end: c.fin,
    }),
  });
  const data = await r.json();
  if (!r.ok || !data.ok) throw new Error(data.error ?? `NED : erreur ${r.status}`);
  return data.ned_reference as number;   // à garder avec votre commande
}

// app/api/ned/route.ts : recevoir les étapes envoyées par NED
import { NextResponse } from 'next/server';

const STATUTS: Record<string, string> = {
  attribuee: 'assignee', en_route: 'en_livraison', livree: 'livree', paiement: 'livree',
  injoignable: 'injoignable', reportee: 'reportee', annulee: 'annulee', retour: 'retour',
};

export async function POST(req: Request) {
  if (req.headers.get('x-ned-key') !== process.env.NED_API_KEY) {
    return NextResponse.json({ ok: false }, { status: 401 });   // ce n'est pas NED
  }
  const e = await req.json();
  // e.external_id = votre numéro de commande ; e.event = l'étape
  const statut = STATUTS[e.event];
  if (statut) {
    // ⬇️ remplacez par votre mise à jour en base
    // await db.commande.update({ where: { id: e.external_id }, data: {
    //   statut, livreurNom: e.driver?.name, livreurTel: e.driver?.phone,
    //   montantEncaisse: e.amount_collected, motif: e.reason } });
  }
  return NextResponse.json({ ok: true });   // répondre vite, sinon NED réessaie
}

Donnez ensuite à NED l'adresse https://votre-domaine/api/ned : chaque étape arrivera là.

Exemple rapide (curl)

curl -X POST https://nedlogistiqueafrica.com/api/partenaires/commandes \
  -H "Authorization: Bearer ned_xxx" -H "Content-Type: application/json" \
  -d '{"external_id":"TEST-1","customer_name":"Test","customer_phone":"90000000","amount":0}'

Une question ? Contactez NED Logistique.