Branchez votre système sur OSCARIO EXPRESS

01Démarrer

L'accès API ne s'active pas tout seul : il est demandé, puis approuvé. Voici le parcours complet, de l'inscription au premier appel.

1. Ouvrez un compte. L'API est ouverte aux comptes client, agence et livreur. Un compte marchand doit avoir son identité (KYC) validée : sans elle, le tableau de bord reste fermé et la création de colis par l'API est refusée.
2. Demandez l'accès API depuis la page Paramètres API du tableau de bord. La demande est transmise aux administrateurs de la plateforme et, si votre compte est rattaché à une agence, à cette agence.
3. Attendez l'approbation. Elle est donnée par un administrateur, par le commercial qui suit votre compte ou par votre agence de rattachement lorsqu'elle y est habilitée. Tant qu'elle manque, la génération de clé répond 403.
4. Générez une clé dans Paramètres API : un nom, et une expiration facultative de 1 à 3 650 jours. La clé complète n'est affichée qu'une fois ; vous pouvez la révoquer à tout moment.
5. Appelez l'API avec l'en-tête x-api-key. Commencez par GET /api/external/cities : le cityId d'une ville desservie est obligatoire pour créer un colis.
6. Abonnez un webhook, facultatif, pour recevoir les changements d'état au lieu de les demander.

02URL de base et authentification

Toutes les routes décrites ici se trouvent sous cette adresse.

https://api.oscario.pro

Chaque appel authentifié porte la clé dans l'en-tête x-api-key. Sans cet en-tête, ou avec une clé invalide ou expirée, la réponse est 401.

x-api-key: osc_VOTRE_CLE

Une clé commence par osc_, suivi de 64 caractères hexadécimaux. Traitez-la comme un mot de passe : elle ne doit jamais apparaître dans le code d'une page web ou d'une application mobile.

Le compte, son type et ses droits se déduisent de la clé, jamais de la requête. Une clé client travaille sur les colis de son compte ; une clé agence ou livreur, sur les colis qui lui sont affectés.

03API marchande

Les routes du quotidien d'un e-commerçant : créer un colis, retrouver ses colis, lire leur état, leurs messages et ses factures.

Dates. Les paramètres de date attendent un horodatage UTC au format ISO 8601 terminé par « Z », par exemple 2026-07-01T00:00:00Z. Une date seule, une date sans fuseau ou une date avec décalage (+01:00) renvoie 400.

curl -X POST https://api.oscario.pro/api/external/colis \
  -H "x-api-key: osc_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-10432" \
  -d '{
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "9b0c6a2e-4f1d-4c7b-8a3e-2d5f6b7c8d9e",
    "address": "12 Rue Hassan II",
    "price": 349.00,
    "product": "Montre connectée",
    "quantity": 1,
    "importRef": "10432",
    "note": "Appeler avant livraison"
  }'

201 Created
{
  "success": true,
  "data": {
    "code": "OE-627313072514",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "cityId": "9b0c6a2e-4f1d-4c7b-8a3e-2d5f6b7c8d9e",
    "price": "349.00",
    "stateId": 1,
    "cfees": "39.00",
    "createdAt": "2026-07-25T20:14:14.000Z"
  }
}

curl "https://api.oscario.pro/api/external/colis?page=1&limit=20&stateIds=1,17&from=2026-07-01T00:00:00Z" \
  -H "x-api-key: osc_VOTRE_CLE"

