Examples - Products Manager API - Products Manager Docs

Cette page regroupe des exemples concrets couvrant les cas d'usage les plus fréquents de l'API Products Manager. Chaque exemple inclut la requête complète et une réponse représentative.

Exemple 1 : Authentification et Obtention du Token

Avant tout appel authentifié, obtenez un JWT access token en échangeant vos identifiants.

curl -X POST "https://api.productsmanager.app/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Réponse

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJtYW5hZ2VyIiwidGVuYW50X2lkIjoidGVuYW50X2FiYzEyMyIsImV4cCI6MTczMTY2NTYwMH0.abc123",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInR5cGUiOiJyZWZyZXNoIiwiZXhwIjoxNzMyMjcwNDAwfQ.xyz789",
    "token_type": "bearer",
    "expires_in": 7200
  }
}

Le access_token expire après 2 heures. Utilisez le refresh_token pour en obtenir un nouveau sans re-saisir les identifiants :

curl -X POST "https://api.productsmanager.app/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Utilisation du token dans les requêtes suivantes

Passez le access_token dans le header Authorization de chaque appel :

curl -X GET "https://api.productsmanager.app/api/v1/products" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Exemple 2 : Lister et Filtrer des Produits

Récupérez une liste paginée de produits avec des critères de filtrage et de tri.

Requête avec pagination et filtres

curl -X GET \
  "https://api.productsmanager.app/api/v1/products?page=1&per_page=20&status=active&category_id=5&brand=Bosch&search=perceuse&sort_by=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123"

Réponse paginée

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": 1234,
        "sku": "BSH-PERC-001",
        "ean": "4054596123456",
        "name": "Perceuse visseuse Bosch GSR 18V-55",
        "brand": "Bosch",
        "category_id": 5,
        "category_name": "Outillage électroportatif",
        "price": 149.99,
        "stock": 42,
        "status": "active",
        "enrichment_status": "enriched",
        "has_images": true,
        "images_count": 4,
        "created_at": "2025-10-01T08:15:00Z",
        "updated_at": "2025-11-10T14:30:00Z"
      },
      {
        "id": 1235,
        "sku": "BSH-PERC-002",
        "ean": "4054596234567",
        "name": "Perceuse à percussion Bosch GSB 18V-55",
        "brand": "Bosch",
        "category_id": 5,
        "category_name": "Outillage électroportatif",
        "price": 179.99,
        "stock": 18,
        "status": "active",
        "enrichment_status": "pending",
        "has_images": true,
        "images_count": 2,
        "created_at": "2025-10-03T09:00:00Z",
        "updated_at": "2025-10-03T09:00:00Z"
      }
    ],
    "total": 87,
    "page": 1,
    "per_page": 20,
    "pages": 5
  }
}

Pour itérer sur toutes les pages, incrémentez page jusqu'à ce que page >= pages.

Exemple 3 : Créer un Import

Importez un catalogue produit depuis un fichier CSV ou via un body JSON. Le process est asynchrone : l'API retourne immédiatement un ID d'import, que vous pouvez ensuite interroger pour suivre la progression.

Étape 1 — Lancer l'import (upload fichier)

