Produkte-API

🤖 Erklären mit KI

Die Produkte-API dient der effizienten Verwaltung von Produktdaten innerhalb einer E-Commerce-Umgebung. Sie unterstützt das Erstellen, Ändern und Löschen von Produkten und verwaltet dabei Preisdetails, Lagerinformationen, Wiederholungseinstellungen, Steuern und die Bildverwaltung.

Die API sorgt für klare und konsistente Antworten, einschließlich detaillierter Fehlerbehandlung und Unterstützung für mehrere Währungen mit korrekter Präzisionsprüfung.

Ein Produkt erstellen¶

Dieser Endpunkt ermöglicht das Erstellen eines neuen Produkts im System durch Senden einer POST-Anfrage mit den Produktdetails – wie Name, Beschreibung, Preis, Währung, Lagerbestand, Steuern, Bilder und Wiederholungseinstellungen.

Query-Parameter:

Felder im Request-Body:

Format des Wiederholungsobjekts:

{
  "recurrence": "period",           // oder "specific_billing_day"
  "duration_period": 1              // Gültig: 1, 2, 3, 4, 6, 12 (Monate)
}

Oder:

{
  "recurrence": "specific_billing_day",
  "payday": 15                       // Gültig: 1-28
}

Parameter für den Datei-Upload:

Anfrage:

curl -X POST 'https://api.4geeks.io/v1/products/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Premium Widget' \
     -F 'description=This is a premium widget product' \
     -F 'price=99.99' \
     -F 'currency=USD' \
     -F 'stock=50' \
     -F 'is_physical=true' \
     -F 'taxes=1,3' \
     -F 'sku=PREMIUM-WIDGET-001' \
     -F 'image_default=@/path/to/image.jpg' \
     -F 'recurrence={"recurrence":"period","duration_period":3}'

Antwort (201 Created):

{
  "code": 201,
  "title": "Registrierung abgeschlossen",
  "content": "Die Registrierung wurde erfolgreich abgeschlossen.",
  "type": "success",
  "data": {
    "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
  }
}

Alle Produkte abrufen¶

Dieser Endpunkt ruft eine paginierte Liste aller Produkte mit erweiterter Filterunterstützung ab. Unterstützt Pagination, Suche, Filterung nach Typ, Preisspanne und Lagerbestand.

