Klanten aanmaken met de API

Wat een klant is

Een klant is de persoon of het bedrijf naar wie u een bestelling stuurt: uw koper. Elke bestelling die u via de API aanmaakt, hoort bij een klant. Uw systeem maakt dus eerst de klant aan en daarna de bestellingen voor die klant. Klanten die via de API zijn aangemaakt, verschijnen onder Clients in uw kanaal, net als de klanten die u met de hand toevoegt.

U heeft eerst een API-token nodig. Zie Het Manual/API-kanaal om te lezen hoe u er een krijgt. Het token bepaalt het kanaal: klanten worden aangemaakt in het kanaal waartoe het token behoort. Het token mag niet alleen-lezen zijn.

Het verzoek

Methode	POST
Adres (live)	https://api.aiku.io/dropshipping/clients
Adres (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Headers	Authorization: Bearer gevolgd door uw token Content-Type: application/json

Het antwoord is altijd JSON. U hoeft geen Accept-header mee te sturen.

Een volledig voorbeeld

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

Het kleinste verzoek dat wij accepteren is alleen het land:

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

Een klant zoals deze kan geen pakketten ontvangen, stuur dus altijd het volledige afleveradres mee als u dat heeft.

De velden

Veld	Verplicht	Wat u stuurt
address	Ja	Het afleveradres, als object met de onderstaande velden.
address.country_code	Ja	Het land als ISO-code: twee letters (GB, ES, DE) of drie letters (GBR, ESP, DEU). Hoofdletters of kleine letters.
address.address_line_1	Voor levering	Straat en huisnummer.
address.address_line_2	Nee	Appartement, verdieping, gebouw.
address.locality	Voor levering	Plaats of stad.
address.administrative_area	Hangt van het land af	Graafschap, staat of provincie, als het land die gebruikt.
address.postal_code	Voor levering	Postcode of ZIP.
address.dependent_locality	Nee	Wijk of buurt, als het land die gebruikt.
address.sorting_code	Nee	Alleen voor landen die een sorteercode gebruiken.
reference	Nee	Uw eigen code voor de klant, bijvoorbeeld het klantnummer in uw shop. De code moet uniek zijn in uw kanaal.
contact_name	Nee	De naam van de persoon.
company_name	Nee	De bedrijfsnaam.
email	Nee	Een geldig e-mailadres.
phone	Nee	Minstens 6 tekens. Gebruik het internationale formaat, bijvoorbeeld +44 7700 900123, zodat de koerier kan bellen.

Adresvelden die niet in deze lijst staan, zoals city, state, county of country, worden genegeerd. Gebruik de namen hierboven. Er zijn geen velden first_name of last_name: stuur de volledige naam in contact_name.

Oudere integraties sturen soms address.country_id, ons eigen nummer voor het land. Het werkt nog steeds, maar gebruik country_code: als u beide stuurt, wint country_code.

Het antwoord als het lukt

Wij antwoorden met 201 Created en de nieuwe klant:

{
  "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 is de bedrijfsnaam als u er een stuurt, anders de contactnaam. formatted_address is het adres als HTML, klaar om te tonen.

Bewaar data.id. U heeft het nodig om bestellingen voor deze klant aan te maken: POST /dropshipping/order/client/{id}/store.

Een klant wijzigen

Stuur PATCH naar /dropshipping/clients/{id} met alleen de velden die u wilt wijzigen. Wijzigt u het adres, stuur dan het hele adres mee, inclusief 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" }'

Wij antwoorden met 200 en de klant, in dezelfde vorm als hierboven, en "message": "Client updated successfully".

Uw klanten opzoeken

• GET /dropshipping/clients toont de klanten van uw kanaal, pagina voor pagina.
• GET /dropshipping/clients/{id} toont één klant.
• DELETE /dropshipping/clients/{id} deactiveert een klant. De eerdere bestellingen blijven bewaard.

Om te voorkomen dat u dezelfde koper twee keer aanmaakt, stuurt u uw eigen klantnummer als reference. Een tweede klant met dezelfde reference in hetzelfde kanaal wordt geweigerd.

Als er iets misgaat

Weigeren wij een verzoek vanwege de gegevens, dan antwoorden wij met 422, een message en het veld dat niet klopt onder 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". De body heeft geen address-object. De adresvelden moeten binnen address staan, niet op het hoogste niveau van de body.
• "The country is required". Het adres heeft geen country_code. Voeg het toe.
• "Unknown country code". De code is geen ISO-landcode. Het Verenigd Koninkrijk is GB of GBR, niet UK.
• "The reference has already been taken". Een andere klant in dit kanaal heeft die reference. Gebruik een andere, of wijzig de bestaande klant met PATCH.
• "The phone must be at least 6 characters". Stuur het volledige telefoonnummer, of laat phone weg.
• 401 met een bericht over de Authorization-header. Het token ontbreekt, is onvolledig of is verwijderd. Kopieer het hele token, inclusief het nummer en de | aan het begin. Staging heeft een eigen token nodig.
• 403 "This API token is read only.". Genereer een token zonder Read only aangevinkt.
• 429. Elk token kan tot 120 verzoeken per minuut doen. Vertraag en probeer het na een minuut opnieuw.

Elk verzoek dat uw systeem doet, staat met ons antwoord in het tabblad API calls op de pagina API van uw kanaal. Kijk daar eerst als een verzoek niet doet wat u verwacht.