curl -X POST "https://api.productsmanager.app/api/v1/imports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -F "file=@/path/to/catalog.csv" \
  -F "supplier_id=42" \
  -F "mapping={\"sku\":\"Reference\",\"name\":\"Designation\",\"price\":\"Prix HT\",\"ean\":\"EAN\"}"

Réponse immédiate (202 Accepted)

{
  "status": "success",
  "data": {
    "import_id": "imp_7f3a9b2c",
    "status": "queued",
    "supplier_id": 42,
    "file_name": "catalog.csv",
    "rows_detected": 1250,
    "created_at": "2025-11-15T10:00:00Z",
    "estimated_duration_seconds": 45
  }
}

Étape 2 — Polling du statut

curl -X GET "https://api.productsmanager.app/api/v1/imports/imp_7f3a9b2c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123"

Réponse (import terminé)

{
  "status": "success",
  "data": {
    "import_id": "imp_7f3a9b2c",
    "status": "completed",
    "supplier_id": 42,
    "rows_total": 1250,
    "rows_created": 1102,
    "rows_updated": 138,
    "rows_skipped": 8,
    "rows_failed": 2,
    "errors": [
      { "row": 47, "sku": "XX-INVALID", "reason": "INVALID_EAN" },
      { "row": 312, "sku": null, "reason": "REQUIRED_FIELD_MISSING" }
    ],
    "started_at": "2025-11-15T10:00:03Z",
    "completed_at": "2025-11-15T10:00:51Z",
    "duration_seconds": 48
  }
}

Les statuts possibles sont : queued, processing, completed, failed, cancelled. Pour éviter le polling, configurez un Webhook sur l'événement import.completed.

Exemple 4 : Lancer un Enrichissement IA

L'enrichissement IA génère automatiquement titres optimisés, descriptions longues, bullet points, attributs et catégories pour une liste de produits.

Étape 1 — Soumettre un batch d'enrichissement

curl -X POST "https://api.productsmanager.app/api/v1/ai-enrichment/batch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [1234, 1235, 1236, 1237, 1238],
    "fields": ["title", "description", "bullet_points", "attributes", "category"],
    "provider": "openai",
    "language": "fr",
    "tone": "professional",
    "overwrite_existing": false
  }'

Réponse (202 Accepted)

{
  "status": "success",
  "data": {
    "job_id": "enrich_4a8f2d91",
    "status": "queued",
    "products_count": 5,
    "estimated_credits": 25,
    "credits_available": 480,
    "created_at": "2025-11-15T10:05:00Z"
  }
}

Étape 2 — Suivi du job

curl -X GET "https://api.productsmanager.app/api/v1/ai-enrichment/jobs/enrich_4a8f2d91" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123"

Réponse (job en cours)

{
  "status": "success",
  "data": {
    "job_id": "enrich_4a8f2d91",
    "status": "processing",
    "products_total": 5,
    "products_done": 3,
    "products_failed": 0,
    "progress_percent": 60,
    "credits_consumed": 15,
    "started_at": "2025-11-15T10:05:02Z",
    "estimated_completion": "2025-11-15T10:05:20Z"
  }
}

Une fois le job completed, les champs enrichis sont disponibles sur chaque produit via GET /api/v1/products/{id}.

Exemple 5 : Synchroniser via un Connecteur

Les connecteurs permettent de synchroniser le catalogue Products Manager vers des plateformes e-commerce (Shopify, WooCommerce, Mirakl, Amazon SP-API, Odoo, PrestaShop, Google Merchant).

Lancer une synchronisation

curl -X POST "https://api.productsmanager.app/api/v1/connectors/conn_shopify_main/sync" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "incremental",
    "since": "2025-11-14T00:00:00Z",
    "product_ids": null,
    "dry_run": false
  }'

Le champ mode accepte full (catalogue complet) ou incremental (delta depuis since). dry_run: true simule la synchronisation sans rien écrire.

Réponse

{
  "status": "success",
  "data": {
    "sync_id": "sync_c91d4e77",
    "connector_id": "conn_shopify_main",
    "connector_type": "shopify",
    "mode": "incremental",
    "status": "running",
    "products_in_scope": 138,
    "started_at": "2025-11-15T10:10:00Z"
  }
}

Vérifier le statut de synchronisation

curl -X GET "https://api.productsmanager.app/api/v1/connectors/conn_shopify_main/syncs/sync_c91d4e77" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123"

Réponse (sync terminée)

