Guide de l'API fournisseur : Traitement des commandes manuelles

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un compte fournisseur avec accès à l'API
• Votre clé API (vous pouvez la générer depuis votre tableau de bord fournisseur)
• L'accès aux endpoints 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 commettez pas dans un système de contrôle de version.

Étape 2 : Récupérer les commandes manuelles

Utilisez l'endpoint 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://votre-domaine.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: VOTRE_CLE_API"

Paramètres de la requête

• status (optionnel) : Filtre par statut de commande. Accepte des valeurs séparées par des virgules : pending,processing
• productType (obligatoire 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, défaut 50)
• offset (optionnel) : Décalage de pagination (défaut 0)

Exemple de réponse

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

Remarques importantes

• Seules les commandes avec paymentStatus: "completed" sont retournées
• Les commandes sont filtrées pour éviter les traitements 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 les commandes récupérées, traitez-les et préparez les identifiants de compte. Utilisez ensuite l'endpoint 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://votre-domaine.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "utilisateur1:motdepasse1",
      "utilisateur2:motdepasse2",
      "utilisateur3:motdepasse3"
    ],
    "supplierOrderId": "FOUR-COMMANDE-12345"
  }'

Paramètres du corps de la requête

• order (obligatoire) : L'ID de la commande (nombre)
• status (optionnel) : Nouveau statut de la commande. Valeurs valides : pending, processing, completed, partial, cancelled, error
• accounts (optionnel, pour les commandes de produits) : Tableau d'identifiants de compte au format "utilisateur:motdepasse" ou "email:motdepasse"
• 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. Chaque chaîne représente un compte :

• Format : "utilisateur:motdepasse" ou "email:motdepasse"
• Exemple : ["user1:pass123", "user2:pass456"]
• Quantité : Fournissez des comptes correspondant à la quantité de la commande

Exemple de workflow complet

Voici un exemple complet utilisant JavaScript/Node.js :

const axios = require('axios');

const API_BASE_URL = 'https://votre-domaine.com/api/admin/v2';
const API_KEY = 'VOTRE_CLE_API';

// Étape 1 : Récupérer les commandes manuelles en attente et en cours de 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;
  }
}

// Workflow principal
async function processOrders() {
  try {
    // Récupérer les commandes
    const orders = await getOrders();
    console.log(`${orders.length} commande(s) trouvée(s) à 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,
        `FOUR-${order.id}`
      );
      
      console.log(`Commande ${order.id} terminée avec succès`);
    }
  } catch (error) {
    console.error('Erreur dans le workflow :', error);
  }
}

// Exécuter le workflow
processOrders();

Gestion des erreurs

Erreurs courantes

1. Clé API invalide

   {
         "error": "INVALID_API_KEY",
         "message": "Clé API invalide"
       }

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

2. Commande introuvable

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Commande introuvable"
       }

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

3. Accès refusé

   {
         "error": "ACCESS_DENIED",
         "message": "Vous n'avez pas accès à cette commande"
       }

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

4. Comptes invalides

   {
         "error": "INVALID_ACCOUNTS",
         "message": "Aucun compte valide fourni après déduplication"
       }

   Solution : Assurez-vous que le tableau de 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 les traitements en double avec un intervalle de 30 minutes.
2. Gestion des erreurs : Implémentez toujours une gestion des erreurs et une logique de réessai appropriées.
3. Validation des comptes : Validez les comptes avant de les soumettre pour garantir 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'abord définir sur processing lorsque vous commencez à travailler dessus
   • Ensuite définir sur completed lorsque les comptes sont prêts
6. Commandes partielles : Si vous ne pouvez exécuter qu'une partie d'une commande, définissez le statut sur partial et soumettez les comptes disponibles.

Résumé

Le workflow complet est :

1. Récupérer 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