🕘 Histórico do Cliente
📋 Visão Geral
O módulo de Histórico do Cliente permite que o cliente autenticado consulte o registro de atividades associadas à sua conta.
O histórico reúne eventos gerados automaticamente pela plataforma ao longo das interações do cliente, como autenticações, alterações cadastrais, movimentações de pontos e ações relacionadas a pedidos.
Cada registro descreve o que aconteceu, quando aconteceu e qual foi o estado dos dados antes e depois da ação. As informações são apresentadas em ordem cronológica paginada, permitindo ao cliente acompanhar sua própria trajetória de uso da loja.
🔄 Entidades Envolvidas
O módulo opera sobre uma única entidade principal:
Registro de Histórico (CustomerHistory)
Representa um evento unitário ocorrido na conta do cliente. Cada registro descreve:
- Origem e tipo de ação — identifica qual módulo e qual operação gerou o evento
before— estado dos dados antes da ação ser executadaafter— estado dos dados depois da ação ser executada- Referência a pedido — vínculo opcional com um pedido específico, quando o evento estiver associado a uma transação comercial
- Timestamp — data e hora exatas em que o evento ocorreu
O cliente é identificado automaticamente pelo token de autenticação — o histórico retornado é exclusivamente o da conta autenticada.
🕘 Listagem do Histórico do Cliente
/customer/history
Endpoint responsável por listar o histórico de atividades do cliente autenticado
📋 Descrição
Endpoint responsável por retornar uma lista paginada dos registros de histórico da conta do cliente autenticado.
Cada registro representa um evento registrado pela plataforma — como um login, uma alteração de endereço, um crédito de pontos ou uma ação vinculada a um pedido.
Os campos before e after descrevem o estado dos dados antes e após a ação, quando aplicável.
O cliente tem acesso apenas ao seu próprio histórico, identificado automaticamente pelo token de autenticação. Não é necessário informar o ID do cliente na URL.
A listagem suporta paginação, filtragem e ordenação por meio dos parâmetros de query descritos abaixo.
🔐 Permissão
CustomerAuth— autenticação do cliente via token JWT
📝 Parâmetros
🏷️ Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Authorization | Bearer {token} | Token de autenticação do cliente |
📄 Parâmetros de Paginação
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
limit | integer | 10 | Quantidade de registros por página (máximo: 100) |
offset | integer | 0 | Deslocamento inicial da listagem |
📊 Campos de Condição Disponíveis
| Campo | Tipo | Descrição |
|---|---|---|
orderId | integer | Filtrar pelos registros vinculados a um pedido específico |
origin | string | Filtrar pela origem do evento (ex: authentication, address, point-system) |
action | string | Filtrar pelo tipo de ação registrada (ex: login, create-address) |
createdAt | string | Filtrar pela data de criação do registro |
📊 Campos de Ordenação Disponíveis
| Campo | Descrição |
|---|---|
id | Ordenar pelo identificador do registro |
createdAt | Ordenar pela data de criação do registro |
💡 Exemplo de Requisição
1curl --request GET \2 --url '{{MAIN_URL}}/customer/history?limit=10&offset=0' \3 --header 'Authorization: Bearer SEU_TOKEN_AQUI'💡 Exemplo com Filtros e Ordenação
1curl --request GET \2 --url '{{MAIN_URL}}/customer/history?limit=10&offset=0&condition[conditions][0][field]=origin&condition[conditions][0][value]=authentication&condition[conditions][0][operator]==&order[0][field]=createdAt&order[0][order]=desc' \3 --header 'Authorization: Bearer SEU_TOKEN_AQUI'✅ Resposta de Sucesso
HTTP Status: 200 OK
1{2 "status": true,3 "data": {4 "registers": [5 {6 "id": 1015,7 "userId": null,8 "userName": null,9 "userEmail": null,10 "origin": "authentication",11 "action": "login",12 "createdAt": "2026-04-01 17:37:29",13 "before": [],14 "after": {15 "loginMethod": "email",16 "result": "success",17 "reason": "authenticated"18 },19 "orderId": null20 },21 {22 "id": 1014,23 "userId": null,24 "userName": null,25 "userEmail": null,26 "origin": "point-system",27 "action": "order-point-available",28 "createdAt": "2026-04-01 17:28:39",29 "before": [],30 "after": {31 "id": 71,32 "currentAmount": 1073.499,33 "available": true,34 "expired": false,35 "expiresAt": ""36 },37 "orderId": 46238 }39 ],40 "pagination": {41 "limit": 10,42 "offset": 0,43 "pages": 1,44 "registers": 245 }46 }47}📋 Campos da Resposta
| Campo | Tipo | Descrição | |
|---|---|---|---|
id | integer | Identificador único do registro de histórico | |
userId | integer\ | null | ID do usuário administrativo que originou a ação, quando aplicável |
userName | string\ | null | Nome do usuário administrativo que originou a ação, quando aplicável |
userEmail | string\ | null | E-mail do usuário administrativo que originou a ação, quando aplicável |
origin | string | Módulo ou contexto que gerou o evento (ex: authentication, address, point-system) | |
action | string | Tipo de ação registrada (ex: login, create-address, order-point-available) | |
createdAt | string | Data e hora de criação do registro no formato YYYY-MM-DD HH:MM:SS | |
before | array\ | null | Estado dos dados antes da ação — pode ser array vazio quando não houver estado anterior |
after | array\ | null | Estado dos dados após a ação — estrutura varia conforme o tipo de evento |
orderId | integer\ | null | ID do pedido relacionado ao evento, quando aplicável |
⚠️ Possíveis Erros
> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.
| Código do Erro | HTTP | Descrição |
|---|---|---|
UAPPI_STORE_CUSTOMER_NOT_FOUND | 404 | Cliente não encontrado |