200 OK
{
  "success": true,
  "data": [
    {
      "code": "OE-627313072514",
      "fullname": "Ahmed Bennani",
      "phone": "0612345678",
      "address": "12 Rue Hassan II",
      "cityId": "9b0c6a2e-...",
      "cityName": "Tiznit",
      "price": "349.00",
      "cfees": "39.00",
      "product": "Montre connectée",
      "quantity": 1,
      "importRef": "10432",
      "stateId": 17,
      "stateName": "Livré",
      "gpsLat": "29.6974210",
      "gpsLng": "-9.7359240",
      "createdAt": "2026-07-25T20:14:14.000Z",
      "updatedAt": "2026-07-27T15:02:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}

curl https://api.oscario.pro/api/external/colis/OE-627313072514 \
  -H "x-api-key: osc_VOTRE_CLE"

200 OK
{
  "success": true,
  "data": {
    "code": "OE-627313072514",
    "fullname": "Ahmed Bennani",
    "phone": "0612345678",
    "address": "12 Rue Hassan II",
    "cityName": "Tiznit",
    "price": "349.00",
    "cfees": "39.00",
    "stateId": 17,
    "stateName": "Livré",
    "gpsLat": "29.6974210",
    "gpsLng": "-9.7359240",
    "createdAt": "2026-07-25T20:14:14.000Z",
    "updatedAt": "2026-07-27T15:02:00.000Z",
    "billingStatus": "paid",
    "factureCode": "FAC-260728-0012",
    "facturePaidAt": "2026-07-29T10:00:00.000Z"
  }
}

curl https://api.oscario.pro/api/external/cities \
  -H "x-api-key: osc_VOTRE_CLE"

200 OK
{
  "success": true,
  "data": [
    { "id": "e455712f-bcf0-4827-b579-b34b52026b0f", "name": "Casablanca" },
    { "id": "9b0c6a2e-4f1d-4c7b-8a3e-2d5f6b7c8d9e", "name": "Tiznit" }
  ]
}

curl "https://api.oscario.pro/api/external/factures?page=1&limit=20&paid=false" \
  -H "x-api-key: osc_VOTRE_CLE"

200 OK
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "FAC-260728-0012",
      "type": "FAC",
      "totalAmount": "349.00",
      "totalFees": "39.00",
      "netAmount": "310.00",
      "paid": false,
      "paidAt": null,
      "createdAt": "2026-07-28T10:00:00.000Z",
      "updatedAt": "2026-07-28T10:00:00.000Z",
      "colisCount": 1
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}

curl "https://api.oscario.pro/api/external/colis/OE-627313072514/messages?page=1&limit=50" \
  -H "x-api-key: osc_VOTRE_CLE"

200 OK
{
  "success": true,
  "data": [
    {
      "id": "6f1e2d3c-4b5a-6978-8b9c-0d1e2f3a4b5c",
      "message": "Colis prêt, en attente de ramassage.",
      "messageType": "text",
      "senderType": "agency",
      "senderName": "Agence Casa",
      "hasAttachment": false,
      "createdAt": "2026-07-25T21:15:00.000Z",
      "deletedAt": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}

Les réponses ci-dessus sont des extraits : certains champs facultatifs sont omis pour la lisibilité.

04API opérationnelle : agences et livreurs

Une clé agence ou livreur ne crée pas de colis. Elle lit les colis qui lui sont affectés et fait évoluer leur état, à l'unité ou par lot ; elle lit aussi les messages et les factures qui la concernent. Une agence consulte en plus ses bons de groupage et ses bons de retour, et réceptionne ses groupages entrants.

Ces routes ne sont pas décrites sur cette page publique. Leur documentation, avec les états autorisés et des exemples, s'affiche dans Paramètres API, selon le type de votre compte, une fois votre accès API approuvé : connectez-vous pour la consulter.

05Routes publiques

Les trois routes ci-dessous répondent sans clé. Elles sont limitées par adresse IP, à 30 ou 20 requêtes par minute selon la route : voir la section Limites de débit.

curl https://api.oscario.pro/api/external/track/OE-627313072514

200 OK
{
  "success": true,
  "data": {
    "code": "OE-627313072514",
    "fullname": "Ahmed B.",
    "stateId": 17,
    "createdAt": "2026-07-25T20:14:14.000Z",
    "timeline": [
      {
        "stateId": 17,
        "stateName": "Livré",
        "userType": "dlm",
        "userCity": "Tiznit",
        "createdAt": "2026-07-27T15:02:00.000Z"
      }
    ]
  }
}

curl "https://api.oscario.pro/api/external/public-fees?agencyId=3f2b9c1e-..."

200 OK
{
  "success": true,
  "data": {
    "agencies": [
      { "id": "3f2b9c1e-...", "name": "Agence Casa", "cityId": "e455712f-..." }
    ],
    "cities": [
      { "id": "e455712f-...", "name": "Casablanca", "price": 20 }
    ]
  }
}

curl -X POST https://api.oscario.pro/api/external/feedback \
  -H "Content-Type: application/json" \
  -d '{ "code": "OE-627313072514", "rating": 5, "comment": "Livraison rapide" }'

201 Created
{ "success": true, "data": { "received": true } }

06Webhooks

Un compte déclare une URL de webhook, depuis Paramètres API, et choisit les événements qu'il veut recevoir. L'URL doit être en HTTPS en production ; les adresses locales et privées sont refusées. Le secret de signature n'est affiché qu'à la création et à chaque régénération. Le bouton Tester envoie un événement ping signé.

Un événement ne part que vers les comptes concernés par l'objet, et seulement si leur accès API est encore actif.

Événements de retrait. payout.approved, payout.tranche.created et payout.tranche.deleted sont acceptés à l'abonnement, mais aucun envoi ne les délivre aujourd'hui à un compte client, agence ou livreur. Ne construisez pas d'intégration sur eux.

Ce que reçoit votre serveur

Une requête POST en JSON, avec les champs event, timestamp et data, et les en-têtes X-OSCARIO-Event et X-OSCARIO-Signature. Le contenu de data dépend de l'événement et ne contient jamais de frais internes.

POST https://votre-serveur.example/webhooks/oscario
Content-Type: application/json
X-OSCARIO-Event: colis.state_changed
X-OSCARIO-Signature: t=1785164520,v1=9f2c4e...

{
  "event": "colis.state_changed",
  "timestamp": "2026-07-27T15:02:00.000Z",
  "data": {
    "code": "OE-627313072514",
    "stateId": 17,
    "stateName": "Livré",
    "price": "349.00",
    "cityName": "Tiznit",
    "gpsLat": "29.6974210",
    "gpsLng": "-9.7359240",
    "updatedAt": "2026-07-27T15:02:00.000Z"
  }
}

Vérifier la signature

L'en-tête X-OSCARIO-Signature contient t, l'heure d'envoi en secondes Unix, et v1, le HMAC-SHA256 en hexadécimal calculé avec votre secret sur t, un point, puis le corps brut de la requête. Calculez-le sur le corps tel qu'il est reçu, avant de le décoder.

const crypto = require('crypto');

const entete = req.get('X-OSCARIO-Signature');
const parts = Object.fromEntries(entete.split(',').map((p) => p.split('=')));
const attendu = crypto
  .createHmac('sha256', SECRET_WEBHOOK)
  .update(parts.t + '.' + corpsBrut)
  .digest('hex');

const valide = attendu.length === parts.v1.length
  && crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(parts.v1));

Échecs et reprises

Une livraison échoue si votre serveur ne répond pas dans les 10 secondes, répond hors de la plage 2xx ou renvoie une redirection, qui n'est jamais suivie. Elle est alors retentée, jusqu'à 5 tentatives au total, avec un délai qui double à partir de 30 secondes. Après 20 livraisons consécutives dont toutes les tentatives ont échoué, le webhook est désactivé automatiquement ; une livraison ou un test réussi remet ce compteur à zéro.

07Limites de débit

Cinq plafonds s'appliquent, chacun sur une fenêtre de durée fixe et avec sa propre clé de comptage. Les valeurs ci-dessous sont celles appliquées par défaut ; l'exploitant de la plateforme peut modifier les deux limites par compte.

Ce qui vous limite en premier dépend de la route. Un serveur qui appelle avec une clé bute sur les limites par compte, bien avant la garde par IP. Les trois routes publiques, elles, s'arrêtent à 30 ou 20 requêtes par minute par IP : dimensionnez un suivi en masse sur GET /api/external/colis avec une clé, pas sur /track.

Chaque réponse porte les en-têtes RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Au-delà du plafond, la réponse est 429 et son champ code nomme le limiteur atteint.

429 Too Many Requests
{
  "success": false,
  "message": "Too many requests, please try again later",
  "code": "rate_limited:publicTrackLimiter"
}

08Erreurs fréquentes

Le corps de chaque erreur porte un champ message qui en donne la cause. Pour un corps ou un paramètre mal formé, message vaut « Validation error » et la liste errors indique, pour chaque champ refusé, son chemin et la règle non respectée.