🕘 Histórico de Cliente (Admin)

📋 Visão Geral

O módulo de Histórico de Cliente permite que usuários administrativos consultem o registro de atividades dos clientes cadastrados na loja.

O histórico reúne ações realizadas pelo cliente ou sobre o cliente, como alterações cadastrais, autenticações, movimentações de pontos e interações relacionadas a pedidos. Essas informações oferecem rastreabilidade e apoio ao suporte.

Os registros são apresentados em ordem cronológica paginada, permitindo navegar por toda a trajetória de uso de cada cliente.

🔄 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 executada
after — 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

Listagem de Histórico do Cliente

GET /customers/{customerId}/history

Endpoint responsável por listar o histórico de atividades do cliente

Descrição

Endpoint responsável por retornar uma lista paginada dos registros de histórico de um cliente específico 📄.

Destinado ao painel administrativo, permite a visualização organizada das atividades vinculadas ao cliente, facilitando auditoria e suporte.

A utilização requer autenticação via UserAuth e permissão CUSTOMER_READ, garantindo controle de acesso às informações.

Parâmetros de Query

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação do usuário

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
customerId	integer	Sim	ID do cliente

Campos de Condição Disponíveis

Campo	Tipo	Descrição
orderId	integer	Filtrar pelo ID da remessa associada ao histórico
origin	integer	Filtra pela origem do histórico
action	string	Filtrar por tipo de ação
createdAt	string	Filtra pela data de criação do registro

Campos de Ordenação Disponíveis

Campo	Descrição
id	Ordenar lista por ID
createdAt	Ordenar lista por data de criação

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/123/history?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customers/123/history?limit=10&offset=0' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/123/history?limit=10&offset=0&order[0][field]=createdAt&order[0][direction]=desc' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customers/123/history?limit=10&offset=0&order[0][field]=createdAt&order[0][direction]=desc' \
  --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": null,
20				"orderGroupId": null
21			},
22			{
23				"id": 1014,
24				"userId": null,
25				"userName": null,
26				"userEmail": null,
27				"origin": "point-system",
28				"action": "order-point-available",
29				"createdAt": "2026-04-01 17:28:39",
30				"before": [],
31				"after": {
32					"id": 71,
33					"currentAmount": 1073.499,
34					"available": true,
35					"expired": false,
36					"expiresAt": ""
37				},
38				"orderId": 462,
39				"orderGroupId": 345
40			}
41    ],
42    "pagination": {
43      "limit": 10,
44      "offset": 0,
45      "pages": 1,
46      "registers": 2
47    }
48  }
49}
{
  "status": true,
  "data": {
    "registers": [
      {
				"id": 1015,
				"userId": null,
				"userName": null,
				"userEmail": null,
				"origin": "authentication",
				"action": "login",
				"createdAt": "2026-04-01 17:37:29",
				"before": [],
				"after": {
					"loginMethod": "email",
					"result": "success",
					"reason": "authenticated"
				},
				"orderId": null,
				"orderGroupId": null
			},
			{
				"id": 1014,
				"userId": null,
				"userName": null,
				"userEmail": null,
				"origin": "point-system",
				"action": "order-point-available",
				"createdAt": "2026-04-01 17:28:39",
				"before": [],
				"after": {
					"id": 71,
					"currentAmount": 1073.499,
					"available": true,
					"expired": false,
					"expiresAt": ""
				},
				"orderId": 462,
				"orderGroupId": 345
			}
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 2
    }
  }
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código HTTP	Descrição
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	Cliente não foi encontrado

Listagem de Histórico de Clientes em Massa

GET /customers/history

Endpoint responsável por listar o histórico de atividades de todos os clientes, sem restrição por cliente específico

Descrição

Endpoint responsável por retornar uma lista paginada dos registros de histórico de todos os clientes cadastrados na loja, sem a necessidade de informar um customerId na URL 📄.

Destinado ao painel administrativo, permite auditar e monitorar as atividades de qualquer cliente a partir de uma única listagem. Cada registro traz o campo customerId, indicando a qual cliente aquela alteração pertence.

A utilização requer autenticação via UserAuth e permissão CUSTOMER_READ, garantindo controle de acesso às informações.

Quando o chamador é um usuário humano (PrivateAuth::userIsHuman()), campos sensíveis do histórico (e-mail, telefone, documento, endereço e nome, entre outros) retornam mascarados para conformidade com a LGPD; chamadas de integração (não humanas) recebem os dados sem máscara.

Parâmetros de Query

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação do usuário

Campos de Condição Disponíveis

Campo	Tipo	Descrição
customerId	integer	Filtrar pelo ID do cliente
orderId	integer	Filtrar pelo ID do pedido associado ao histórico
origin	string	Filtra pela origem do histórico
userName	string	Filtrar pelo nome do usuário responsável pela ação
userEmail	string	Filtrar pelo e-mail do usuário responsável pela ação
action	string	Filtrar por tipo de ação
createdAt	string	Filtra pela data de criação do registro

Campos de Ordenação Disponíveis

Campo	Descrição
id	Ordenar lista por ID
createdAt	Ordenar lista por data de criação

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/history?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customers/history?limit=10&offset=0' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/history?limit=10&offset=0&condition[customerId]=123&order[0][field]=createdAt&order[0][direction]=desc' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customers/history?limit=10&offset=0&condition[customerId]=123&order[0][field]=createdAt&order[0][direction]=desc' \
  --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        "customerId": 123,
8        "orderId": null,
9        "orderGroupId": null,
10        "userId": null,
11        "userName": null,
12        "userEmail": null,
13        "origin": "authentication",
14        "action": "login",
15        "before": [],
16        "after": {
17          "loginMethod": "email",
18          "result": "success",
19          "reason": "authenticated"
20        },
21        "createdAt": "2026-04-01 17:37:29"
22      },
23      {
24        "id": 1014,
25        "customerId": 456,
26        "orderId": 462,
27        "orderGroupId": 345,
28        "userId": null,
29        "userName": null,
30        "userEmail": null,
31        "origin": "point-system",
32        "action": "order-point-available",
33        "before": [],
34        "after": {
35          "id": 71,
36          "currentAmount": 1073.499,
37          "available": true,
38          "expired": false,
39          "expiresAt": ""
40        },
41        "createdAt": "2026-04-01 17:28:39"
42      }
43    ],
44    "pagination": {
45      "limit": 10,
46      "offset": 0,
47      "pages": 1,
48      "registers": 2
49    }
50  }
51}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 1015,
        "customerId": 123,
        "orderId": null,
        "orderGroupId": null,
        "userId": null,
        "userName": null,
        "userEmail": null,
        "origin": "authentication",
        "action": "login",
        "before": [],
        "after": {
          "loginMethod": "email",
          "result": "success",
          "reason": "authenticated"
        },
        "createdAt": "2026-04-01 17:37:29"
      },
      {
        "id": 1014,
        "customerId": 456,
        "orderId": 462,
        "orderGroupId": 345,
        "userId": null,
        "userName": null,
        "userEmail": null,
        "origin": "point-system",
        "action": "order-point-available",
        "before": [],
        "after": {
          "id": 71,
          "currentAmount": 1073.499,
          "available": true,
          "expired": false,
          "expiresAt": ""
        },
        "createdAt": "2026-04-01 17:28:39"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 2
    }
  }
}

