Clientes

Os clientes são os compradores finais da sua loja. Este recurso cobre os dois lados da experiência: a gestão administrativa, feita pelo lojista (user), e a conta do comprador (customer), com registro, autenticação e recuperação de senha.

Todas as requisições devem incluir o header X-Shop-Id (UUID) identificando a loja. Os endpoints protegidos exigem também o header Authorization: Bearer {token} — os públicos são marcados com [public].

Endpoints do Comprador

Endpoints voltados para a área do comprador no frontend da loja. Os endpoints de autenticação (login, register, forgot-password) possuem limite de requisições mais restrito.

Registrar Conta `[public]`

Cria uma nova conta de comprador na loja.

http

POST /v1/shop/customer/public/register

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome do comprador (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome (máx. 100 caracteres).
`email`	`string`	Sim	E-mail único na loja (máx. 250 caracteres).
`password`	`string`	Sim	Senha entre 8 e 32 caracteres.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/shop/customer/public/register" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "cliente@exemplo.com",
    "password": "SenhaForte@123"
  }'

Respostas

201 Created

Conta criada com sucesso. Sem corpo na resposta.

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "Email já cadastrado",
      "rule": "database.unique",
      "field": "email"
    }
  ]
}

Login `[public]`

Autentica o comprador e retorna um token de acesso (Bearer) com validade.

http

POST /v1/shop/customer/public/login

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail cadastrado na loja.
`password`	`string`	Sim	Senha da conta (8 a 32 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/shop/customer/public/login" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cliente@exemplo.com",
    "password": "SenhaForte@123"
  }'

Respostas

200 OK

Retorna o token de acesso do comprador.

json

{
  "type": "bearer",
  "name": "00000000-0000-4000-8000-000000000000",
  "token": "{token}",
  "abilities": ["*"],
  "lastUsedAt": null,
  "expiresAt": "2026-07-27T20:41:17.945Z"
}

Esqueci a Senha `[public]`

Inicia o fluxo de recuperação de senha. Um código é enviado para o e-mail do comprador.

http

POST /v1/shop/customer/public/forgot-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail de uma conta existente na loja.

Respostas

201 Created

Solicitação processada com sucesso. Sem corpo na resposta.

Redefinir Senha `[public]`

Conclui a recuperação de senha usando o código recebido por e-mail.

http

PATCH /v1/shop/customer/public/reset-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail da conta.
`code`	`string`	Sim	Código de recuperação enviado por e-mail (máx. 20 caracteres).
`password`	`string`	Sim	Nova senha (8 a 32 caracteres).

Exemplo de Requisição

bash

curl -X PATCH "https://api.us.basis.tavares.in/v1/shop/customer/public/reset-password" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cliente@exemplo.com",
    "code": "1d44fcb",
    "password": "SenhaForte@123"
  }'

Respostas

204 No Content

Senha redefinida com sucesso.

Obter Conta

Retorna os dados da conta do comprador autenticado.

http

GET /v1/shop/customer/account

Exemplo de Requisição

javascript

