Documentation développeurs

L'API qui fait entrer et sortir vos décisions.

REST, webhooks signés, SDK first-party en TypeScript, Python et PHP. Les exemples ci-dessous s'exécutent contre l'API de production ; remplacez simplement les identifiants.

31
Connecteurs certifiés: 7
Ressources REST: 12 mois
Dépréciation minimale: api.maisonnumerique.site
Domaine API

Ingénieur devant plusieurs écrans, à côté d'une baie serveur.

Intégration

Aucune double saisie.
Les données entrent, les décisions ressortent.

L'API existe pour que les recommandations arrivent dans le système où vos équipes travaillent déjà — ERP, caisse ou entrepôt — plutôt que dans un tableau de bord de plus à consulter.

01Démarrage rapide

Quatre appels pour obtenir
une première recommandation.

1. Obtenir un jeton d’accès (OAuth 2.0, grant client_credentials).

POST /oauth/token

curl -X POST https://api.maisonnumerique.site/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=produits:lecture stocks:ecriture recommandations:lecture"

# Réponse
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "produits:lecture stocks:ecriture recommandations:lecture"
}

2. Récupérer les recommandations du jour pour un magasin.

GET /v1/recommandations

curl https://api.maisonnumerique.site/v1/recommandations?magasin=lyon-part-dieu \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Réponse (extrait)
{
  "data": [
    {
      "reference": "SKU-48213",
      "type": "reassort",
      "quantite_recommandee": 36,
      "date_commande_conseillee": "2026-08-27",
      "confiance": 0.87
    }
  ],
  "meta": { "total": 214, "page": 1 }
}

3. Pousser un réassort validé vers votre ERP via la plateforme.

POST /v1/commandes

curl -X POST https://api.maisonnumerique.site/v1/commandes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "magasin": "lyon-part-dieu",
    "fournisseur_id": "FRN-1029",
    "lignes": [
      { "reference": "SKU-48213", "quantite": 36 }
    ],
    "origine": "recommandation_ia"
  }'

# Réponse
{ "id": "CMD-88213", "statut": "en_attente_validation" }

4. Recevoir la confirmation via webhook une fois la commande validée côté ERP.

Webhook reçu : commande.validee

POST https://votre-domaine.fr/webhooks/maison-numerique
X-MN-Signature: t=1756123200,v1=5d41402abc4b2a76b9719d911017c592
Content-Type: application/json

{
  "type": "commande.validee",
  "id_evenement": "evt_7f3a...",
  "cree_le": "2026-08-25T09:12:00Z",
  "donnees": { "id": "CMD-88213", "statut": "validee" }
}

02SDK

Trois langages, un même modèle de données.

TypeScript

npm i @maisonnumerique/sdk

import { MaisonNumerique } from "@maisonnumerique/sdk";

const client = new MaisonNumerique({
  clientId: process.env.MN_CLIENT_ID,
  clientSecret: process.env.MN_CLIENT_SECRET,
});

const reco = await client.recommandations.list({
  magasin: "lyon-part-dieu",
});

Python

pip install maisonnumerique

from maisonnumerique import Client

client = Client(
    client_id=os.environ["MN_CLIENT_ID"],
    client_secret=os.environ["MN_CLIENT_SECRET"],
)

reco = client.recommandations.list(magasin="lyon-part-dieu")

PHP

composer require maisonnumerique/sdk

use MaisonNumerique\Client;

$client = new Client(
    clientId: getenv('MN_CLIENT_ID'),
    clientSecret: getenv('MN_CLIENT_SECRET'),
);

$reco = $client->recommandations->list(['magasin' => 'lyon-part-dieu']);

Les trois SDK gèrent le renouvellement automatique du jeton d’accès et la vérification de signature des webhooks. Ils couvrent les mêmes ressources que les connecteurs déjà certifiés pour 19+ systèmes, dont ERP, Caisse & encaissement, E-commerce, Données & marketing.

