Qu'est-ce qu'OXO Livraison ?

OXO Livraison est une société de livraison e-commerce au Maroc spécialisée dans le paiement à la livraison (cash on delivery). Elle ramasse les colis chez les vendeurs, les livre aux clients en encaissant le montant à la livraison, et gère le suivi en temps réel et les retours.

Qu'est-ce que le paiement à la livraison (COD) ?

Le paiement à la livraison, ou cash on delivery (COD), permet au client de payer son colis en espèces au moment de la réception. OXO Livraison collecte le paiement et le reverse au vendeur.

Dans quelles villes OXO Livraison livre-t-elle ?

OXO Livraison livre partout au Maroc, notamment à Casablanca, Rabat, Marrakech, Fès, Tanger, Agadir, Meknès, Oujda, Kénitra, Tétouan, Salé et Mohammedia.

Comment suivre mon colis OXO Livraison ?

Vous pouvez suivre votre colis en temps réel sur https://oxolivraison.com/suivi-colis en saisissant votre code de suivi.

Comment devenir vendeur ou livreur chez OXO Livraison ?

Les vendeurs peuvent créer un compte sur oxolivraison.com pour expédier leurs colis, et les livreurs peuvent postuler via la page Devenir livreur.

Documentation API

Intégrez OXO en quelques minutes

API REST publique pour créer, suivre et gérer vos colis depuis votre boutique ou ERP. Compatible YouCan, Shopify, WooCommerce, et tout système qui parle HTTP.

Base URL :https://oxolivraison.com/api/v1

Démarrage rapide

Votre premier colis en 60 secondes

1Connectez-vous et générez une clé API depuis /integrations.
2Récupérez la liste des villes (vous aurez besoin d'un ville_id ou du nom).
3Envoyez un POST avec votre clé API et les infos du colis.

bash

curl -X POST https://oxolivraison.com/api/v1/colis \
  -H "Authorization: Bearer oxo_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "destinataire": "Nadia Benali",
    "telephone": "+212661123456",
    "adresse": "12 Avenue Hassan II",
    "ville": "Casablanca",
    "produit": "Robe soirée",
    "prix_cod": 350
  }'

json

{
  "data": {
    "id": "8f3e2d1b-...",
    "code_barre": "OXO-A1B2-C3D4",
    "statut": "cree",
    "created_at": "2026-05-19T20:00:00.000Z"
  }
}

Authentification

Bearer token

Toutes les requêtes nécessitent l'en-tête Authorization: Bearer oxo_live_…. La clé n'est affichée qu'une seule fois lors de sa création — stockez-la dans un coffre-fort secret (variable d'environnement, secret manager).

bash

Authorization: Bearer oxo_live_a1b2c3d4e5f6...

Ne committez jamais votre clé dans Git. Une clé compromise peut créer des colis à votre nom — révoquez-la immédiatement depuis /integrations.

GET/v1/me

Vérifier la clé API

Retourne l'identité du marchand associé à votre clé. Pratique pour valider l'auth pendant l'intégration.

bash

curl https://oxolivraison.com/api/v1/me -H "Authorization: Bearer oxo_live_..."

json

{
  "data": {
    "id": "8320dc28-...",
    "email": "vous@boutique.ma",
    "nom": "Votre Boutique",
    "role": "merchant",
    "api_key_id": "4a76045b-..."
  }
}

GET/v1/villes

Lister les villes desservies

Retourne toutes les villes avec leurs IDs et tarifs. Utilisez le id ou le nom dans POST /colis.

json

{
  "data": [
    { "id": "bbb...", "nom": "Casablanca", "tarif_standard": "25.00", "tarif_retour": "15.00" },
    { "id": "bbb...", "nom": "Rabat",      "tarif_standard": "30.00", "tarif_retour": "18.00" }
  ]
}

POST/v1/colis

Créer un colis

Crée un nouveau colis associé à votre compte marchand. Le tarif est calculé automatiquement depuis la ville de livraison.

Corps de la requête (JSON)

destinataire

