Kunden-API

🤖 Erklären mit KI

Die Kunden-API ist ein Tool, mit dem Unternehmen Kundeninformationen sicher und effizient verwalten und abrufen können. Mit dieser API können Unternehmen Kundenverwaltungsfunktionen in ihre Websites, Anwendungen und andere Softwarelösungen integrieren.

Es werden Funktionen wie Pagination, Suche nach Name oder E-Mail sowie detaillierte Kundeninformationen wie Name, E-Mail, Telefon, Foto, Land und benutzerdefinierte Metadaten unterstützt.

Eine Liste aller Kunden abrufen¶

Endpunkt

GET /v1/customers/

Dieser Endpunkt ruft eine paginierte Liste aller Kunden für Ihr Konto ab. Standardmäßig werden 10 Kunden pro Seite zurückgegeben.

Query-Parameter:

Parameter	Beschreibung	Typ	Erforderlich
page	Die abzurufende Seitennummer	integer	nein
page_size	Die Anzahl der Kunden, die pro Seite angezeigt werden sollen (max. 100)	integer	nein
search	Suche nach Vorname oder E-Mail	string	nein

Anfrage (Alle Kunden auflisten):

curl -X GET 'https://api.4geeks.io/v1/customers/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Anfrage (Mit Pagination):

curl -X GET 'https://api.4geeks.io/v1/customers/?page=2&page_size=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Anfrage (Suche nach Name oder E-Mail):

curl -X GET 'https://api.4geeks.io/v1/customers/?search=john' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
    "count": 38,
    "next": "https://api.4geeks.io/v1/customers/?page=3",
    "previous": "https://api.4geeks.io/v1/customers/",
    "results": [
        {
            "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
            "developer": 2875,
            "first_name": "test",
            "last_name": "test",
            "email": "shadya.mora+401@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
            "country": null,
            "metadata": null,
            "test": true
        },
        {
            "id": "3048a540-e825-4ccf-a693-fc4771c5f216",
            "developer": 2875,
            "first_name": "panchos",
            "last_name": "Cruz",
            "email": "marco.cruz+24@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/79a1c28ca1ef7df0e2b80c4eb4367cbf?d=monsterid",
            "country": "Costa Rica",
            "metadata": null,
            "test": true
        }
    ]
}

Einen bestimmten Kunden abrufen¶

Endpunkt

GET /v1/customers/{id}/

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

Pfad-Parameter:

Parameter	Beschreibung	Typ	Erforderlich
id	Die eindeutige Kennung eines Kunden	string	ja

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/customers/03124bfa-a8gd-4e63-823f-90540b9akcff/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
    "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
    "developer": 2875,
    "first_name": "test",
    "last_name": "test",
    "email": "shadya.mora+401@4geeks.io",
    "phone": "+50683236988",
    "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
    "country": "Costa Rica",
    "metadata": null,
    "test": true
}

Suche nach Kunden¶

Endpunkt

GET /v1/customers/?search={query}

Dieser Endpunkt ruft eine Liste von Kunden ab, die einer Suchanfrage entsprechen. Suchen werden in den Feldern first_name und email durchgeführt.

Query-Parameter:

Parameter	Beschreibung	Typ	Erforderlich
search	Die Suchanfrage zum Abgleich nach Name oder E-Mail	string	ja

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/customers/?search=alejandro' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK - Ergebnisse gefunden):

