Creare clienti con l'API

Cos'è un cliente

Un cliente è la persona o l'azienda a cui invii un ordine: il tuo acquirente. Ogni ordine che crei tramite l'API appartiene a un cliente, quindi il tuo sistema crea prima il cliente, poi crea gli ordini per lui. I clienti creati tramite l'API compaiono in Clients sotto il tuo canale, come quelli che aggiungi a mano.

Prima ti serve un token API. Vedi Il canale Manual/API per sapere come ottenerlo. Il token decide il canale: i clienti vengono creati nel canale a cui appartiene il token. Il token non deve essere di sola lettura.

La richiesta

Metodo	POST
Indirizzo (reale)	https://api.aiku.io/dropshipping/clients
Indirizzo (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Header	Authorization: Bearer seguito dal tuo token Content-Type: application/json

La risposta è sempre JSON. Non serve inviare un header Accept.

Un esempio completo

curl -X POST https://api.aiku.io/dropshipping/clients \
  -H "Authorization: Bearer 123|AbCdEf..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "WEB-10045",
    "contact_name": "Jane Smith",
    "company_name": "Smith Gifts Ltd",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "address": {
      "address_line_1": "12 High Street",
      "address_line_2": "Flat 3",
      "locality": "Sheffield",
      "administrative_area": "South Yorkshire",
      "postal_code": "S1 2AB",
      "country_code": "GB"
    }
  }'

La richiesta più piccola che accettiamo è solo il paese:

{
  "address": { "country_code": "GB" }
}

Un cliente così non può ricevere pacchi, quindi invia sempre l'indirizzo di consegna completo quando ce l'hai.

I campi

Campo	Obbligatorio	Cosa inviare
address	Sì	L'indirizzo di consegna, come oggetto con i campi qui sotto.
address.country_code	Sì	Il paese come codice ISO: due lettere (GB, ES, DE) o tre lettere (GBR, ESP, DEU). Maiuscolo o minuscolo.
address.address_line_1	Per la consegna	Via e numero.
address.address_line_2	No	Appartamento, piano, edificio.
address.locality	Per la consegna	Città o località.
address.administrative_area	Dipende dal paese	Contea, stato o provincia, dove il paese ne usa una.
address.postal_code	Per la consegna	CAP.
address.dependent_locality	No	Distretto o quartiere, dove il paese ne usa uno.
address.sorting_code	No	Solo per i paesi che usano un codice di smistamento.
reference	No	Un tuo codice per il cliente, per esempio il numero cliente nel tuo negozio. Deve essere unico nel tuo canale.
contact_name	No	Il nome della persona.
company_name	No	Il nome dell'azienda.
email	No	Un indirizzo email valido.
phone	No	Almeno 6 caratteri. Usa il formato internazionale, per esempio +44 7700 900123, così il corriere può chiamare.

I campi dell'indirizzo che non sono in questo elenco, come city, state, county o country, vengono ignorati. Usa i nomi indicati sopra. Non esistono i campi first_name o last_name: invia il nome completo in contact_name.

Le integrazioni più vecchie possono inviare address.country_id, il nostro numero interno per il paese. Funziona ancora, ma usa country_code: se invii entrambi, vince country_code.

La risposta quando funziona

Rispondiamo 201 Created con il nuovo cliente:

{
  "data": {
    "id": 52817,
    "ulid": "01M4639WS5Z7QT08CNW0M0DEJQ",
    "reference": "WEB-10045",
    "active": null,
    "name": "Smith Gifts Ltd",
    "contact_name": "Jane Smith",
    "company_name": "Smith Gifts Ltd",
    "location": ["GB", "United Kingdom", "Sheffield"],
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "created_at": "2026-10-05T13:15:59.000000Z",
    "updated_at": "2026-10-05T13:15:59.000000Z",
    "address": {
      "id": 9123456,
      "address_line_1": "12 High Street",
      "address_line_2": "Flat 3",
      "sorting_code": null,
      "postal_code": "S1 2AB",
      "locality": "Sheffield",
      "dependent_locality": null,
      "administrative_area": "South Yorkshire",
      "country_code": "GB",
      "country_id": 48,
      "checksum": "74d55290109e98f64b7d908a3e66b9d8",
      "created_at": "2026-10-05T13:15:59.000000Z",
      "updated_at": "2026-10-05T13:15:59.000000Z",
      "country": { "code": "GB", "iso3": "GBR", "name": "United Kingdom" },
      "formatted_address": "<p translate=\"no\">...12 High Street<br>Flat 3<br>Sheffield<br>S1 2AB<br>United Kingdom</p>",
      "can_edit": null,
      "can_delete": null
    }
  },
  "message": "Client created successfully"
}

name è il nome dell'azienda quando ne invii uno, altrimenti il nome della persona. formatted_address è l'indirizzo in HTML, pronto da mostrare.

Conserva data.id. Ti serve per creare ordini per questo cliente: POST /dropshipping/order/client/{id}/store.

Modificare un cliente

Invia PATCH a /dropshipping/clients/{id} solo con i campi che vuoi cambiare. Quando cambi l'indirizzo, invia l'indirizzo completo incluso country_code.

curl -X PATCH https://api.aiku.io/dropshipping/clients/52817 \
  -H "Authorization: Bearer 123|AbCdEf..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+44 7700 900999" }'

Rispondiamo 200 con il cliente, nella stessa forma di sopra, e "message": "Client updated successfully".

Trovare i tuoi clienti

• GET /dropshipping/clients elenca i clienti del tuo canale, pagina per pagina.
• GET /dropshipping/clients/{id} mostra un cliente.
• DELETE /dropshipping/clients/{id} disattiva un cliente. I suoi ordini passati vengono conservati.

Per non creare due volte lo stesso acquirente, invia il tuo numero cliente come reference. Un secondo cliente con la stessa reference nello stesso canale viene rifiutato.

Quando qualcosa non funziona

Quando rifiutiamo una richiesta a causa dei dati, rispondiamo 422 con un message e il campo sbagliato sotto errors:

{
  "message": "Unknown country code \"UK\". Send the ISO code of the country, two letters (GB) or three letters (GBR).",
  "errors": {
    "address.country_code": [
      "Unknown country code \"UK\". Send the ISO code of the country, two letters (GB) or three letters (GBR)."
    ]
  }
}

• "The client's delivery address is required". Il corpo non ha un oggetto address. I campi dell'indirizzo devono stare dentro address, non al livello principale del corpo.
• "The country is required". L'indirizzo non ha country_code. Aggiungilo.
• "Unknown country code". Il codice non è un codice paese ISO. Il Regno Unito è GB o GBR, non UK.
• "The reference has already been taken". Un altro cliente in questo canale ha quella reference. Usane una diversa, oppure modifica il cliente esistente con PATCH.
• "The phone must be at least 6 characters". Invia il numero di telefono completo, oppure ometti phone.
• 401 con un messaggio sull'header Authorization. Il token manca, è incompleto o è stato eliminato. Copia tutto il token, compreso il numero e | all'inizio. Staging ha bisogno del suo token.
• 403 "This API token is read only.". Genera un token senza Read only spuntato.
• 429. Ogni token può fare fino a 120 richieste al minuto. Rallenta e riprova dopo un minuto.

Ogni richiesta fatta dal tuo sistema è elencata nella scheda API calls della pagina API del tuo canale, con la risposta che abbiamo dato. Guarda lì per prima cosa quando una richiesta non fa quello che ti aspetti.