⚠️ Possíveis erros:

Por se tratar de uma listagem em massa, sem customerId na URL, este endpoint não possui um erro de cliente não encontrado — o único erro específico deste contexto é a validação dos campos de condição/ordenação informados.

Código Interno	Código HTTP	Descrição
UAPPI_CORE_INVALID_SEARCH_FIELD	400	Um dos campos de condição ou ordenação informados na requisição não é válido para esta listagem.

Detalhe do Histórico do Cliente

GET /customers/{customerId}/history/{historyId}

Endpoint responsável por retornar o detalhe de um registro de histórico do cliente

Descrição

Endpoint responsável por retornar os detalhes completos de um registro específico do histórico de um cliente 🕘.

Destinado ao painel administrativo, este endpoint permite a consulta detalhada de eventos vinculados ao cadastro do cliente, auxiliando em análises e suporte.

A utilização requer autenticação de usuário e permissão CUSTOMER_READ, garantindo controle de acesso às informações.

Parâmetros de Query

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação do usuário

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
customerId	integer	Sim	ID do cliente
historyId	integer	Sim	ID do registro de histórico

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/1/history/1' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customers/1/history/1' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": 1,
5		"userId": null,
6		"userName": null,
7		"userEmail": null,
8		"origin": "address",
9		"action": "create-address",
10		"createdAt": "2026-01-01 20:23:29",
11		"before": [],
12		"after": {
13			"id": 2,
14			"zipCode": "1600000",
15			"identification": "Casa",
16			"street": "Rua xxxxxx",
17			"number": "1111",
18			"city": "São Paulo",
19			"complement": "Casa verde",
20			"district": "Centro",
21			"state": "São Paulo",
22			"recipient": "Recebedor",
23			"stateCode": "BR-SP",
24			"countryCode": "BRA",
25			"createdAt": "",
26			"updatedAt": ""
27		},
28		"orderId": null
29	}
30}
{
	"status": true,
	"data": {
		"id": 1,
		"userId": null,
		"userName": null,
		"userEmail": null,
		"origin": "address",
		"action": "create-address",
		"createdAt": "2026-01-01 20:23:29",
		"before": [],
		"after": {
			"id": 2,
			"zipCode": "1600000",
			"identification": "Casa",
			"street": "Rua xxxxxx",
			"number": "1111",
			"city": "São Paulo",
			"complement": "Casa verde",
			"district": "Centro",
			"state": "São Paulo",
			"recipient": "Recebedor",
			"stateCode": "BR-SP",
			"countryCode": "BRA",
			"createdAt": "",
			"updatedAt": ""
		},
		"orderId": null
	}
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código HTTP	Descrição
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	Cliente não foi encontrado
UAPPI_STORE_HISTORY_NOT_FOUND	404	Registro de histórico não foi encontrado

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

🕘 Histórico de Cliente (Admin)

📋 Visão Geral

🔄 Entidades Envolvidas

Listagem de Histórico do Cliente

Descrição

Parâmetros de Query

Headers Obrigatórios

Parâmetros de URL

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

Exemplo com Filtros

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Listagem de Histórico de Clientes em Massa

Descrição

Parâmetros de Query

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

Exemplo com Filtros

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Detalhe do Histórico do Cliente

Descrição

Parâmetros de Query

Headers Obrigatórios

Parâmetros de URL

Exemplo de Requisição