Criar clientes com a API

O que é um cliente

Um cliente é a pessoa ou empresa a quem envias uma encomenda: o teu comprador. Cada encomenda que crias através da API pertence a um cliente, por isso o teu sistema cria primeiro o cliente e depois cria encomendas para ele. Os clientes criados através da API aparecem em Clients no teu canal, tal como os que adicionas à mão.

Precisas primeiro de um token da API. Vê O canal Manual/API para saberes como obter um. O token decide o canal: os clientes são criados no canal a que o token pertence. O token não pode ser só de leitura.

O pedido

Método	POST
Endereço (real)	https://api.aiku.io/dropshipping/clients
Endereço (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Cabeçalhos	Authorization: Bearer seguido do teu token Content-Type: application/json

A resposta é sempre JSON. Não precisas de enviar um cabeçalho Accept.

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

O menor pedido que aceitamos é apenas o país:

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

Um cliente assim não pode receber encomendas, por isso envia sempre a morada de entrega completa quando a tiveres.

Os campos

Campo	Obrigatório	O que enviar
address	Sim	A morada de entrega, como um objeto com os campos abaixo.
address.country_code	Sim	O país como código ISO: duas letras (GB, ES, DE) ou três letras (GBR, ESP, DEU). Maiúsculas ou minúsculas.
address.address_line_1	Para entrega	Rua e número.
address.address_line_2	Não	Andar, piso, edifício.
address.locality	Para entrega	Localidade ou cidade.
address.administrative_area	Depende do país	Condado, estado ou província, nos países que usam um.
address.postal_code	Para entrega	Código postal.
address.dependent_locality	Não	Distrito ou bairro, nos países que usam um.
address.sorting_code	Não	Só para países que usam um código de triagem.
reference	Não	O teu próprio código para o cliente, por exemplo o número de cliente na tua loja. Tem de ser único no teu canal.
contact_name	Não	O nome da pessoa.
company_name	Não	O nome da empresa.
email	Não	Um endereço de e-mail válido.
phone	Não	Pelo menos 6 caracteres. Usa o formato internacional, por exemplo +44 7700 900123, para que a transportadora possa ligar.

Os campos de morada que não estão nesta lista, como city, state, county ou country, são ignorados. Usa os nomes acima. Não existem os campos first_name nem last_name: envia o nome completo em contact_name.

Integrações mais antigas podem enviar address.country_id, o nosso número próprio para o país. Ainda funciona, mas usa country_code: se enviares os dois, country_code prevalece.

A resposta quando funciona

Respondemos 201 Created com o novo 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 é o nome da empresa quando envias um, caso contrário é o nome do contacto. formatted_address é a morada em HTML, pronta a mostrar.

Guarda data.id. Precisas dele para criar encomendas para este cliente: POST /dropshipping/order/client/{id}/store.

Mudar um cliente

Envia PATCH para /dropshipping/clients/{id} só com os campos que queres mudar. Quando mudas a morada, envia a morada inteira, incluindo 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 com o cliente, na mesma forma que acima, e "message": "Client updated successfully".

Encontrar os teus clientes

• GET /dropshipping/clients lista os clientes do teu canal, página a página.
• GET /dropshipping/clients/{id} mostra um cliente.
• DELETE /dropshipping/clients/{id} desativa um cliente. As encomendas anteriores mantêm-se.

Para não criares o mesmo comprador duas vezes, envia o teu próprio número de cliente como reference. Um segundo cliente com o mesmo reference no mesmo canal é recusado.

Quando algo corre mal

Quando recusamos um pedido por causa dos dados, respondemos 422 com uma message e o campo errado em 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". O corpo não tem um objeto address. Os campos da morada têm de estar dentro de address, não ao nível superior do corpo.
• "The country is required". A morada não tem country_code. Adiciona-o.
• "Unknown country code". O código não é um código ISO de país. O Reino Unido é GB ou GBR, não UK.
• "The reference has already been taken". Outro cliente deste canal tem esse reference. Usa um diferente, ou muda o cliente existente com PATCH.
• "The phone must be at least 6 characters". Envia o número de telefone completo, ou deixa phone de fora.
• 401 com uma mensagem sobre o cabeçalho Authorization. O token falta, está incompleto ou foi apagado. Copia o token inteiro, incluindo o número e o | do início. O staging precisa do seu próprio token.
• 403 "This API token is read only.". Gera um token sem Read only marcado.
• 429. Cada token pode fazer até 120 pedidos por minuto. Abranda e tenta de novo passado um minuto.

Cada pedido que o teu sistema faz aparece na aba API calls da página API do teu canal, com a resposta que demos. Olha primeiro aí quando um pedido não faz o que esperas.