Vai al contenuto

API Clienti

🤖 Spiega con l'intelligenza artificiale

L’API Clienti è uno strumento che consente alle aziende di gestire e recuperare le informazioni dei clienti in modo sicuro ed efficiente. Con questa API, le aziende possono integrare le funzionalità di gestione dei clienti nei propri siti web, applicazioni e altre soluzioni software.

Supporta funzionalità come la paginazione, la ricerca per nome o email e informazioni dettagliate sui clienti, inclusi nome, email, telefono, foto, paese e metadati personalizzati.

Ottenere un elenco di tutti i clienti

Endpoint

GET /v1/customers/

Questo endpoint recupera un elenco paginato di tutti i clienti per il tuo account. Per impostazione predefinita, restituisce 10 clienti per pagina.

Parametri di query:

Parametro Descrizione Tipo Obbligatorio
page Il numero della pagina da recuperare integer false
page_size Il numero di clienti da visualizzare per pagina (max 100) integer false
search Cerca per nome o email string false

Richiesta (Elenca tutti i clienti):

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

Richiesta (Con paginazione):

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

Richiesta (Ricerca per nome o email):

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

Risposta (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
        }
    ]
}

Ottenere un cliente specifico

Endpoint

GET /v1/customers/{id}/

Questo endpoint recupera i dettagli completi di un cliente specifico tramite il suo ID univoco.

Parametri di percorso:

Parametro Descrizione Tipo Obbligatorio
id L’identificatore univoco di un cliente string true

Richiesta:

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

Risposta (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
}

Cercare clienti

Endpoint

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

Questo endpoint recupera un elenco di clienti che corrispondono a una query di ricerca. Le ricerche vengono eseguite sui campi first_name e email.

Parametri di query:

Parametro Descrizione Tipo Obbligatorio
search La query di ricerca per nome o email string true

Richiesta:

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

Risposta (200 OK - Risultati trovati):

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

Risposta (404 Not Found - Nessun risultato):

{
    "message": {
        "code": 404,
        "title": "Cliente non trovato",
        "content": "Nessun cliente trovato per la query: 'customer_name'.",
        "type": "danger",
        "query": "customer_name"
    }
}

Gestione degli indirizzi

I clienti possono avere fino a 3 indirizzi associati al proprio profilo.

Gestione degli errori

L’API restituisce codici di stato HTTP standard per indicare il successo o il fallimento di una richiesta. Di seguito sono riportati gli errori comuni specifici per i clienti:

400 Bad Request

Si verifica quando la richiesta è malformata o mancano campi obbligatori.

Scenari:

Scenario Messaggio di errore Soluzione
Query di ricerca vuota "La query di ricerca non può essere vuota." Fornire un termine di ricerca non vuoto
Campo obbligatorio mancante "Questo campo è obbligatorio." Includere tutti i campi obbligatori (first_name, last_name, email)
Formato email non valido "Inserisci un indirizzo email valido." Controlla il formato dell’email e riprova

Esempio di risposta di errore:

{
    "code": 400,
    "title": "Richiesta non valida",
    "content": "La query di ricerca non può essere vuota.",
    "type": "danger"
}

401 Unauthorized

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempio:

{
    "detail": "Le credenziali di autenticazione non sono state fornite."
}

Soluzione:

  • Verifica di aver incluso il parametro -u 'sk_test_...: o l’header Authorization: Basic
  • Assicurati che la tua chiave API sia corretta e attiva
  • Testa con Postman utilizzando Basic Auth

404 Not Found

Il cliente richiesto non esiste.

Esempio:

{
    "code": 404,
    "title": "Cliente non trovato",
    "content": "Non è stato possibile trovare il cliente, per favore controlla l'ID.",
    "type": "danger"
}

Soluzione:

  • Verifica che l’ID del cliente esista
  • Usa l’endpoint di elenco per trovare l’ID cliente corretto
  • Assicurati che il cliente appartenga al tuo account sviluppatore

406 Not Acceptable

Si verifica quando si tenta di eseguire un’azione non valida.

Esempio:

{
    "code": 406,
    "title": "Errore di registrazione dell'indirizzo",
    "content": "Il cliente ha già 3 indirizzi registrati.",
    "type": "danger"
}