stringrequis

Nom complet du destinataire (max 200 caractères).

telephone

stringrequis

Numéro marocain au format +2126XXXXXXXX ou 06XXXXXXXX.

adresse

stringrequis

Adresse de livraison complète.

produit

stringrequis

Description du produit ou contenu du colis.

ville_id

uuid

UUID de la ville (récupéré via GET /villes).

ville

string

Nom de la ville (alternative à ville_id). Ex: "Casablanca".

prix_cod

number

Montant Paiements à collecter en MAD. 0 ou omis si pas de paiement à la livraison.

taille

enum

Une de : standard, moyen, lourd. Défaut : standard.

poids

number

Poids en kg.

notes

string

Notes internes (max 1000 caractères).

code_barre

string

Code-barres personnalisé. Laisser vide pour génération auto (recommandé).

Réponse 201 Created

json

{
  "data": {
    "id": "8f3e2d1b-7c4a-4f15-b3d8-1e2a9c6f0b75",
    "code_barre": "OXO-A1B2-C3D4",
    "statut": "cree",
    "created_at": "2026-05-19T20:00:00.000Z"
  }
}

GET/v1/colis

Lister vos colis

Liste paginée de vos colis, triés par date de création décroissante.

Paramètres de requête

limit

integer

Nombre de résultats (défaut 50, max 200).

offset

integer

Décalage pour pagination (défaut 0).

statut

enum

Filtrer par statut : cree, ramasse, en_hub, en_livraison, livre, retour, refuse.

bash

curl "https://oxolivraison.com/api/v1/colis?statut=en_livraison&limit=20" \
  -H "Authorization: Bearer oxo_live_..."

GET/v1/colis/{code}

Récupérer un colis par code-barres

Retourne les détails complets d'un colis. Seul le propriétaire (marchand) peut consulter ses colis.

bash

curl https://oxolivraison.com/api/v1/colis/OXO-A1B2-C3D4 \
  -H "Authorization: Bearer oxo_live_..."

Webhooks

Notifications en temps réel

Configurez un endpoint webhook depuis /integrations. OXO enverra un POST JSON signé HMAC-SHA256 à chaque changement de statut d'un colis.

En-têtes envoyés

X-OXO-Event

string

Type d'événement, ex. colis.status_changed.

X-OXO-Signature

string

Signature HMAC-SHA256 du body, format sha256=<hex>.

X-OXO-Timestamp

ISO 8601

Horodatage de l'événement.

Payload colis.status_changed

json

{
  "id": "c9c88263-f24d-4a4d-ad7f-3808e39d3397",
  "event": "colis.status_changed",
  "created_at": "2026-05-19T20:00:00.000Z",
  "data": {
    "colis": {
      "code_barre": "OXO-A1B2-C3D4",
      "destinataire": "Nadia Benali",
      "telephone": "+212661123456",
      "ville": "Casablanca",
      "statut": "en_livraison",
      "prix_cod": 350
    },
    "event_statut": "en_livraison",
    "actor_role": "livreur",
    "note": "Tournée du jour — Casablanca"
  }
}

Vérifier la signature (Node.js)

javascript

import crypto from 'node:crypto';

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-oxo-signature']; // "sha256=..."
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.OXO_WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');
  if (sig !== expected) return res.status(401).send('bad sig');
  // traiter req.body
  res.sendStatus(200);
});

Tout code de réponse 2xx est considéré comme un succès. En cas d'échec, OXO réessaiera et désactivera le webhook après 20 échecs consécutifs.

Erreurs

Codes de réponse

Code	Signification
200 / 201	Succès
400	Requête malformée
401	Clé API manquante, invalide ou révoquée
403	Pas la permission (ex. clé d'un compte non-marchand)
404	Ressource introuvable
422	Validation échouée (champs invalides)
429	Trop de requêtes (rate limit)
500	Erreur serveur — contactez le support

Format d'erreur

json

{ "error": "Description lisible du problème" }

Une question ? Écrivez-nous à support@oxolivraison.com.