API & MCP Z-Commerce
pour développeurs et partenaires

01Quick start

Trois étapes pour passer ton premier appel API.

02Environnements

03Authentification

JWT Bearer. Pas d'OAuth, pas d'API key statique — chaque utilisateur a un token court-vivant et un refresh token.

Login

curl -X POST "http://zc1.tail077eb3.ts.net:4002/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"zoomici@gmail.com","password":"<motdepasse>"}'

Réponse

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",  // JWT - durée 24h
  "refreshToken": "eyJhbGc...",             // 7 jours
  "user": { "id": "...", "email": "...", "role": "SUPER_ADMIN" }
}

Rôles

• SUPER_ADMIN — accès complet, gère tous les suppliers et users
• ADMIN — accès complet sans gestion des SUPER_ADMIN
• SUPPLIER_ADMIN — limité à son supplierId
• SELLER_ADMIN — pour les sellers ZCOMMERCE marketplace
• VIEWER — lecture seule

04Endpoints principaux

70 endpoints au total. Voici les plus utilisés (le reste est dans le Swagger interactif).

Suppliers

Orders

Dashboard

05Exemples de code

Exemple : lister les commandes Shopify en attente de routage.

curl "http://zc1.tail077eb3.ts.net:4002/api/v1/orders?status=RECEIVED&limit=50" \
  -H "Authorization: Bearer $JWT"

const base = "http://zc1.tail077eb3.ts.net:4002/api/v1";
const r = await fetch(`${base}/orders?status=RECEIVED&limit=50`, {
  headers: { "Authorization": `Bearer ${process.env.ZC_JWT}` }
});
const { data, total } = await r.json();
console.log(`${data.length}/${total} commandes`);

import os, requests
base = "http://zc1.tail077eb3.ts.net:4002/api/v1"
r = requests.get(
  f"{base}/orders",
  params={"status": "RECEIVED", "limit": 50},
  headers={"Authorization": f"Bearer {os.environ['ZC_JWT']}"}
)
data = r.json()
print(f"{len(data['data'])}/{data['total']} commandes")

# Method:  GET
# URL:     http://zc1.tail077eb3.ts.net:4002/api/v1/orders
# Query:   status=RECEIVED, limit=50
# Header:  Authorization: Bearer {{ $credentials.zcommerceJwt.token }}
# Auth:    None (Authorization en header manuel)

06Collection Postman

Collection auto-générée depuis le spec OpenAPI : 83 requêtes groupées en 12 dossiers, variables d'environnement {{API_BASE}} et {{JWT}}.

Import dans Postman

1. Ouvrir Postman → Import → glisser les deux fichiers téléchargés
2. Sélectionner l'environnement ZCOMMERCE - Test & Prod en haut à droite
3. Coller ton JWT dans la variable JWT (Edit Environment)
4. Switch API_BASE entre {{API_BASE_TEST}} et {{API_BASE_PROD}} selon le besoin

07Webhooks

Z-Commerce reçoit des webhooks (Shopify, suppliers) et émet des webhooks sortants vers ton n8n/Zapier.

Webhooks entrants

Webhooks sortants (à configurer dans la fiche supplier)

• order.routed — quand une commande Shopify est routée vers un supplier
• order.confirmed — quand le supplier confirme la commande (send_order OK)
• order.shipped — quand un tracking est récupéré
• order.cancelled — annulation côté supplier
• connector.health.degraded — quand un connecteur passe en DEGRADED/UNHEALTHY

Payload signé HMAC-SHA256 avec le secret défini dans la fiche supplier (header X-ZC-Signature).

08Swagger interactif

Spec OpenAPI complète, essai depuis le navigateur (clique sur Authorize en haut à droite et colle ton JWT).

09MCP Z-Commerce

Le MCP server expose les tools d'administration de la plateforme dans Claude Desktop, Cursor, Continue.dev, et autres clients compatibles Model Context Protocol.

Connexion

{
  "mcpServers": {
    "zcommerce-suppliers": {
      "command": "python",
      "args": ["-m", "zcommerce_suppliers_mcp.server"],
      "env": {
        "ZC_API_BASE": "http://zc1.tail077eb3.ts.net:4002/api/v1",
        "ZC_EMAIL": "<ton email admin>",
        "ZC_PASSWORD": "<ton mot de passe>"
      }
    }
  }
}

Tools exposés

+ orders, tracking, dashboard, connectors tools en cours d'ajout (chantier #4 séparé).

10Cahier des charges connecteur supplier

Ajouter un nouveau distributeur (ex: Ingram, Tech Data, Also) = implémenter ISupplierConnector + déclarer le code dans la factory. Aucune modif de l'API ni du dashboard.

Architecture (séparation tech / commercial)

Étapes pour ajouter un connecteur

Exemple : interface ISupplierConnector

export interface ISupplierConnector {
  testConnection(): Promise<boolean>;
  fetchProducts(): Promise<ProductData[]>;
  fetchStock(skus?: string[]): Promise<StockData[]>;
  fetchTracking(orderId: string): Promise<TrackingData | null>;
  sendOrder(order: OrderData): Promise<OrderConfirmation>;
}

Connecteurs disponibles aujourd'hui

• sftp — SFTP générique avec CSV/XML parsers
• api-rest — API REST générique (Bearer, API key, Basic, OAuth2)
• comline — COMLINE GmbH (FTPS Preisliste + JSONdirect, 210k SKU, send_order, get_shipping_details)

11Pipelines n8n

9 workflows COMLINE déjà en place sur n8n.srv978465.hstgr.cloud. À répliquer pour chaque nouveau supplier.

12Codes d'erreur

Format d'erreur standard

{
  "statusCode": 422,
  "message": ["email must be an email", "password too short"],
  "error": "Bad Request",
  "timestamp": "2026-06-07T20:30:00.000Z",
  "path": "/api/v1/auth/signup",
  "method": "POST",
  "requestId": "abc-123"
}