Créer des clients avec l'API

5 min de lectura

English Deutsch EspañolFrançaisItaliano Nederlands Português

Traduit pour plus de commodité. En cas de différence, la version anglaise fait foi.

Ce qu'est un client

Un client est la personne ou l'entreprise à qui vous envoyez une commande : votre acheteur. Chaque commande que vous créez via l'API appartient à un client, votre système crée donc d'abord le client, puis crée des commandes pour lui. Les clients créés via l'API apparaissent dans Clients sous votre canal, comme ceux que vous ajoutez à la main.

Il vous faut d'abord un jeton API. Voir Le canal Manuel/API pour l'obtenir. Le jeton détermine le canal : les clients sont créés dans le canal auquel le jeton appartient. Le jeton ne doit pas être en lecture seule.

La requête


Méthode	POST
Adresse (réel)	https://api.aiku.io/dropshipping/clients
Adresse (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
En-têtes	Authorization: Bearer suivi de votre jeton Content-Type: application/json

La réponse est toujours en JSON. Vous n'avez pas besoin d'envoyer d'en-tête Accept.

Un exemple complet

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 plus petite requête que nous acceptons est simplement le pays :

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

Un client comme celui-là ne peut pas recevoir de colis, envoyez donc toujours l'adresse de livraison complète quand vous l'avez.

Les champs

Champ	Obligatoire	Quoi envoyer
address	Oui	L'adresse de livraison, sous forme d'objet avec les champs ci-dessous.
address.country_code	Oui	Le pays sous forme de code ISO : deux lettres (GB, ES, DE) ou trois lettres (GBR, ESP, DEU). Majuscules ou minuscules.
address.address_line_1	Pour la livraison	Rue et numéro.
address.address_line_2	Non	Appartement, étage, bâtiment.
address.locality	Pour la livraison	Ville.
address.administrative_area	Selon le pays	Comté, état ou province, quand le pays en utilise un.
address.postal_code	Pour la livraison	Code postal.
address.dependent_locality	Non	Quartier ou district, quand le pays en utilise un.
address.sorting_code	Non	Seulement pour les pays qui utilisent un code de tri.
reference	Non	Votre propre code pour le client, par exemple le numéro de client dans votre boutique. Il doit être unique dans votre canal.
contact_name	Non	Le nom de la personne.
company_name	Non	Le nom de l'entreprise.
email	Non	Une adresse e-mail valide.
phone	Non	Au moins 6 caractères. Utilisez le format international, par exemple +44 7700 900123, pour que le transporteur puisse appeler.

Les champs d'adresse qui ne figurent pas dans cette liste, comme city, state, county ou country, sont ignorés. Utilisez les noms ci-dessus. Il n'y a pas de champs first_name ou last_name : envoyez le nom complet dans contact_name.

Les anciennes intégrations peuvent envoyer address.country_id, notre propre numéro pour le pays. Cela fonctionne toujours, mais utilisez country_code : si vous envoyez les deux, country_code l'emporte.

La réponse quand tout fonctionne

Nous répondons 201 Created avec le nouveau client :

{
  "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 est le nom de l'entreprise quand vous en envoyez un, sinon le nom du contact. formatted_address est l'adresse en HTML, prête à afficher.

Gardez data.id. Il vous sert à créer des commandes pour ce client : POST /dropshipping/order/client/{id}/store.

Modifier un client

Envoyez PATCH à /dropshipping/clients/{id} avec seulement les champs que vous voulez changer. Quand vous changez l'adresse, envoyez l'adresse complète, country_code compris.

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" }'

Nous répondons 200 avec le client, dans la même forme que ci-dessus, et "message": "Client updated successfully".

Retrouver vos clients

GET /dropshipping/clients liste les clients de votre canal, page par page.
GET /dropshipping/clients/{id} affiche un client.
DELETE /dropshipping/clients/{id} désactive un client. Ses commandes passées sont conservées.

Pour éviter de créer deux fois le même acheteur, envoyez votre propre numéro de client comme reference. Un second client avec la même reference dans le même canal est refusé.

En cas de problème

Quand nous refusons une requête à cause des données, nous répondons 422 avec un message et le champ erroné sous 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". Le corps n'a pas d'objet address. Les champs d'adresse doivent être à l'intérieur de address, pas au premier niveau du corps.
"The country is required". L'adresse n'a pas de country_code. Ajoutez-le.
"Unknown country code". Le code n'est pas un code pays ISO. Le Royaume-Uni est GB ou GBR, pas UK.
"The reference has already been taken". Un autre client de ce canal a cette reference. Utilisez-en une autre, ou modifiez le client existant avec PATCH.
"The phone must be at least 6 characters". Envoyez le numéro de téléphone complet, ou omettez phone.
401 avec un message sur l'en-tête Authorization. Le jeton est absent, incomplet ou supprimé. Copiez le jeton en entier, y compris le numéro et le | au début. Le staging a besoin de son propre jeton.
403 "This API token is read only.". Générez un jeton sans Read only coché.
429. Chaque jeton peut faire jusqu'à 120 requêtes par minute. Ralentissez et réessayez après une minute.

Chaque requête que fait votre système est listée dans l'onglet API calls de la page API de votre canal, avec la réponse que nous avons donnée. Regardez d'abord là quand une requête ne fait pas ce que vous attendez.