03Ressources REST

Ce que l'API expose.

GET /v1/produits: Catalogue produit et score IA associé à chaque référence.
GET /v1/ventes: Historique des ventes, par référence, magasin et période.
GET /v1/stocks: Niveau de stock par référence et par point de vente, mis à jour à chaque synchronisation.
GET /v1/clients: Fiches clients et segments issus de l'Intelligence Client.
POST /v1/commandes: Création d'une commande fournisseur, notamment pour pousser un réassort recommandé.
GET /v1/recommandations: Recommandations en cours : assortiment, réassort, prix et ciblage client.
GET /v1/previsions: Prévision de demande par référence et magasin, avec intervalle de confiance.

04Webhooks

Signature, vérification
et gestion des rejeux.

Vérifier la signature

Chaque webhook porte un en-tête X-MN-Signature au format t={horodatage},v1={hmac}. Le HMAC-SHA256 est calculé sur la concaténation horodatage.corps_brut avec votre clé de signature webhook.

Rejetez tout événement dont l’horodatage dépasse 5 minutes d’écart avec l’heure serveur, pour vous protéger d’un rejeu.

Livraison et rejeux

Réessais automatiques pendant 24 heures, avec un intervalle croissant.
Un événement identique porte toujours le même id_evenement : utilisez-le pour dédupliquer côté récepteur.
Le journal des 90 derniers jours d’envois est consultable depuis le tableau de bord, avec le corps et le code de réponse renvoyé par votre serveur.
Un renvoi manuel est possible depuis ce même journal.

05Limites de débit

Par forfait, pas par ressource.

Boutique: 60 requêtes / minute, 20 000 requêtes / jour.
Réseau: 300 requêtes / minute, 150 000 requêtes / jour.
Entreprise: Limite négociée au contrat, généralement au-delà de 1 000 requêtes / minute.
Webhooks: Non comptabilisés dans le quota de requêtes ; livraison avec réessais automatiques pendant 24 heures.

06Erreurs

Codes d'erreur en français.

400 — requete_invalide: Le corps de la requête ne respecte pas le schéma attendu. Le détail du champ fautif est renvoyé.
401 — jeton_invalide: Le jeton d'accès est absent, expiré ou révoqué. Redemandez un jeton via /oauth/token.
403 — acces_refuse: Le client OAuth authentifié n'a pas le scope nécessaire pour cette ressource.
404 — ressource_introuvable: L'identifiant demandé n'existe pas ou n'appartient pas à votre compte.
409 — conflit_etat: L'action demandée entre en conflit avec l'état actuel de la ressource (ex. commande déjà validée).
422 — regle_metier_violee: La requête est bien formée mais viole une règle métier (ex. quantité négative).
429 — limite_debit_atteinte: Le quota de requêtes du forfait est dépassé. L'en-tête Retry-After indique le délai avant nouvel essai.
503 — service_indisponible: Interruption temporaire côté plateforme. Réessayez avec un backoff exponentiel.

07Versionnage

Des versions datées,
une dépréciation annoncée à l'avance.

API v2026-03

Version datée

Chaque version de l'API porte une date (API v2026-03). Aucun changement cassant n'est introduit sur une version déjà publiée.

Dépréciation minimale de 12 mois

Une version dépréciée reste disponible au moins 12 mois après l'annonce, avec un en-tête d'avertissement sur chaque réponse.

Spécification OpenAPI publiée

Le contrat d'interface complet est publié au format OpenAPI, généré depuis la même source que la documentation interactive.

REST, webhooks signés et SDK first-party

Accès API

Besoin d'un accès
au bac à sable de test ?

Nos équipes fournissent un identifiant client OAuth de test, sans engagement, pour valider une intégration avant sa mise en production.

Demander un accès de test Voir la page Sécurité

Support intégrateurs — Réponse sous 2 jours ouvrés