{
  "status": "success",
  "data": {
    "sync_id": "sync_c91d4e77",
    "connector_id": "conn_shopify_main",
    "connector_type": "shopify",
    "status": "completed",
    "products_synced": 136,
    "products_created": 12,
    "products_updated": 124,
    "products_failed": 2,
    "errors": [
      { "product_id": 1100, "reason": "CONNECTOR_AUTH_FAILED", "detail": "Variant limit exceeded on Shopify plan" }
    ],
    "started_at": "2025-11-15T10:10:00Z",
    "completed_at": "2025-11-15T10:10:42Z",
    "duration_seconds": 42
  }
}

Exemple 6 : Utiliser une API Key

Les API Keys permettent un accès machine-to-machine sans flux OAuth. Elles sont préfixées pm_live_ en production et pm_test_ en environnement de test.

Créer une API Key (depuis l'interface ou l'API admin)

curl -X POST "https://api.productsmanager.app/api/v1/auth/api-keys" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "X-Tenant-Id: tenant_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Intégration ERP Production",
    "scopes": ["products:read", "products:write", "imports:write", "exports:read"],
    "expires_at": null
  }'

Réponse (la clé n'est affichée qu'une seule fois)

{
  "status": "success",
  "data": {
    "api_key_id": "key_8b3f1d22",
    "name": "Intégration ERP Production",
    "key": "pm_live_4xKz9mNqRtW2vJhL8cBpYeA7dGs0FuXi",
    "scopes": ["products:read", "products:write", "imports:write", "exports:read"],
    "created_at": "2025-11-15T10:15:00Z",
    "expires_at": null
  }
}

Stockez la valeur de key immédiatement : elle ne sera plus affichée après cette réponse.

Utiliser l'API Key dans les requêtes

Passez la clé dans le header X-API-Key à la place du JWT :

curl -X GET "https://api.productsmanager.app/api/v1/products?status=active" \
  -H "X-API-Key: pm_live_4xKz9mNqRtW2vJhL8cBpYeA7dGs0FuXi" \
  -H "X-Tenant-Id: tenant_abc123"

Scopes disponibles

Scope	Accès
`products:read`	Lecture du catalogue produit
`products:write`	Création et modification de produits
`products:delete`	Suppression de produits
`imports:write`	Lancer des imports
`exports:read`	Télécharger des exports
`suppliers:read`	Lecture des fournisseurs
`connectors:sync`	Déclencher des synchronisations
`analytics:read`	Accès aux métriques et rapports
`admin:*`	Accès administration complet (super admin uniquement)

Les API Keys ne peuvent pas dépasser les permissions du rôle RBAC de l'utilisateur qui les a créées.

Liens Utiles

Authentification API — détails JWT, refresh, révocation
Endpoints complets — référence de tous les 530+ endpoints
Gestion des erreurs — codes d'erreur et retry logic
Rate Limiting — limites par endpoint et headers
Webhooks — éviter le polling avec des notifications push
Connecteurs API — configuration et gestion des connecteurs
Permissions RBAC — liste des 62 permissions disponibles

Exemple 1 : Authentification et Obtention du Token

Requête de login

Réponse

Utilisation du token dans les requêtes suivantes

Exemple 2 : Lister et Filtrer des Produits

Requête avec pagination et filtres

Réponse paginée

Exemple 3 : Créer un Import

Étape 1 — Lancer l'import (upload fichier)

Réponse immédiate (202 Accepted)

Étape 2 — Polling du statut

Réponse (import terminé)

Exemple 4 : Lancer un Enrichissement IA

Étape 1 — Soumettre un batch d'enrichissement

Réponse (202 Accepted)

Étape 2 — Suivi du job

Réponse (job en cours)

Exemple 5 : Synchroniser via un Connecteur

Lancer une synchronisation

Réponse

Vérifier le statut de synchronisation

Réponse (sync terminée)

Exemple 6 : Utiliser une API Key

Créer une API Key (depuis l'interface ou l'API admin)

Réponse (la clé n'est affichée qu'une seule fois)

Utiliser l'API Key dans les requêtes

Scopes disponibles

Liens Utiles