Crear clientes con la API

Qué es un cliente

Un cliente es la persona o empresa a la que envías un pedido: tu comprador. Cada pedido que creas a través de la API pertenece a un cliente, así que tu sistema crea primero el cliente y después crea pedidos para él. Los clientes creados a través de la API aparecen en Clientes bajo tu canal, igual que los que añades a mano.

Primero necesitas un token de API. Consulta El canal Manual/API para saber cómo obtenerlo. El token decide el canal: los clientes se crean en el canal al que pertenece el token. El token no debe ser de solo lectura.

La petición

Método	POST
Dirección (sitio real)	https://api.aiku.io/dropshipping/clients
Dirección (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Cabeceras	Authorization: Bearer seguida de tu token Content-Type: application/json

La respuesta siempre es JSON. No necesitas enviar la cabecera Accept.

Un ejemplo 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 petición más pequeña que aceptamos es solo el país:

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

Un cliente así no puede recibir paquetes, por eso envía siempre la dirección de entrega completa cuando la tengas.

Los campos

Campo	Obligatorio	Qué enviar
address	Sí	La dirección de entrega, como un objeto con los campos de abajo.
address.country_code	Sí	El país como código ISO: dos letras (GB, ES, DE) o tres letras (GBR, ESP, DEU). En mayúsculas o minúsculas.
address.address_line_1	Para la entrega	Calle y número.
address.address_line_2	No	Piso, planta, edificio.
address.locality	Para la entrega	Población o ciudad.
address.administrative_area	Depende del país	Condado, estado o provincia, si el país usa uno.
address.postal_code	Para la entrega	Código postal.
address.dependent_locality	No	Distrito o barrio, si el país usa uno.
address.sorting_code	No	Solo para países que usan un código de clasificación.
reference	No	Tu propio código para el cliente, por ejemplo el número de cliente en tu tienda. Debe ser único en tu canal.
contact_name	No	El nombre de la persona.
company_name	No	El nombre de la empresa.
email	No	Una dirección de correo válida.
phone	No	Al menos 6 caracteres. Usa el formato internacional, por ejemplo +44 7700 900123, para que el transportista pueda llamar.

Los campos de dirección que no están en esta lista, como city, state, county o country, se ignoran. Usa los nombres de arriba. No existen los campos first_name ni last_name: envía el nombre completo en contact_name.

Las integraciones antiguas pueden enviar address.country_id, nuestro propio número para el país. Sigue funcionando, pero usa country_code: si envías los dos, gana country_code.

La respuesta cuando funciona

Respondemos 201 Created con el nuevo 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 es el nombre de la empresa cuando envías uno; si no, el nombre de contacto. formatted_address es la dirección en HTML, lista para mostrar.

Guarda data.id. Lo necesitas para crear pedidos de este cliente: POST /dropshipping/order/client/{id}/store.

Cambiar un cliente

Envía PATCH a /dropshipping/clients/{id} solo con los campos que quieres cambiar. Cuando cambies la dirección, envía la dirección completa, incluido 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" }'

Respondemos 200 con el cliente, con la misma forma de arriba, y "message": "Client updated successfully".

Buscar tus clientes

• GET /dropshipping/clients lista los clientes de tu canal, página por página.
• GET /dropshipping/clients/{id} muestra un cliente.
• DELETE /dropshipping/clients/{id} desactiva un cliente. Sus pedidos anteriores se conservan.

Para no crear dos veces al mismo comprador, envía tu propio número de cliente como reference. Un segundo cliente con la misma reference en el mismo canal se rechaza.

Cuando algo va mal

Cuando rechazamos una petición por los datos, respondemos 422 con un message y el campo incorrecto en 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". El cuerpo no tiene el objeto address. Los campos de dirección deben ir dentro de address, no en el nivel superior del cuerpo.
• "The country is required". La dirección no tiene country_code. Añádelo.
• "Unknown country code". El código no es un código ISO de país. El Reino Unido es GB o GBR, no UK.
• "The reference has already been taken". Otro cliente de este canal tiene esa reference. Usa otra, o cambia el cliente existente con PATCH.
• "The phone must be at least 6 characters". Envía el número de teléfono completo, o deja fuera phone.
• 401 con un mensaje sobre la cabecera Authorization. El token falta, está incompleto o fue borrado. Copia el token entero, incluido el número y el | del principio. Staging necesita su propio token.
• 403 "This API token is read only.". Genera un token sin marcar Read only.
• 429. Cada token puede hacer hasta 120 peticiones por minuto. Ralentiza tu sistema e inténtalo de nuevo pasado un minuto.

Cada petición que hace tu sistema aparece en la pestaña API calls de la página API de tu canal, con la respuesta que dimos. Mira ahí primero cuando una petición no haga lo que esperas.