VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Registro de atividades

Consultar registros

Lista, filtra e exporta os registros de atividade, e devolve os valores disponíveis para montar os filtros.

O registro de atividades responde "quem fez o quê e quando" na loja: logins, alterações de pedido, edição de produto, mudanças de configuração. Esta página tem as três rotas de leitura: a lista paginada, a exportação em CSV e o dicionário de valores para os filtros. Todas exigem o privilégio view_logs.

Listar registros

GET/api/v1/admin/logsAdmin

Lista paginada dos registros de atividade

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 100. Acima de 100 não limita: volta para 20.
typestring
Família do evento (igualdade exata).
actionstring
Ação (igualdade exata).
user_iduuid
Quem agiu.
entity_typestring
Tipo do registro afetado.
entity_idstring
Id do registro afetado, por exemplo o UUID de um pedido para ver o histórico dele.
event_levelstring
NWE
Gravidade.
date_fromstring
Início, RFC 3339 (2026-10-01T00:00:00Z). Um valor fora desse formato é ignorado sem erro.
date_tostring
Fim, RFC 3339. Mesmo comportamento de date_from.
searchstring
Texto livre, sem diferenciar maiúsculas: procura dentro dos detalhes (content), no tipo e no id do registro.

Exemplo de requisição

Resposta

200Registros

Campos da resposta

logsarray
Os registros da página. null (não []) quando nada casa com os filtros.
total / page / per_page / total_pagesinteger
Paginação: total de registros que casam, página atual, tamanho e total de páginas.
logs[].iduuid
Id do registro.
logs[].user_idstring
Quem agiu (UUID). Vazio para ações do sistema, como rotinas automáticas.
logs[].user_emailstring
E-mail de quem agiu, no momento da ação.
logs[].typestring
Família do evento (auth, orders, products, settings...). Use Valores dos filtros para ver os existentes.
logs[].actionstring
O que foi feito (login, create, delete, bulk_update_status...).
logs[].event_levelstring
NWE
Gravidade: N normal, W aviso, E erro.
logs[].entity_type / entity_idstring
O tipo e o id do registro afetado (por exemplo order e o UUID do pedido).
logs[].contentobject
Detalhes livres da ação. O formato varia por type e action.
logs[].ip_address / user_agentstring
Origem da requisição.
logs[].created_atstring
Quando ocorreu (RFC 3339, UTC).
logs[].payload_before / payload_afterobject
Estado do registro antes e depois da ação, quando a ação registra isso. Ausentes nas demais.
logs[].entity_label / entity_hrefstring
Rótulo legível do registro afetado e o caminho no painel (/admin/orders/...) quando existe. Calculados na leitura.
logs[].summarystring
Frase curta em inglês descrevendo o registro.
logs[].summary_key / summary_paramsstring / object
A mesma frase em forma traduzível (chave de mensagem e variáveis), presente só em alguns tipos de registro.
logs[].actor_user_type / actor_display_namestring
customer, vendor ou admin, e o nome de quem agiu.
logs[].ip_address_label / user_agent_labelstring
Rótulos legíveis (por exemplo System para ações internas).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_logs"]}
500Falha ao consultar.{"error":"failed to list logs","detail":"..."}
`logs` pode ser null

Trate logs ausente ou null como lista vazia.

Histórico de um registro

Para ver tudo o que aconteceu com um pedido, filtre entity_type=order&entity_id=<uuid>.

Exportar em CSV

GET/api/v1/admin/logs/exportAdmin

Exporta registros em CSV

Parâmetros de consulta

typestring
Família do evento (igualdade exata).
actionstring
Ação (igualdade exata).
user_iduuid
Quem agiu.
entity_typestring
Tipo do registro afetado.
entity_idstring
Id do registro afetado, por exemplo o UUID de um pedido para ver o histórico dele.
event_levelstring
NWE
Gravidade.
date_fromstring
Início, RFC 3339 (2026-10-01T00:00:00Z). Um valor fora desse formato é ignorado sem erro.
date_tostring
Fim, RFC 3339. Mesmo comportamento de date_from.
searchstring
Texto livre, sem diferenciar maiúsculas: procura dentro dos detalhes (content), no tipo e no id do registro.

