Lieferanten-API-Anleitung: Manuelle Bestellungen verarbeiten

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Lieferantenkonto mit API-Zugriff
• Ihren API-Schlüssel (Sie können ihn aus Ihrem Lieferanten-Dashboard generieren)
• Zugriff auf die Admin API v2-Endpunkte

Schritt 1: Holen Sie sich Ihren API-Schlüssel

1. Melden Sie sich bei Ihrem Lieferanten-Dashboard an
2. Navigieren Sie zu den API-Einstellungen (/api-settings)
3. Klicken Sie auf "API-Schlüssel generieren", falls Sie noch keinen haben
4. Kopieren Sie Ihren API-Schlüssel und bewahren Sie ihn sicher auf

Wichtig: Ihr API-Schlüssel sollte geheim bleiben. Geben Sie ihn niemals öffentlich preis oder committen Sie ihn in die Versionskontrolle.

Schritt 2: Manuelle Bestellungen abrufen

Verwenden Sie den Endpunkt GET /api/admin/v2/orders, um ausstehende und in Bearbeitung befindliche manuelle Bestellungen abzurufen.

API-Anfrage

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"

Anfrageparameter

• status (optional): Bestellstatus-Filter. Unterstützt kommagetrennte Werte: pending,processing
• productType (erforderlich für manuelle Bestellungen): Auf manual setzen
• entityType (optional): Filtern nach product oder smm_service
• subCategory (optional): Filtern nach Unterkategorie-Name
• limit (optional): Anzahl der zurückzugebenden Bestellungen (max. 500, Standard 50)
• offset (optional): Paginierungs-Offset (Standard 0)

Beispielantwort

{
  "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
}

Wichtige Hinweise

• Es werden nur Bestellungen mit paymentStatus: "completed" zurückgegeben
• Bestellungen werden gefiltert, um doppelte Verarbeitung zu verhindern (30-Minuten-Intervall)
• Sie können nur Bestellungen für Produkte/Dienste sehen, die Ihnen als Lieferant gehören

Schritt 3: Bestellungen bearbeiten und Konten übermitteln

Sobald Sie die Bestellungen haben, bearbeiten Sie diese und bereiten Sie die Kontozugangsdaten vor. Verwenden Sie dann den Endpunkt POST /api/admin/v2/orders-update, um Konten zu übermitteln und den Bestellstatus zu aktualisieren.

API-Anfrage

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"
  }'

Anfrage-Body-Parameter

• order (erforderlich): Die Bestell-ID (Nummer)
• status (optional): Neuer Bestellstatus. Gültige Werte: pending, processing, completed, partial, cancelled, error
• accounts (optional, für Produktbestellungen): Array von Kontozugangsdaten im Format "username:password" oder "email:password"
• supplierOrderId (optional): Ihre interne Bestell-ID zur Nachverfolgung

Kontenformat

Für Produktbestellungen sollten Konten als Array von Strings bereitgestellt werden. Jeder String repräsentiert ein Konto:

• Format: "username:password" oder "email:password"
• Beispiel: ["user1:pass123", "user2:pass456"]
• Menge: Stellen Sie Konten bereit, die der Bestellmenge entsprechen

Vollständiges Workflow-Beispiel

Hier ist ein vollständiges Beispiel mit JavaScript/Node.js:

const axios = require('axios');

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

// Schritt 1: Ausstehende und in Bearbeitung befindliche manuelle Bestellungen abrufen
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('Fehler beim Abrufen der Bestellungen:', error.response?.data || error.message);
    throw error;
  }
}

// Schritt 2: Bestellung bearbeiten und Konten übermitteln
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('Fehler beim Aktualisieren der Bestellung:', error.response?.data || error.message);
    throw error;
  }
}

// Haupt-Workflow
async function processOrders() {
  try {
    // Bestellungen abrufen
    const orders = await getOrders();
    console.log(`Gefunden ${orders.length} zu bearbeitende Bestellungen`);
    
    // Jede Bestellung bearbeiten
    for (const order of orders) {
      console.log(`Bearbeite Bestellung ${order.id}...`);
      
      // Konten vorbereiten (hier würden Sie sie aus Ihrem System abrufen)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... weitere Konten entsprechend order.quantity
      ];
      
      // Bestellung mit Konten aktualisieren und als abgeschlossen markieren
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Bestellung ${order.id} erfolgreich abgeschlossen`);
    }
  } catch (error) {
    console.error('Fehler im Workflow:', error);
  }
}

// Workflow ausführen
processOrders();

Fehlerbehandlung

Häufige Fehler

1. Ungültiger API-Schlüssel

   {
         "error": "INVALID_API_KEY",
         "message": "Ungültiger API-Schlüssel"
       }

   Lösung: Überprüfen Sie, ob Ihr API-Schlüssel korrekt und aktiv ist.

2. Bestellung nicht gefunden

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Bestellung nicht gefunden"
       }

   Lösung: Verifizieren Sie, dass die Bestell-ID existiert und Ihnen gehört.

3. Zugriff verweigert

   {
         "error": "ACCESS_DENIED",
         "message": "Sie haben keinen Zugriff auf diese Bestellung"
       }

   Lösung: Stellen Sie sicher, dass die Bestellung Produkte/Dienste enthält, die Ihnen gehören.

4. Ungültige Konten

   {
         "error": "INVALID_ACCOUNTS",
         "message": "Nach Deduplizierung wurden keine gültigen Konten bereitgestellt"
       }

   Lösung: Stellen Sie sicher, dass das Konten-Array nicht leer ist und gültige Strings enthält.

Bewährte Verfahren

1. Abfragehäufigkeit: Fragen Sie nicht zu häufig ab. Die API verhindert doppelte Verarbeitung mit einem Intervall von 30 Minuten.
2. Fehlerbehandlung: Implementieren Sie stets eine ordnungsgemäße Fehlerbehandlung und Wiederholungslogik.
3. Kontenvalidierung: Validieren Sie Konten vor der Übermittlung, um sicherzustellen, dass sie das korrekte Format haben.
4. Auftragsverfolgung: Verwenden Sie supplierOrderId, um Aufträge in Ihrem System zu verfolgen.
5. Statusaktualisierungen: Sie können den Status schrittweise aktualisieren:
   • Zuerst auf processing setzen, wenn Sie mit der Bearbeitung beginnen
   • Dann auf completed setzen, wenn die Konten bereit sind
6. Teilaufträge: Wenn Sie nur einen Teil eines Auftrags erfüllen können, setzen Sie den Status auf partial und übermitteln Sie die verfügbaren Konten.

Zusammenfassung

Der vollständige Workflow ist:

1. Aufträge abrufen: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Aufträge bearbeiten: Konten für jeden Auftrag vorbereiten
3. Konten übermitteln: POST /api/admin/v2/orders-update mit Konten und status: "completed"

Dieser einfache dreistufige Prozess ermöglicht es Ihnen, Ihren Auftragsabwicklungs-Workflow vollständig zu automatisieren!

Beides sind zentrale Leitfäden für Lieferanten. Das Verlinken hilft Lieferanten, von der Produkteinrichtung zur Auftragsabwicklung zu navigieren und einen logischen Workflow zu schaffen. Produktmanagement-Leitfaden.