API de Clientes

Crie, consulte, atualize e exclua clientes da sua loja.

Endpoints

GET

/customers

customers:read

Obter uma lista paginada de clientes.

GET

/customers/:id

customers:read

Obter um cliente pelo ID.

POST

/customers

customers:write

Criar um novo cliente.

PUT

/customers/:id

customers:write

Atualizar um cliente existente. Atualizacoes parciais sao suportadas.

DELETE

/customers/:id

customers:write

Exclusao suave de um cliente. O registro pode ser restaurado em 30 dias.

Referencia de Campos

Campo	Tipo	Obrigatorio	Descricao
id	string	Nao	Identificador unico do cliente (somente leitura)
name	string	Sim	Nome completo do cliente
email	string	Sim	Email do cliente
phone	string	Nao	Numero de telefone com codigo do pais
createdAt	datetime	Nao	Timestamp ISO 8601 (somente leitura)
updatedAt	datetime	Nao	Timestamp ISO 8601 (somente leitura)

Parametros de Consulta (Lista)

Campo	Tipo	Obrigatorio	Descricao
page	integer	Nao	Numero da pagina (padrao: 1)
limit	integer	Nao	Itens por pagina (padrao: 20, maximo: 100)
q	string	Nao	Buscar por nome ou email do cliente

Exemplo

Listar clientes com paginacao

bash

curl "https://api.mercozy.com/api/v1/external/customers?page=1&limit=20" \
  -H "X-API-Key: mk_live_xxxxx"

Criar um cliente

bash

curl -X POST "https://api.mercozy.com/api/v1/external/customers" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

Exemplo de Resposta

json

{
  "data": {
    "id": "cust_abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "createdAt": "2025-12-15T10:30:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}