Pläne-API

🤖 Erklären mit KI

Die Pläne-API ist für die effiziente Verwaltung von Abonnementplänen konzipiert. Sie unterstützt die Erstellung von Plänen, das Auflisten aller Pläne, das Abrufen nach ID, Änderungen und Löschungen, was eine nahtlose Verwaltung von Mitgliedschaften ermöglicht.

Die API sorgt für klare und konsistente Antworten, einschließlich detaillierter Fehlerbehandlung, um Entwicklern eine reibungslose Erfahrung zu bieten.

Einen Plan erstellen¶

Dieser Endpunkt ermöglicht das Erstellen eines neuen wiederkehrenden Plans im System durch Senden einer POST-Anfrage mit den Plandetails – wie Name, Beschreibung, Betrag, Währung, Intervall (Abrechnungshäufigkeit), trial_period_days und ein optionales Bild. Wenn der Vorgang erfolgreich ist, wird die Erstellung des Plans bestätigt und sein eindeutiger Schlüssel bereitgestellt.

Query-Parameter:

Felder im Request-Body:

Anfrage (cURL):

curl -X POST 'https://api.4geeks.io/v1/plans/?test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Premium Plan",
           "description": "Unlimited access to all features",
           "currency": "USD",
           "amount": 9.99,
           "interval": "month",
           "interval_count": 1,
           "trial_period_days": 7,
           "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
         }'

Anfrage (Python):

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/v1/plans/?test=false',
    headers={
        'Authorization': f'Api-Key {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        "name": "Premium Plan",
        "description": "Unlimited access to all features",
        "currency": "USD",
        "amount": 9.99,
        "interval": "month",
        "interval_count": 1,
        "trial_period_days": 7
    }
)
print(response.json())

Anfrage (Postman):

1. Methode: POST
2. URL: https://api.4geeks.io/v1/plans/?test=false
3. Autorisierung: Api-Key mit dem Wert sk_test_51O62xYzAbcDef123
4. Body (raw JSON):

{
    "name": "Premium Plan",
    "description": "Unlimited access to all features",
    "currency": "USD",
    "amount": 9.99,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 7
}

Antwort (201 Created):

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

Alle Pläne abrufen¶

Dieser Endpunkt ruft eine paginierte Liste aller Pläne mit erweiterter Filterunterstützung ab.

Query-Parameter:

Anfrage (Alle Pläne auflisten):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&page_size=10&test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Anfrage (Mit Filtern):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&name=premium&price_min=5&price_max=50&status=active' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Antwort (200 OK):

{
  "count": 2,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "key": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
      "information": {
        "name": "Premium Plan",
        "created": "2025-08-17T20:00:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "9.99",
        "trial_period_days": 7,
        "credit_card_description": "PREMIUM",
        "description": "Unlimited access to all features with premium support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 150,
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    },
    {
      "key": "a1b2c3d4-5678-90ef-ghij-1234567890cd",
      "information": {
        "name": "Basic Plan",
        "created": "2025-08-17T20:05:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "4.99",
        "trial_period_days": 0,
        "credit_card_description": "BASIC",
        "description": "Limited access to basic features with standard support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 45,
        "image": null,
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    }
  ]
}

Einen bestimmten Plan abrufen¶

Dieser Endpunkt ruft die vollständigen Details eines bestimmten Plans anhand seines eindeutigen Schlüssels ab.

Pfad-Parameter:

Query-Parameter:

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Antwort (200 OK):

{
  "key": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "information": {
    "name": "Standard Plan",
    "created": "2025-03-25T08:50:15.732299Z",
    "interval": "month",
    "interval_count": 1,
    "currency": "USD",
    "amount": "19.99",
    "trial_period_days": 0,
    "credit_card_description": "STANDARD",
    "description": "This plan offers access to standard features with basic support.",
    "email": "developer@example.com",
    "company_name": "Acme Corp",
    "page": "https://acme.com",
    "active": true,
    "count": 75,
    "image": null,
    "image_dev": "https://acme.com/logo.png"
  },
  "test": true
}

Antwort (404 Not Found):

{
  "code": 404,
  "title": "Plan existiert nicht",
  "content": "Der angeforderte Plan existiert nicht, bitte überprüfen.",
  "type": "danger"
}

Einen Plan aktualisieren¶

Aktualisiert einen bestehenden Plan mit neuen Details. Sie können einzelne Felder wie Name, Beschreibung, Bild und Testzeitraum in Tagen aktualisieren, ohne andere zu beeinflussen.

Pfad-Parameter:

Query-Parameter:

Felder im Request-Body (alle optional):

Anfrage:

curl -X PUT 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Updated Premium Plan",
           "description": "Updated description with full access to features",
           "trial_period_days": 14,
           "is_test": false
         }'

Antwort (200 OK):