[
    {
        "id": "004b75b1-64d9-42cc-8556-1b111611b67b",
        "developer_id": 2875,
        "first_name": "Shadya",
        "last_name": "Mora Sánchez",
        "email": "shadya.mora@4geeks.io",
        "phone": null,
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Shadya_Mora_test_1696356164.None",
        "country": "Costa Rica",
        "pay_providers": [
            {
                "id": "cus_NHLcuJNDnJDTnK",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-02-26T06:56:07.152267Z",
        "test": false
    },
    {
        "id": "008ffa95-31be-41f8-b797-a4d75aafb9a5",
        "developer_id": 2875,
        "first_name": "Josito",
        "last_name": "Urenas",
        "email": "jose.urena+407@4geeks.io",
        "phone": "000000000",
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Josito_Urenas_test_1696279031.jpeg",
        "country": "Argentina",
        "pay_providers": [
            {
                "id": "cus_NWeHJ69zAJZx9Y",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-03-14T16:46:08.241614Z",
        "test": true
    }
]

Antwort (404 Not Found - Keine Ergebnisse):

{
    "message": {
        "code": 404,
        "title": "Kunde nicht gefunden",
        "content": "Es wurden keine Kunden gefunden, die der Suchanfrage entsprechen: 'customer_name'.",
        "type": "danger",
        "query": "customer_name"
    }
}

Adressverwaltung¶

Kunden können bis zu 3 Adressen mit ihrem Profil verknüpft haben.

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 Kunden sind:

400 Bad Request¶

Tritt auf, wenn die Anfrage fehlerhaft ist oder erforderliche Felder fehlen.

Szenarien:

Szenario	Fehlermeldung	Lösung
Leere Suchanfrage	`"Die Suchanfrage darf nicht leer sein."`	Geben Sie einen nicht leeren Suchbegriff an
Fehlendes erforderliches Feld	`"Dieses Feld ist erforderlich."`	Geben Sie alle erforderlichen Felder an (first_name, last_name, email)
Ungültiges E-Mail-Format	`"Geben Sie eine gültige E-Mail-Adresse ein."`	Überprüfen Sie das E-Mail-Format und versuchen Sie es erneut

Beispiel für eine Fehlerantwort:

{
    "code": 400,
    "title": "Ungültige Anfrage",
    "content": "Die Suchanfrage darf nicht leer sein.",
    "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¶

Der angeforderte Kunde existiert nicht.

Beispiel:

{
    "code": 404,
    "title": "Kunde nicht gefunden",
    "content": "Der Kunde konnte nicht gefunden werden, bitte überprüfen Sie die ID.",
    "type": "danger"
}

Lösung:

Überprüfen Sie, ob die Kunden-ID existiert
Verwenden Sie den List-Endpunkt, um die korrekte Kunden-ID zu finden
Stellen Sie sicher, dass der Kunde zu Ihrem Entwicklerkonto gehört

406 Not Acceptable¶

Tritt auf, wenn versucht wird, eine ungültige Aktion auszuführen.

Beispiel:

{
    "code": 406,
    "title": "Fehler bei der Adressregistrierung",
    "content": "Der Kunde hat bereits 3 Adressen registriert.",
    "type": "danger"
}

Lösung:

Löschen Sie eine vorhandene Adresse, bevor Sie eine neue erstellen
Maximal 3 Adressen pro Kunde

Wichtige Hinweise¶

!!! warning “Kundeninformationen” - E-Mail-Adressen müssen innerhalb Ihres Kontos eindeutig sein - Kunden können bis zu 3 Adressen haben - Das Löschen eines Kunden kann nicht rückgängig gemacht werden

!!! info “Foto-Upload” - Fotos können als Multipart-Form-Daten hochgeladen werden - Unterstützte Formate: JPEG, PNG - Maximale Dateigröße: 5MB

!!! note “Metadaten” - Metadaten werden als JSON gespeichert und können benutzerdefinierte Schlüssel-Wert-Paare enthalten - Verwenden Sie Metadaten, um anwendungsspezifische Kundeninformationen zu speichern - Maximale Metadatengröße: 10KB

!!! note “Test vs Produktion” - Verwenden Sie Ihren Test-Key (sk_test_...) für die Entwicklung und zum Testen - Verwenden Sie Ihren Live-Key (sk_live_...) für echte Transaktionen - Das System erkennt den Modus automatisch anhand des verwendeten API-Keys

Best Practices¶

E-Mail-Adressen validieren - Stellen Sie sicher, dass E-Mails eindeutig und gültig sind, bevor Sie einen Kunden erstellen
Metadaten klug einsetzen - Speichern Sie relevante Geschäftsdaten in den Metadaten für eine spätere einfache Filterung
Adressen aktuell halten - Halten Sie die Adressinformationen für einen genauen Versand aktuell
Pagination handhaben - Verwenden Sie Seitennummern und page_size für große Kundenlisten
Effizient suchen - Verwenden Sie Suchparameter, um Kunden schnell zu finden
Standardadressen verwenden - Markieren Sie bevorzugte Adressen als Standardadresse

Fehlerbehebung¶

Problem: „Der Kunde hat bereits 3 Adressen registriert“¶

Ursache: Versuch, einem Kunden mehr als 3 Adressen hinzuzufügen
Lösung:

Löschen Sie zuerst eine vorhandene Adresse
Verwenden Sie den DELETE-Endpunkt, um eine ungenutzte Adresse zu entfernen
Erstellen Sie dann die neue Adresse

Problem: „Der Kunde konnte nicht gefunden werden“¶

Ursache: Kunden-ID existiert nicht oder gehört zu einem anderen Entwicklerkonto
Lösung:

Überprüfen Sie die Kunden-ID über den List-Endpunkt
Stellen Sie sicher, dass Sie den richtigen API-Key verwenden
Überprüfen Sie, ob der Kunde nicht gelöscht wurde

Problem: „Authentifizierungsdaten wurden nicht bereitgestellt“¶

Ursache: Fehlende oder ungültige API-Key-Authentifizierung
Lösung:

Verwenden Sie -u 'sk_test_...: in cURL
Oder verwenden Sie den Header Authorization: Basic <base64_encoded_key>
Überprüfen Sie, ob Ihr API-Key aktiv ist

FAQ¶

F: Kann ich doppelte E-Mail-Adressen haben?
A: Nein, E-Mail-Adressen müssen innerhalb Ihres Entwicklerkontos eindeutig sein. Der Versuch, ein Duplikat zu erstellen, führt zu einem Fehler.

F: Was passiert mit der Zahlungshistorie, wenn ich einen Kunden lösche?
A: Die Zahlungsprotokolle bleiben erhalten. Sie können die Transaktionshistorie auch nach dem Löschen eines Kunden weiterhin einsehen.

F: Wie viele Adressen kann ein Kunde haben?
A: Jeder Kunde kann bis zu 3 Adressen haben. Löschen Sie eine vorhandene Adresse, bevor Sie eine neue hinzufügen, wenn das Limit erreicht ist.

F: Kann ich nach mehreren Feldern suchen?
A: Der Suchparameter sucht in den Feldern first_name und email. Um nach anderen Feldern zu suchen, rufen Sie alle Kunden ab und filtern Sie auf Ihrer Seite.

F: Welche Daten kann ich in Metadaten speichern?
A: Metadaten akzeptieren jedes gültige JSON-Objekt (max. 10KB). Häufige Verwendungszwecke sind Kundentyp, Registrierungsquelle, Treuepunkte usw.

F: Wie oft sollte ich die Kundeninformationen aktualisieren?
A: Aktualisieren Sie Informationen, wann immer sie sich ändern. Es gibt keine Ratenbegrenzungen für Aktualisierungen.

Noch Fragen? Get support.
Check out the changelog.