Exemplo de requisição

Resposta

200Arquivo CSV

Campos da resposta

X-Export-Totalheader
Quantos registros casam com o filtro.
X-Export-Returnedheader
Quantos entraram no arquivo (no máximo 10.000, os mais novos).
X-Export-Truncatedheader
true quando X-Export-Total é maior que X-Export-Returned.

O CSV usa vírgula como separador e cabeçalhos fixos em inglês (diferente dos relatórios, que usam ;). Details é o content serializado como JSON. Não inclui payload_before e payload_after.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_logs"]}
500Falha ao consultar.{"error":"failed to export logs","detail":"..."}
Exportação truncada

Acima de 10.000 linhas o arquivo vem cortado e a primeira linha passa a ser um aviso (# AVISO: exportação truncada ...) antes do cabeçalho. Leia X-Export-Truncated e reduza o período com date_from/date_to. O navegador só lê esses cabeçalhos porque a plataforma os expõe em Access-Control-Expose-Headers.

Valores dos filtros

GET/api/v1/admin/logs/filtersAdmin

Valores distintos para montar filtros

Exemplo de requisição

Resposta

200Valores

Campos da resposta

types / actions / entity_types / user_emailsarray
Valores distintos que aparecem nos registros recentes, para preencher listas de seleção.
window_daysinteger
Janela usada: 90. Valores que só existem em registros mais antigos não aparecem.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_logs"]}
500Falha ao consultar.{"error":"failed to get filter values","detail":"..."}

Veja também

  • Configurar o que é registrado
  • Limpar registros antigos
  • Paginação
Anterior
Registro de atividades
Próxima
Configurar o que é registrado
Nesta página
  • Listar registros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar em CSV
  • Exemplo de requisição
  • Resposta
  • Erros
  • Valores dos filtros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/logs?type=auth&event_level=N&per_page=20&date_from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"
text
Date,User Email,User ID,Type,Action,Level,Entity Type,Entity ID,Details,IP Address,User Agent
2026-10-11T21:11:33Z,admin@minhaloja.com.br,d4613dde-ac7a-431c-9232-50d8cd6ad5fc,auth,login,N,user,d4613dde-ac7a-431c-9232-50d8cd6ad5fc,"{""user_type"":""admin""}",203.0.113.10,Mozilla/5.0
bash
curl "$BASE_URL/api/v1/admin/logs/export?type=auth&date_from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN" \
  -o activity_logs.csv
bash
curl "$BASE_URL/api/v1/admin/logs/filters" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "logs": [
    {
      "id": "b4585e4c-141a-426a-a716-b2a40b8df6bc",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "user_email": "admin@minhaloja.com.br",
      "type": "auth",
      "action": "login",
      "event_level": "N",
      "entity_type": "user",
      "entity_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "content": {
        "user_type": "admin"
      },
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "created_at": "2026-10-11T21:03:10.08301Z",
      "entity_label": "Maria Souza (admin)",
      "entity_href": "/admin/users/d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "summary": "Login succeeded: Maria Souza (admin)",
      "actor_user_type": "admin",
      "actor_display_name": "Maria Souza",
      "ip_address_label": "203.0.113.10",
      "user_agent_label": "Mozilla/5.0"
    }
  ],
  "total": 14409,
  "page": 1,
  "per_page": 20,
  "total_pages": 721
}
json
{
  "types": [
    "auth",
    "orders",
    "products",
    "settings"
  ],
  "actions": [
    "create",
    "delete",
    "login",
    "update"
  ],
  "entity_types": [
    "order",
    "product",
    "user"
  ],
  "user_emails": [
    "admin@minhaloja.com.br"
  ],
  "window_days": 90
}