{
    "code": 200,
    "title": "Plan aktualisiert",
    "content": "Der Plan Updated Premium Plan wurde korrekt aktualisiert.",
    "type": "success",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Antwort (404 Not Found):

{
    "code": 404,
    "title": "Plan nicht gefunden",
    "content": "Der Plan mit der ID f9b77185-a62e-4da9-a056-3c7b812ca334 existiert nicht oder Sie haben keine Berechtigung, ihn zu ändern.",
    "type": "danger"
}

Antwort (200 - Keine Änderungen):

{
    "code": 200,
    "title": "Keine Änderungen",
    "content": "Es wurden keine Änderungen am Plan festgestellt.",
    "type": "info",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Einen Plan löschen¶

Löscht einen Plan und alle zugehörigen Abonnements dauerhaft. Wenn ein Plan gelöscht wird, werden alle Kunden mit aktiven Abonnements per E-Mail benachrichtigt.

Pfad-Parameter:

Anfrage:

curl -X DELETE 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Antwort (200 OK):

{
    "code": 200,
    "title": "Plan gelöscht",
    "content": "Der Plan f9b77185-a62e-4da9-a056-3c7b812ca334 wurde erfolgreich gelöscht.",
    "type": "success"
}

Antwort (404 Not Found):

{
    "code": 404,
    "title": "Plan existiert nicht",
    "content": "Der Plan f9b77185-a62e-4da9-a056-3c7b812ca334 existiert nicht oder wurde bereits gelöscht.",
    "type": "danger"
}

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 Pläne 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ültiger Preisbereich",
    "content": "Der Mindestpreis kann nicht größer sein als der Höchstpreis.",
    "type": "warning"
}

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 Header Authorization: Api-Key sk_test_... hinzugefügt haben
• Stellen Sie sicher, dass Ihr API-Key korrekt und aktiv ist
• Testen Sie mit Postman unter Verwendung der Api-Key-Authentifizierungsmethode

404 Not Found¶

Der angeforderte Plan existiert nicht.

Beispiel:

{
    "code": 404,
    "title": "Plan existiert nicht",
    "content": "Der angeforderte Plan existiert nicht, bitte überprüfen.",
    "type": "danger"
}

Lösung:

• Überprüfen Sie, ob der Planschlüssel existiert
• Verwenden Sie den List-Endpunkt, um den korrekten Planschlüssel zu finden
• Stellen Sie sicher, dass der Plan zu Ihrem Entwicklerkonto gehört

Wichtige Hinweise¶

Best Practices¶

1. Klare Plannamen – Verwenden Sie beschreibende Namen, die die Stufe und die Funktionen klar angeben
2. Genaue Beschreibungen – Stellen Sie detaillierte Beschreibungen bereit, was in jedem Plan enthalten ist
3. Angemessene Preisgestaltung – Stellen Sie sicher, dass die Preise wettbewerbsfähig sind und den bereitgestellten Wert widerspiegeln
4. Testzeiträume – Erwägen Sie das Angebot von Testzeiträumen, um die Hürden für die Kundengewinnung zu senken
5. Vor der Produktion testen – Verwenden Sie den Testmodus mit Test-API-Keys zur Validierung
6. Abonnenten überwachen – Verwenden Sie die Abonnentenzahl in den Antworten, um die Planakzeptanz zu verfolgen
7. Plan-Versionierung – Erstellen Sie neue Pläne, anstatt bestehende Pläne mit Abonnenten stark zu ändern
8. Bildoptimierung – Verwenden Sie optimierte Bilder, um die Antwortzeiten der API zu verkürzen

Fehlerbehebung¶

Problem: „Plan existiert nicht“¶

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

Problem: „Authentifizierungsdaten wurden nicht bereitgestellt“¶

Ursache: Fehlende oder ungültige API-Key-Authentifizierung
Lösung: - Verwenden Sie den Header Authorization: Api-Key sk_test_... in Ihrer Anfrage - Überprüfen Sie, ob Ihr API-Key aktiv ist - Testen Sie mit Postman unter Verwendung der Api-Key-Authentifizierung

Problem: „Der Mindestpreis kann nicht größer sein als der Höchstpreis“¶

Ursache: Ungültiger Preisbereichsfilter angegeben
Lösung: - Stellen Sie sicher, dass price_min ≤ price_max - Überprüfen Sie, ob die Filterwerte gültige Zahlen sind

Problem: „Der abgefragte Plan existiert nicht“¶

Ursache: Die Abfragefilter stimmten mit keinem Plan überein
Lösung: - Überprüfen Sie, ob die Filterparameter korrekt sind - Versuchen Sie, alle Pläne ohne Filter aufzulisten - Überprüfen Sie, ob der Plan im Testmodus existiert (Test-Parameter anpassen)

FAQ¶

F: Kann ich den Preis eines bestehenden Plans ändern?
A: Nein, die Preisgestaltung eines Plans ist unveränderlich. Erstellen Sie einen neuen Plan mit dem aktualisierten Preis und migrieren Sie die Kunden darauf.

F: Was passiert, wenn ich einen Plan lösche?
A: Alle aktiven Abonnements werden gekündigt und die Kunden werden benachrichtigt. Diese Aktion kann nicht rückgängig gemacht werden.

F: Kann ich mehrere Pläne mit demselben Namen haben?
A: Ja, aber es wird empfohlen, eindeutige Namen für eine einfachere Verwaltung und Identifizierung zu verwenden.

F: Wie viele Pläne kann ich erstellen?
A: Es gibt keine Begrenzung für die Anzahl der Pläne, die Sie erstellen können.

F: Kann ich Intervall oder interval_count nach der Erstellung aktualisieren?
A: Nein, diese sind unveränderlich. Erstellen Sie einen neuen Plan mit der gewünschten Abrechnungshäufigkeit.

F: Was ist der Unterschied zwischen Intervall und interval_count?
A: interval ist die Einheit (Monat, Jahr) und interval_count ist der Multiplikator (z. B. alle 3 Monate = interval=month, interval_count=3).

F: Kann ich denselben Plan für mehrere Produkte verwenden?
A: Ja, Pläne sind unabhängig von Produkten. Ein Plan stellt eine Konfiguration für einen Abrechnungszyklus dar.

F: Wie überprüfe ich die Anzahl der aktiven Abonnenten für einen Plan?
A: Verwenden Sie die List- oder Get-Endpunkte. Das Feld information.count zeigt die aktiven Abonnements an.

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