fetch('https://api.us.basis.tavares.in/v1/shop/customer/account', {
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Shop-Id': '00000000-0000-4000-8000-000000000000'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

200 OK

Retorna os dados da conta.

json

{
  "id": "5",
  "hash": "00000000-0000-4000-8000-000000000000",
  "firstName": "Maria",
  "lastName": "Silva",
  "email": "cliente@exemplo.com",
  "createdAt": "2026-06-27T17:18:41.157+00:00",
  "updatedAt": "2026-06-27T17:18:41.157+00:00"
}

Atualizar Conta

Atualiza os dados cadastrais do comprador autenticado.

http

PUT /v1/shop/customer/update-account

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome (máx. 100 caracteres).
`email`	`string`	Sim	E-mail único na loja (máx. 250 caracteres).

Respostas

204 No Content

Conta atualizada com sucesso.

Alterar Senha

Altera a senha do comprador autenticado.

http

PATCH /v1/shop/customer/change-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`password`	`string`	Sim	Nova senha (8 a 32 caracteres).

Respostas

204 No Content

Senha alterada com sucesso.

Excluir Conta

Remove permanentemente a conta do comprador autenticado.

http

DELETE /v1/shop/customer/destroy-account

Respostas

204 No Content

Conta removida com sucesso.

Logout

Encerra a sessão do comprador, invalidando o token atual.

http

POST /v1/shop/customer/logout

Respostas

204 No Content

Sessão encerrada com sucesso.

Endpoints Administrativos

Endpoints protegidos para o lojista gerenciar os clientes da sua loja. Requerem autenticação de usuário do shop.

Listar Clientes

Retorna uma lista paginada dos clientes cadastrados na loja.

http

GET /v1/shop/user/customers

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	Número da página (mín. 1).
`perPage`	`number`	Não	Itens por página (máx. 100).
`search`	`string`	Não	Busca por termo (máx. 150 caracteres).
`orderBy`	`enum`	Não	`id`, `firstName`, `email` ou `createdAt`.
`orderDirection`	`enum`	Não	`asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/customers?perPage=25&page=1&orderBy=id&orderDirection=desc" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de clientes e metadados.

json

{
  "meta": {
    "total": 2,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=1",
    "nextPageUrl": null,
    "previousPageUrl": null
  },
  "data": [
    {
      "id": "3",
      "firstName": "Maria",
      "lastName": "Silva",
      "email": "cliente@exemplo.com",
      "createdAt": "2026-06-23T21:54:53.125+00:00",
      "updatedAt": "2026-06-23T21:54:53.125+00:00"
    }
  ]
}

Listar Clientes (Select)

Retorna uma lista simplificada de clientes, ideal para campos de seleção (autocomplete).

http

GET /v1/shop/user/customers/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Busca por termo (máx. 150 caracteres).
`limit`	`number`	Não	Quantidade máxima de itens (máx. 300).
`orderBy`	`enum`	Não	`value` ou `label`.
`orderDirection`	`enum`	Não	`asc` ou `desc`.

Respostas

200 OK

Retorna um array de opções com label e value.

json

[
  {
    "label": "Maria Silva <cliente@exemplo.com>",
    "value": "3"
  }
]

Criar Cliente

Cadastra um novo cliente na loja pelo painel administrativo.

http

POST /v1/shop/user/customers

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome (máx. 100 caracteres).
`email`	`string`	Sim	E-mail único na loja (máx. 200 caracteres).
`password`	`string`	Sim	Senha entre 8 e 32 caracteres.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/shop/user/customers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "cliente@exemplo.com",
    "password": "SenhaForte@123"
  }'

Respostas

201 Created

Retorna o ID do cliente criado.

json

{
  "id": "2"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "Email em uso",
      "rule": "database.unique",
      "field": "email"
    }
  ]
}

Obter Cliente

Recupera os detalhes de um cliente específico.

http

GET /v1/shop/user/customers/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	ID do cliente.

Respostas

200 OK

Retorna os dados do cliente.

json

{
  "id": "2",
  "hash": "00000000-0000-4000-8000-000000000000",
  "firstName": "Maria",
  "lastName": "Silva",
  "email": "cliente@exemplo.com",
  "createdAt": "2026-06-23T21:53:13.091+00:00",
  "updatedAt": "2026-06-23T21:53:13.091+00:00"
}

404 Not Found

Ocorre quando o cliente não existe na loja.

Atualizar Cliente

Atualiza os dados de um cliente existente.

http

PUT /v1/shop/user/customers/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome (máx. 100 caracteres).
`email`	`string`	Sim	E-mail único na loja (máx. 200 caracteres).

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/shop/user/customers/2" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "cliente@exemplo.com"
  }'

Respostas

204 No Content

Cliente atualizado com sucesso.

Alterar Senha do Cliente

Redefine a senha de um cliente pelo painel administrativo.

http

PATCH /v1/shop/user/customers/:id/change-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`password`	`string`	Sim	Nova senha (8 a 32 caracteres).

Respostas

204 No Content

Senha alterada com sucesso.

Remover Cliente

Exclui um cliente da loja.

http

DELETE /v1/shop/user/customers/:id

Respostas

204 No Content

Remoção concluída com sucesso.

Clientes ​

Endpoints do Comprador ​

Registrar Conta [public] ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Login [public] ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Esqueci a Senha [public] ​

Payload (Body) ​

Respostas ​

Redefinir Senha [public] ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Conta ​

Exemplo de Requisição ​

Respostas ​

Atualizar Conta ​

Payload (Body) ​

Respostas ​

Alterar Senha ​

Payload (Body) ​

Respostas ​

Excluir Conta ​

Respostas ​

Logout ​

Respostas ​

Endpoints Administrativos ​

Listar Clientes ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Listar Clientes (Select) ​

Parâmetros de Query ​

Respostas ​

Criar Cliente ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Cliente ​

Parâmetros de Rota ​

Respostas ​

Atualizar Cliente ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Alterar Senha do Cliente ​

Payload (Body) ​

Respostas ​

Remover Cliente ​

Respostas ​

Clientes

Endpoints do Comprador

Registrar Conta `[public]`

Payload (Body)

Exemplo de Requisição

Respostas

Login `[public]`

Payload (Body)

Exemplo de Requisição

Respostas

Esqueci a Senha `[public]`

Payload (Body)

Respostas

Redefinir Senha `[public]`

Payload (Body)

Exemplo de Requisição

Respostas

Obter Conta

Exemplo de Requisição

Respostas

Atualizar Conta

Payload (Body)

Respostas

Alterar Senha

Payload (Body)

Respostas

Excluir Conta

Respostas

Logout

Respostas

Endpoints Administrativos

Listar Clientes

Parâmetros de Query

Exemplo de Requisição

Respostas

Listar Clientes (Select)

Parâmetros de Query

Respostas

Criar Cliente

Payload (Body)

Exemplo de Requisição

Respostas

Obter Cliente

Parâmetros de Rota

Respostas

Atualizar Cliente

Payload (Body)

Exemplo de Requisição

Respostas

Alterar Senha do Cliente

Payload (Body)

Respostas

Remover Cliente

Respostas