Kunden mit der API anlegen

Was ein Kunde ist

Ein Kunde ist die Person oder das Unternehmen, an die Sie eine Bestellung senden: Ihr Käufer. Jede Bestellung, die Sie über die API erstellen, gehört zu einem Kunden, daher legt Ihr System zuerst den Kunden an und erstellt dann Bestellungen für ihn. Über die API angelegte Kunden erscheinen unter Clients in Ihrem Kanal, genau wie die, die Sie von Hand hinzufügen.

Sie brauchen zuerst ein API-Token. Siehe The Manual/API channel, wie Sie eines erhalten. Das Token bestimmt den Kanal: Kunden werden in dem Kanal angelegt, zu dem das Token gehört. Das Token darf nicht nur lesend sein.

Die Anfrage

Methode	POST
Adresse (live)	https://api.aiku.io/dropshipping/clients
Adresse (Staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Header	Authorization: Bearer, gefolgt von Ihrem Token Content-Type: application/json

Die Antwort ist immer JSON. Sie müssen keinen Accept-Header senden.

Ein vollständiges Beispiel

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

Die kleinste Anfrage, die wir akzeptieren, ist nur das Land:

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

Ein solcher Kunde kann keine Pakete empfangen, senden Sie deshalb immer die vollständige Lieferadresse, wenn Sie sie haben.

Die Felder

Feld	Erforderlich	Was zu senden ist
address	Ja	Die Lieferadresse, als Objekt mit den folgenden Feldern.
address.country_code	Ja	Das Land als ISO-Code: zwei Buchstaben (GB, ES, DE) oder drei Buchstaben (GBR, ESP, DEU). Groß- oder Kleinschreibung.
address.address_line_1	Für die Lieferung	Straße und Hausnummer.
address.address_line_2	Nein	Wohnung, Stockwerk, Gebäude.
address.locality	Für die Lieferung	Ort oder Stadt.
address.administrative_area	Je nach Land	Grafschaft, Bundesland oder Provinz, wenn das Land eine verwendet.
address.postal_code	Für die Lieferung	Postleitzahl.
address.dependent_locality	Nein	Stadtteil oder Ortsteil, wenn das Land einen verwendet.
address.sorting_code	Nein	Nur für Länder, die einen Sortiercode verwenden.
reference	Nein	Ihr eigener Code für den Kunden, zum Beispiel die Kundennummer in Ihrem Shop. Er muss in Ihrem Kanal eindeutig sein.
contact_name	Nein	Der Name der Person.
company_name	Nein	Der Firmenname.
email	Nein	Eine gültige E-Mail-Adresse.
phone	Nein	Mindestens 6 Zeichen. Verwenden Sie das internationale Format, zum Beispiel +44 7700 900123, damit der Zusteller anrufen kann.

Adressfelder, die nicht in dieser Liste stehen, wie city, state, county oder country, werden ignoriert. Verwenden Sie die oben genannten Namen. Es gibt keine Felder first_name oder last_name: Senden Sie den vollständigen Namen in contact_name.

Ältere Integrationen senden möglicherweise address.country_id, unsere eigene Nummer für das Land. Das funktioniert weiterhin, verwenden Sie aber country_code: Wenn Sie beide senden, gilt country_code.

Die Antwort, wenn es funktioniert

Wir antworten mit 201 Created und dem neuen Kunden:

{
  "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 ist der Firmenname, wenn Sie einen senden, sonst der Kontaktname. formatted_address ist die Adresse als HTML, bereit zur Anzeige.

Bewahren Sie data.id auf. Sie brauchen sie, um Bestellungen für diesen Kunden zu erstellen: POST /dropshipping/order/client/{id}/store.

Einen Kunden ändern

Senden Sie PATCH an /dropshipping/clients/{id} mit nur den Feldern, die Sie ändern möchten. Wenn Sie die Adresse ändern, senden Sie die ganze Adresse einschließlich 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" }'

Wir antworten mit 200 und dem Kunden, in derselben Form wie oben, und "message": "Client updated successfully".

Ihre Kunden finden

• GET /dropshipping/clients listet die Kunden Ihres Kanals seitenweise auf.
• GET /dropshipping/clients/{id} zeigt einen Kunden.
• DELETE /dropshipping/clients/{id} deaktiviert einen Kunden. Seine vergangenen Bestellungen bleiben erhalten.

Um zu vermeiden, denselben Käufer zweimal anzulegen, senden Sie Ihre eigene Kundennummer als reference. Ein zweiter Kunde mit derselben reference im selben Kanal wird abgelehnt.

Wenn etwas schiefgeht

Lehnen wir eine Anfrage wegen der Daten ab, antworten wir mit 422 und einer message sowie dem fehlerhaften Feld unter 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". Der Body enthält kein address-Objekt. Die Adressfelder müssen innerhalb von address stehen, nicht auf der obersten Ebene des Bodys.
• "The country is required". Die Adresse hat kein country_code. Fügen Sie es hinzu.
• "Unknown country code". Der Code ist kein ISO-Ländercode. Das Vereinigte Königreich ist GB oder GBR, nicht UK.
• "The reference has already been taken". Ein anderer Kunde in diesem Kanal hat diese reference. Verwenden Sie eine andere, oder ändern Sie den bestehenden Kunden mit PATCH.
• "The phone must be at least 6 characters". Senden Sie die vollständige Telefonnummer, oder lassen Sie phone weg.
• 401 mit einer Meldung über den Authorization-Header. Das Token fehlt, ist unvollständig oder wurde gelöscht. Kopieren Sie das ganze Token, einschließlich der Zahl und des | am Anfang. Staging braucht sein eigenes Token.
• 403 "This API token is read only.". Erzeugen Sie ein Token ohne angehaktes Read only.
• 429. Jedes Token kann bis zu 120 Anfragen pro Minute stellen. Verlangsamen Sie Ihr System und versuchen Sie es nach einer Minute erneut.

Jede Anfrage Ihres Systems wird im Tab API calls auf der Seite API Ihres Kanals aufgeführt, mit der Antwort, die wir gegeben haben. Schauen Sie zuerst dort nach, wenn eine Anfrage nicht das tut, was Sie erwarten.