Query-Parameter:

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&page_size=10&test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Anfrage (Mit Filtern):

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&search=widget&type=physical&price_min=10&price_max=100&stock_min=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
  "count": 25,
  "current_page": 1,
  "total_pages": 3,
  "results": [
    {
      "id": "a232cccc-956a-44ca-a2e8-d763afddc89f",
      "name": "Premium Widget",
      "short_description": "Hochwertiges Widget",
      "description": "Dies ist ein Premium-Widget-Produkt mit erweiterten Funktionen",
      "stock": 50,
      "price": "99.99",
      "currency": "USD",
      "total_price": "109.99",
      "is_physical": true,
      "bar_code": "123456789012",
      "sku": "PREMIUM-WIDGET-001",
      "recurrence": {
        "recurrence": "period",
        "duration_period": 3
      },
      "images": {
        "default": "https://storage.googleapis.com/bucket/image-default.jpg",
        "additional_images": [
          {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
          {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
        ]
      },
      "payment_link": false,
      "created_on": "2025-12-04T10:30:00Z",
      "test": false,
      "taxes": [
        {"id": 1, "name": "MwSt.", "value": 10.0}
      ]
    }
  ]
}

Ein bestimmtes Produkt abrufen¶

Dieser Endpunkt ruft die vollständigen Details eines bestimmten Produkts anhand seiner eindeutigen ID ab.

Pfad-Parameter:

Query-Parameter:

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
  "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "name": "Premium Widget",
  "short_description": "Hochwertiges Widget",
  "description": "Dies ist ein Premium-Widget-Produkt mit erweiterten Funktionen",
  "stock": 50,
  "price": "99.99",
  "currency": "USD",
  "total_price": "109.99",
  "is_physical": true,
  "bar_code": "123456789012",
  "sku": "PREMIUM-WIDGET-001",
  "recurrence": {
    "recurrence": "period",
    "duration_period": 3
  },
  "images": {
    "default": "https://storage.googleapis.com/bucket/image-default.jpg",
    "additional_images": [
      {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
      {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
    ]
  },
  "payment_link": false,
  "created_on": "2025-12-04T10:30:00Z",
  "test": false,
  "taxes": [
    {"id": 1, "name": "MwSt.", "value": 10.0}
  ]
}

Ein Produkt aktualisieren¶

Aktualisiert ein bestehendes Produkt mit neuen Details. Sie können einzelne Felder aktualisieren, ohne andere zu beeinflussen.

Pfad-Parameter:

Query-Parameter:

Felder im Request-Body (alle optional):

Flags für die Bildverwaltung:

Anfrage:

curl -X PUT 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Updated Widget Name' \
     -F 'description=Updated description' \
     -F 'price=79.99' \
     -F 'stock=100' \
     -F 'default=-1'

Antwort (200 OK):

{
  "code": 200,
  "title": "Produkt aktualisiert",
  "content": "Das Produkt wurde erfolgreich aktualisiert.",
  "type": "success",
  "data": {
    "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
    "name": "Updated Widget Name",
    "description": "Updated description",
    "price": "79.99",
    "stock": 100,
    "total_price": "87.99"
  }
}

Ein Produkt löschen¶

Löscht ein Produkt dauerhaft und deaktiviert es.

Pfad-Parameter:

Query-Parameter:

Anfrage:

curl -X DELETE 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
  "code": 200,
  "title": "Produkt gelöscht",
  "content": "Das Produkt wurde erfolgreich gelöscht.",
  "type": "success"
}

Fehlerbehandlung¶

Die API gibt Standard-HTTP-Statuscodes zurück, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen. Nachfolgend sind häufige Fehler aufgeführt, die spezifisch für Produkte sind:

400 Bad Request¶

Tritt auf, wenn die Anfrage fehlerhaft ist oder ungültige Daten enthält.

Szenarien:

Beispiel für eine Fehlerantwort:

{
  "code": 400,
  "title": "Ungültiges Preisformat",
  "content": "Preisvalidierungsfehler: JPY benötigt 0 Dezimalstellen. Bitte passen Sie den Preis entsprechend den Währungsanforderungen an.",
  "type": "danger"
}

401 Unauthorized¶

Authentifizierung fehlgeschlagen. Der API-Key ist ungültig, fehlt oder ist fehlerhaft.

Beispiel:

{
  "detail": "Authentifizierungsdaten wurden nicht bereitgestellt."
}

Lösung: - Überprüfen Sie, ob Sie den Parameter -u 'sk_test_...: oder den Header Authorization: Basic hinzugefügt haben - Stellen Sie sicher, dass Ihr API-Key korrekt und aktiv ist - Testen Sie mit Postman unter Verwendung von Basic Auth

404 Not Found¶

Das angeforderte Produkt existiert nicht.

Beispiel:

{
  "code": 404,
  "title": "Produkt existiert nicht",
  "content": "Die ID 'f9b77185-a62e-4da9-a056-3c7b812ca334' entspricht keinem Produkt",
  "type": "danger"
}

Lösung: - Überprüfen Sie, ob die Produkt-ID existiert - Verwenden Sie den List-Endpunkt, um die korrekte Produkt-ID zu finden - Stellen Sie sicher, dass das Produkt zu Ihrem Entwicklerkonto gehört

406 Not Acceptable¶

Die Anfrage verstößt gegen Geschäftsregeln oder Validierungsbeschränkungen.

Beispiel:

{
  "code": 406,
  "title": "Fehler bei der Produktregistrierung",
  "content": "Registrierung des Produkts fehlgeschlagen, bitte prüfen: Ungültige Feldwerte",
  "type": "danger"
}

Wichtige Hinweise¶

Best Practices¶

1. Preise sorgfältig validieren – Stellen Sie sicher, dass die Preise den Anforderungen an die Dezimalstellen der Währung entsprechen
2. Beschreibende Namen verwenden – Helfen Sie Kunden, Produkte klar zu verstehen
3. Genauen Lagerbestand festlegen – Halten Sie die Inventarzahlen aktuell
4. Bilder hinzufügen – Produktbilder erhöhen die Konversionsraten
5. SKUs verwenden – Eindeutige SKUs helfen bei der Lagerverwaltung
6. Steuern korrekt anwenden – Beziehen Sie alle anwendbaren Steuer-IDs ein
7. Vor der Produktion testen – Verwenden Sie den Testmodus mit Test-API-Keys zur Validierung
8. Wiederholung klug einsetzen – Legen Sie die Wiederholung nur für abonnementfähige Produkte fest

Fehlerbehebung¶

Problem: „Preisvalidierungsfehler: JPY benötigt 0 Dezimalstellen“¶

Ursache: Verwendung von Dezimalstellen, die von der Währung nicht unterstützt werden
Lösung: - JPY: Ganze Zahlen verwenden (keine Dezimalstellen) - USD/EUR: 2 Dezimalstellen verwenden (99.99) - KWD: 3 Dezimalstellen verwenden (99.999)

Problem: „Der duration_period kann nur die folgenden Werte enthalten: 1, 2, 3, 4, 6, 12“¶

Ursache: Ungültiger Wiederholungszeitraum angegeben
Lösung: - Verwenden Sie nur: 1 (monatlich), 2 (zweimonatlich), 3 (vierteljährlich), 4 (viermonatlich), 6 (halbjährlich) oder 12 (jährlich)

Problem: „Der payday muss größer als 0 und kleiner oder gleich 28 sein“¶

Ursache: Ungültiger Abrechnungstag angegeben
Lösung: - Der Zahltag muss zwischen 1 und 28 liegen - Die Tage 29-31 werden nicht unterstützt, um die monatliche Konsistenz zu gewährleisten

Problem: „Produkt existiert nicht“¶

Ursache: Produkt-ID existiert nicht oder gehört zu einem anderen Entwicklerkonto
Lösung: - Überprüfen Sie die Produkt-ID über den List-Endpunkt - Stellen Sie sicher, dass Sie den richtigen API-Key verwenden - Überprüfen Sie, ob das Produkt nicht gelöscht wurde

Problem: „Der angegebene Zustand ist ungültig“¶

Ursache: Ungültiger Produkttyp oder Filterwert
Lösung: - Verwenden Sie gültige Typwerte: „physical“ oder „digital“ - Stellen Sie sicher, dass die Filterparameter korrekt formatiert sind

• Noch Fragen? Get support.
• Check out the changelog.