Guide de l'API fournisseur : Traitement des commandes manuelles

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un compte fournisseur avec accès API
• Votre clé API (vous pouvez la générer depuis votre tableau de bord fournisseur)
• Accès aux points de terminaison de l'API Admin v2

Étape 1 : Obtenir votre clé API

1. Connectez-vous à votre tableau de bord fournisseur
2. Accédez aux Paramètres API (/api-settings)
3. Cliquez sur "Générer une clé API" si vous n'en avez pas
4. Copiez votre clé API et conservez-la en sécurité

Important : Votre clé API doit rester secrète. Ne la partagez jamais publiquement et ne la validez pas dans un système de contrôle de version.

Étape 2 : Obtenir les commandes manuelles

Utilisez le point de terminaison GET /api/admin/v2/orders pour récupérer les commandes manuelles en attente et en cours de traitement.

Requête API

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

Paramètres de la requête

• status (optionnel) : Filtre de statut de commande. Prend en charge les valeurs séparées par des virgules : pending,processing
• productType (requis pour les commandes manuelles) : Définir sur manual
• entityType (optionnel) : Filtrer par product ou smm_service
• subCategory (optionnel) : Filtrer par nom de sous-catégorie
• limit (optionnel) : Nombre de commandes à retourner (max 500, par défaut 50)
• offset (optionnel) : Décalage de pagination (par défaut 0)

Exemple de réponse

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

Notes importantes

• Seules les commandes avec paymentStatus: "completed" sont retournées
• Les commandes sont filtrées pour éviter un traitement en double (intervalle de 30 minutes)
• Vous ne pouvez voir que les commandes pour les produits/services qui vous appartiennent en tant que fournisseur

Étape 3 : Traiter les commandes et soumettre les comptes

Une fois que vous avez les commandes, traitez-les et préparez les identifiants de compte. Ensuite, utilisez le point de terminaison POST /api/admin/v2/orders-update pour soumettre les comptes et mettre à jour le statut de la commande.

Requête API

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

Paramètres du corps de la requête

• order (requis) : L'ID de la commande (nombre)
• status (optionnel) : Nouveau statut de commande. Valeurs valides : pending, processing, completed, partial, cancelled, error
• accounts (optionnel, pour les commandes de produits) : Tableau des identifiants de compte au format "username:password" ou "email:password"
• supplierOrderId (optionnel) : Votre ID de commande interne pour le suivi

Format des comptes

Pour les commandes de produits, les comptes doivent être fournis sous forme de tableau de chaînes de caractères. Chaque chaîne représente un compte :

• Format : "username:password" ou "email:password"
• Exemple : ["user1:pass123", "user2:pass456"]
• Quantité : Fournissez un nombre de comptes correspondant à la quantité commandée

Exemple de flux de travail complet

Voici un exemple complet utilisant JavaScript/Node.js :

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// Étape 1 : Obtenir les commandes manuelles en attente et en traitement
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('Erreur lors de la récupération des commandes :', error.response?.data || error.message);
    throw error;
  }
}

// Étape 2 : Traiter la commande et soumettre les comptes
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Erreur lors de la mise à jour de la commande :', error.response?.data || error.message);
    throw error;
  }
}

// Flux de travail principal
async function processOrders() {
  try {
    // Obtenir les commandes
    const orders = await getOrders();
    console.log(`Trouvé ${orders.length} commandes à traiter`);
    
    // Traiter chaque commande
    for (const order of orders) {
      console.log(`Traitement de la commande ${order.id}...`);
      
      // Préparer les comptes (c'est ici que vous récupéreriez depuis votre système)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... plus de comptes correspondant à order.quantity
      ];
      
      // Mettre à jour la commande avec les comptes et la marquer comme terminée
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Commande ${order.id} terminée avec succès`);
    }
  } catch (error) {
    console.error('Erreur dans le flux de travail :', error);
  }
}

// Exécuter le flux de travail
processOrders();

Gestion des erreurs

Erreurs courantes

1. Clé API invalide

   {
         "error": "INVALID_API_KEY",
         "message": "Invalid API key"
       }

   Solution : Vérifiez que votre clé API est correcte et active.

2. Commande introuvable

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Order not found"
       }

   Solution : Vérifiez que l'ID de commande existe et vous appartient.

3. Accès refusé

   {
         "error": "ACCESS_DENIED",
         "message": "You do not have access to this order"
       }

   Solution : Assurez-vous que la commande contient des produits/services qui vous appartiennent.

4. Comptes invalides

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No valid accounts provided after deduplication"
       }

   Solution : Assurez-vous que le tableau des comptes n'est pas vide et contient des chaînes valides.

Bonnes pratiques

1. Fréquence d'interrogation : N'interrogez pas trop fréquemment. L'API empêche le traitement en double avec un intervalle de 30 minutes.
2. Gestion des erreurs : Implémentez toujours une gestion des erreurs appropriée et une logique de nouvelle tentative.
3. Validation des comptes : Validez les comptes avant de les soumettre pour vous assurer qu'ils sont au bon format.
4. Suivi des commandes : Utilisez supplierOrderId pour suivre les commandes dans votre système.
5. Mises à jour de statut : Vous pouvez mettre à jour le statut de manière incrémentielle :
   • Définissez d'abord sur processing lorsque vous commencez à y travailler
   • Puis définissez sur completed lorsque les comptes sont prêts
6. Commandes partielles : Si vous ne pouvez honorer qu'une partie d'une commande, définissez le statut sur partial et soumettez les comptes disponibles.

Résumé

Le flux de travail complet est :

1. Obtenir les commandes : GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Traiter les commandes : Préparer les comptes pour chaque commande
3. Soumettre les comptes : POST /api/admin/v2/orders-update avec les comptes et status: "completed"

Ce simple processus en trois étapes vous permet d'automatiser entièrement votre flux de travail de traitement des commandes !

Les deux sont des guides de documentation essentiels pour les fournisseurs. Les relier aide les fournisseurs à naviguer de la configuration des produits au traitement des commandes, créant un flux de travail logique. guide de gestion des produits.