Soluzione:

  • Elimina un indirizzo esistente prima di crearne uno nuovo
  • Massimo 3 indirizzi per cliente

Note importanti

!!! warning “Informazioni sul cliente” - Gli indirizzi email devono essere univoci all’interno del tuo account - I clienti possono avere fino a 3 indirizzi - L’eliminazione di un cliente non può essere annullata

!!! info “Caricamento foto” - Le foto possono essere caricate come dati multipart form - Formati supportati: JPEG, PNG - Dimensione massima del file: 5MB

!!! note “Metadati” - I metadati sono memorizzati come JSON e possono contenere coppie chiave-valore personalizzate - Usa i metadati per memorizzare informazioni sul cliente specifiche per l’applicazione - Dimensione massima dei metadati: 10KB

!!! note “Test vs Produzione” - Usa la tua Chiave di Test (sk_test_...) per lo sviluppo e il testing - Usa la tua Chiave Live (sk_live_...) per le transazioni reali - Il sistema rileva automaticamente la modalità in base alla Chiave API utilizzata

Migliori pratiche

  1. Valida gli indirizzi email - Assicurati che le email siano univoche e valide prima della creazione
  2. Usa i metadati con saggezza - Memorizza i dati aziendali rilevanti nei metadati per facilitare il filtraggio successivo
  3. Mantieni gli indirizzi aggiornati - Mantieni aggiornate le informazioni sull’indirizzo per una spedizione accurata
  4. Gestisci la paginazione - Usa i numeri di pagina e page_size per elenchi di clienti numerosi
  5. Cerca in modo efficiente - Usa i parametri di ricerca per trovare rapidamente i clienti
  6. Usa indirizzi predefiniti - Contrassegna gli indirizzi preferiti come predefiniti per comodità

Risoluzione dei problemi

Problema: “Il cliente ha già 3 indirizzi registrati”

Causa: Tentativo di aggiungere più di 3 indirizzi a un cliente
Soluzione:

  • Elimina prima un indirizzo esistente
  • Usa l’endpoint DELETE per rimuovere un indirizzo non utilizzato
  • Quindi crea il nuovo indirizzo

Problema: “Non è stato possibile trovare il cliente”

Causa: L’ID cliente non esiste o appartiene a un diverso account sviluppatore
Soluzione:

  • Verifica l’ID cliente utilizzando l’endpoint di elenco
  • Assicurati di utilizzare la chiave API corretta
  • Controlla che il cliente non sia stato eliminato

Problema: “Le credenziali di autenticazione non sono state fornite”

Causa: Autenticazione con chiave API mancante o non valida
Soluzione:

  • Usa -u 'sk_test_...: in cURL
  • Oppure usa l’header Authorization: Basic <base64_encoded_key>
  • Verifica che la tua chiave API sia attiva

FAQ

D: Posso avere indirizzi email duplicati?
A: No, gli indirizzi email devono essere univoci all’interno del tuo account sviluppatore. Il tentativo di creare un duplicato comporterà un errore.

D: Cosa succede alla cronologia dei pagamenti quando elimino un cliente?
A: I log dei pagamenti vengono preservati. È comunque possibile visualizzare la cronologia delle transazioni anche dopo l’eliminazione del cliente.

D: Quanti indirizzi può avere un cliente?
A: Ogni cliente può avere fino a 3 indirizzi. Elimina un indirizzo esistente prima di aggiungerne uno nuovo se il limite è raggiunto.

D: Posso cercare per più campi?
A: Il parametro di ricerca effettua la ricerca tra i campi first_name ed email. Per cercare per altri campi, recupera tutti i clienti e filtra sul tuo lato.

D: Quali dati posso memorizzare nei metadati?
A: I metadati accettano qualsiasi oggetto JSON valido (max 10KB). Gli usi comuni includono il tipo di cliente, la fonte di registrazione, i punti fedeltà, ecc.

D: Con quale frequenza devo aggiornare le informazioni sui clienti?
A: Aggiorna le informazioni ogni volta che cambiano. Non ci sono limiti di frequenza per gli aggiornamenti.