🕒 Histórico de Grupo de Pedido

📋 Visão Geral

O módulo de Histórico de Grupo de Pedido registra todas as alterações realizadas em um grupo de pedido ao longo do seu ciclo de vida — desde a criação da remessa até mudanças de status, atualizações de frete, emissão de nota fiscal, troca de armazém, movimentações financeiras e edições manuais de dados cadastrais.

Cada registro captura quem realizou a ação, quando ocorreu e qual foi o estado anterior (before) e o estado posterior (after) da alteração. Isso torna o histórico uma ferramenta essencial para auditoria, diagnóstico e rastreabilidade operacional.

🔄 Entidades Envolvidas

O histórico (OrderHistory) é uma tabela unificada que consolida dois conjuntos de eventos: os eventos de remessa (criação, status, frete, nota fiscal, armazém, alterações financeiras) e os eventos de grupo (atualização de cliente e endereço). A listagem retorna ambos, identificados pelo campo origin.

Cada registro armazena snapshots completos de before e after — a estrutura desses objetos varia conforme a action, podendo conter dados de status, rastreamento, nota fiscal, armazém, movimentações financeiras ou dados cadastrais do cliente e endereço.

Quando userId, userName e userEmail são null, a ação foi realizada pelo próprio sistema — sem intervenção manual, como na criação automática da remessa no checkout.

📌 Notas e Considerações

A listagem suporta filtros por origin, action, userName, userEmail e createdAt, além de ordenação por id e createdAt e paginação.
O campo newOrderStatusId é preenchido apenas para action: change-status; é null nos demais registros.
Os campos orderId e orderGroupId identificam a qual remessa ou grupo o evento pertence — ambos podem coexistir no mesmo registro.

🕒 Histórico de Grupo de Pedido

GET /orders/groups/{orderGroupId}/history

Lista o histórico de alterações de um grupo de pedido

📋 Descrição

Endpoint responsável por listar o histórico completo de alterações de um grupo de pedido, retornando cada evento registrado em ordem cronológica com os dados de quem realizou a ação, qual foi a mudança e quando ocorreu.

Cada registro contém os campos before e after com o snapshot do estado antes e depois da alteração — permitindo reconstruir com precisão toda a linha do tempo do pedido. A estrutura desses campos varia conforme o tipo de ação (action), podendo conter dados de status, rastreamento, nota fiscal, armazém, movimentações financeiras ou dados cadastrais do cliente e endereço.

Ações realizadas pelo próprio sistema (sem intervenção manual) terão userId, userName e userEmail com valor null — como a criação automática da remessa no checkout.

Suporta filtros, ordenação e paginação para facilitar a navegação em pedidos com muitos registros.

🔐 Permissão

UserAuth — autenticação do usuário administrativo
ORDER_READ — escopo de permissão para leitura de pedidos e histórico de alterações

📝 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`orderGroupId`	integer	✅ Sim	ID do grupo de pedido

📦 Parâmetros do Corpo (opcional)

1{
2  "order": [
3    { "field": "id", "order": "asc" }
4  ],
5  "condition": {
6    "type": "AND",
7    "conditions": [
8      { "field": "userName", "operator": "=", "value": "João" }
9    ]
10  },
11  "pagination": {
12    "limit": 10,
13    "offset": 0
14  }
15}
{
  "order": [
    { "field": "id", "order": "asc" }
  ],
  "condition": {
    "type": "AND",
    "conditions": [
      { "field": "userName", "operator": "=", "value": "João" }
    ]
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  }
}

Campos de Condição Disponíveis

Cada item do array conditions aceita os campos field, operator e value.

`field`	Descrição
`origin`	Origem da alteração — ex: `status`, `shipping`, `customer`
`action`	Ação registrada — ex: `change-status`, `update-customer`
`userName`	Nome do usuário que realizou a ação
`userEmail`	E-mail do usuário que realizou a ação
`createdAt`	Data e hora do registro

Campos de Ordenação Disponíveis

Campo	Descrição
`id`	ID do registro de histórico
`createdAt`	Data de criação

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/orders/groups/3710/history' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "order": [{ "field": "id", "order": "asc" }],
7    "condition": {
8      "type": "AND",
9      "conditions": [
10        { "field": "userName", "operator": "=", "value": "João" }
11      ]
12    },
13    "pagination": { "limit": 10, "offset": 0 }
14  }'
curl --request GET \
  --url '{{MAIN_URL}}/orders/groups/3710/history' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "order": [{ "field": "id", "order": "asc" }],
    "condition": {
      "type": "AND",
      "conditions": [
        { "field": "userName", "operator": "=", "value": "João" }
      ]
    },
    "pagination": { "limit": 10, "offset": 0 }
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 7,
7        "userId": null,
8        "userName": null,
9        "userEmail": null,
10        "origin": "order",
11        "action": "create-order",
12        "createdAt": "2025-09-11 20:35:18",
13        "before": [],
14        "after": {
15          "id": 3710,
16          "orderGroupId": 3710,
17          "productStorageId": 1,
18          "orderStatusId": 1
19        },
20        "orderGroupId": 3710,
21        "orderId": 3710,
22        "newOrderStatusId": null
23      },
24      {
25        "id": 27,
26        "userId": 6,
27        "userName": "João",
28        "userEmail": "joao@email.com.br",
29        "origin": "status",
30        "action": "change-status",
31        "createdAt": "2025-10-28 18:11:35",
32        "before": {
33          "orderStatusId": 1
34        },
35        "after": {
36          "orderStatusId": 6,
37          "retroactiveDate": null
38        },
39        "orderGroupId": 3710,
40        "orderId": 3710,
41        "newOrderStatusId": 6
42      }
43    ],
44    "pagination": {
45      "limit": 10,
46      "offset": 0,
47      "pages": 1,
48      "registers": 7
49    }
50  }
51}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 7,
        "userId": null,
        "userName": null,
        "userEmail": null,
        "origin": "order",
        "action": "create-order",
        "createdAt": "2025-09-11 20:35:18",
        "before": [],
        "after": {
          "id": 3710,
          "orderGroupId": 3710,
          "productStorageId": 1,
          "orderStatusId": 1
        },
        "orderGroupId": 3710,
        "orderId": 3710,
        "newOrderStatusId": null
      },
      {
        "id": 27,
        "userId": 6,
        "userName": "João",
        "userEmail": "joao@email.com.br",
        "origin": "status",
        "action": "change-status",
        "createdAt": "2025-10-28 18:11:35",
        "before": {
          "orderStatusId": 1
        },
        "after": {
          "orderStatusId": 6,
          "retroactiveDate": null
        },
        "orderGroupId": 3710,
        "orderId": 3710,
        "newOrderStatusId": 6
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 7
    }
  }
}

Campos da Resposta

Campo	Tipo	Nullable	Descrição
`id`	integer	Não	ID do registro de histórico
`userId`	integer	Sim	ID do usuário responsável — `null` para ações do sistema
`userName`	string	Sim	Nome do usuário que realizou a ação — `null` para ações do sistema
`userEmail`	string	Sim	E-mail do usuário responsável — `null` para ações do sistema
`origin`	string	Não	Origem da alteração — identifica o contexto da mudança
`action`	string	Não	Ação realizada — detalha o que foi feito
`createdAt`	string	Não	Data e hora do registro
`before`	object/array	Sim	Estado anterior à alteração — estrutura varia por `action`
`after`	object/array	Sim	Estado posterior à alteração — estrutura varia por `action`
`orderGroupId`	integer	Sim	ID do grupo de pedido vinculado ao registro
`orderId`	integer	Sim	ID da remessa vinculada ao registro
`newOrderStatusId`	integer	Sim	Novo status aplicado — preenchido apenas para `action: change-status`

Referência de `origin` e `action`

Valores de `origin`

Valor	Descrição
`order`	Criação do pedido
`status`	Alteração de status
`shipping`	Atualização de frete ou rastreamento
`invoice`	Atualização de nota fiscal
`storage`	Troca de armazém
`alteration`	Adição ou remoção de desconto/acréscimo
`customer`	Atualização dos dados cadastrais do cliente do grupo
`address`	Atualização dos endereços do grupo

Valores de `action`

Valor	`origin`	Descrição
`create-order`	`order`	Remessa criada
`change-status`	`status`	Status alterado
`update-tracking`	`shipping`	Código de rastreamento atualizado
`update-delivery-forecast`	`shipping`	Previsão de entrega atualizada
`update-invoice`	`invoice`	Nota fiscal atualizada
`change-storage`	`storage`	Armazém trocado
`create-discount`	`alteration`	Desconto adicionado
`create-addition`	`alteration`	Acréscimo adicionado
`remove-discount`	`alteration`	Desconto removido
`remove-addition`	`alteration`	Acréscimo removido
`update-customer`	`customer`	Dados cadastrais do cliente atualizados
`update-address`	`address`	Endereços do grupo atualizados

Estrutura de `before` e `after` por ação

Os campos before e after carregam o snapshot do dado antes e depois da alteração. A estrutura varia conforme a action:

`create-order`

1"before": [],
2"after": { "id": 101, "orderGroupId": 55, "productStorageId": 1, "orderStatusId": 1 }
"before": [],
"after": { "id": 101, "orderGroupId": 55, "productStorageId": 1, "orderStatusId": 1 }

> userId, userName e userEmail serão null — a criação é feita pelo sistema no checkout.

`change-status`

1"before": { "orderStatusId": 1 },
2"after":  { "orderStatusId": 2, "retroactiveDate": null }
"before": { "orderStatusId": 1 },
"after":  { "orderStatusId": 2, "retroactiveDate": null }

> retroactiveDate: data retroativa aplicada à mudança de status, quando informada. newOrderStatusId também é preenchido no registro raiz.

`update-tracking` / `update-delivery-forecast`

1"before": { "orderId": 101, "trackingCode": null },
2"after":  { "orderId": 101, "trackingCode": "BR123456789BR" }
"before": { "orderId": 101, "trackingCode": null },
"after":  { "orderId": 101, "trackingCode": "BR123456789BR" }

`update-invoice`

1"before": [],
2"after":  { "orderId": 101, "number": "000123", "key": "35260412...", "serie": "1", "url": "https://..." }
"before": [],
"after":  { "orderId": 101, "number": "000123", "key": "35260412...", "serie": "1", "url": "https://..." }

`change-storage`

1"before": { "id": 101, "productStorageId": 1 },
2"after":  { "id": 101, "productStorageId": 2 }
"before": { "id": 101, "productStorageId": 1 },
"after":  { "id": 101, "productStorageId": 2 }

`create-discount` / `create-addition`

1"before": null,
2"after":  { "id": 10, "orderId": 101, "type": "discount", "entityId": "coupon-123", "value": 15.00 }
"before": null,
"after":  { "id": 10, "orderId": 101, "type": "discount", "entityId": "coupon-123", "value": 15.00 }

`remove-discount` / `remove-addition`

1"before": { "id": 10, "orderId": 101, "type": "discount", "entityId": "coupon-123", "value": 15.00 },
2"after":  null
"before": { "id": 10, "orderId": 101, "type": "discount", "entityId": "coupon-123", "value": 15.00 },
"after":  null

`update-customer`

1"before": { "customerId": 3533, "customerNameCorporateName": "Nome Antigo", "customerEmail": "antigo@email.com", "customerPhone": "+5511888888888", "customerDocument": "000.000.000-00", "customerDocument2": "", "customerIsCorporate": false, "customerGender": "undefined", "customerBirthdate": "2000-01-01" },
2"after":  { "customerId": 3533, "customerNameCorporateName": "Nome Novo", "customerEmail": "novo@email.com", "customerPhone": "+5511999999999", "customerDocument": "000.000.000-00", "customerDocument2": "", "customerIsCorporate": false, "customerGender": "male", "customerBirthdate": "1990-05-20" }
"before": { "customerId": 3533, "customerNameCorporateName": "Nome Antigo", "customerEmail": "antigo@email.com", "customerPhone": "+5511888888888", "customerDocument": "000.000.000-00", "customerDocument2": "", "customerIsCorporate": false, "customerGender": "undefined", "customerBirthdate": "2000-01-01" },
"after":  { "customerId": 3533, "customerNameCorporateName": "Nome Novo", "customerEmail": "novo@email.com", "customerPhone": "+5511999999999", "customerDocument": "000.000.000-00", "customerDocument2": "", "customerIsCorporate": false, "customerGender": "male", "customerBirthdate": "1990-05-20" }

`update-address`

1"before": { "customerAddressType": "both", "addressZipCode": "01310100", "addressRecipient": "Nome Antigo", "addressStreet": "Rua Antiga", "addressNumber": "1", "addressDistrict": "Bairro", "addressCity": "São Paulo", "addressState": "São Paulo", "addressStateCode": "BR-SP", "addressCountryCode": "BRA", "addressComplement": "" },
2"after":  { "customerAddressType": "both", "addressZipCode": "04922150", "addressRecipient": "Nome Novo", "addressStreet": "Rua Nova", "addressNumber": "42", "addressDistrict": "Centro", "addressCity": "São Paulo", "addressState": "São Paulo", "addressStateCode": "BR-SP", "addressCountryCode": "BRA", "addressComplement": "" }
"before": { "customerAddressType": "both", "addressZipCode": "01310100", "addressRecipient": "Nome Antigo", "addressStreet": "Rua Antiga", "addressNumber": "1", "addressDistrict": "Bairro", "addressCity": "São Paulo", "addressState": "São Paulo", "addressStateCode": "BR-SP", "addressCountryCode": "BRA", "addressComplement": "" },
"after":  { "customerAddressType": "both", "addressZipCode": "04922150", "addressRecipient": "Nome Novo", "addressStreet": "Rua Nova", "addressNumber": "42", "addressDistrict": "Centro", "addressCity": "São Paulo", "addressState": "São Paulo", "addressStateCode": "BR-SP", "addressCountryCode": "BRA", "addressComplement": "" }

⚠️ 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_ORDER_GROUP_NOT_FOUND`	404	Grupo de pedido não encontrado com o ID informado

🕒 Detalhe de Histórico de Grupo de Pedido

GET /orders/groups/{orderGroupId}/history/{historyId}

Retorna o detalhe completo de um registro de histórico de um grupo de pedido

📋 Descrição

Endpoint responsável por retornar o detalhe completo de um registro de histórico de um grupo de pedido, incluindo os snapshots de before e after com todos os dados da alteração — útil para diagnóstico aprofundado de um evento específico dentro da linha do tempo do pedido.

Ideal para auditoria pontual, quando já se conhece o ID do registro via listagem e é necessário inspecionar o contexto completo da mudança.

Quando userId, userName e userEmail são null, a ação foi realizada pelo próprio sistema — como na criação automática da remessa no checkout.

🔐 Permissão

UserAuth — autenticação do usuário administrativo
ORDER_READ — escopo de permissão para leitura de pedidos e histórico de alterações

📝 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`orderGroupId`	integer	✅ Sim	ID do grupo de pedido
`historyId`	integer	✅ Sim	ID do registro de histórico

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 7,
5    "userId": null,
6    "userName": null,
7    "userEmail": null,
8    "origin": "order",
9    "action": "create-order",
10    "createdAt": "2025-09-11 20:35:18",
11    "before": [],
12    "after": {
13      "id": 3710,
14      "orderGroupId": 3710,
15      "productStorageId": 1,
16      "orderStatusId": 1
17    },
18    "orderGroupId": 3710,
19    "orderId": 3710,
20    "newOrderStatusId": null
21  }
22}
{
  "status": true,
  "data": {
    "id": 7,
    "userId": null,
    "userName": null,
    "userEmail": null,
    "origin": "order",
    "action": "create-order",
    "createdAt": "2025-09-11 20:35:18",
    "before": [],
    "after": {
      "id": 3710,
      "orderGroupId": 3710,
      "productStorageId": 1,
      "orderStatusId": 1
    },
    "orderGroupId": 3710,
    "orderId": 3710,
    "newOrderStatusId": null
  }
}

⚠️ 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_ORDER_GROUP_NOT_FOUND`	404	Grupo de pedido não encontrado com o ID informado
`UAPPI_STORE_ORDER_GROUP_HISTORY_NOT_FOUND`	404	Registro de histórico não encontrado com o ID informado

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 Grupo de Pedido

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

🕒 Histórico de Grupo de Pedido

📋 Descrição

🔐 Permissão

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

📦 Parâmetros do Corpo (opcional)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

Campos da Resposta

Referência de origin e action

Valores de origin

Valores de action

Estrutura de before e after por ação

create-order

change-status

update-tracking / update-delivery-forecast

update-invoice

change-storage

create-discount / create-addition

remove-discount / remove-addition

update-customer

update-address

⚠️ Possíveis Erros

Referência de `origin` e `action`

Valores de `origin`

Valores de `action`

Estrutura de `before` e `after` por ação

`create-order`

`change-status`

`update-tracking` / `update-delivery-forecast`

`update-invoice`

`change-storage`

`create-discount` / `create-addition`

`remove-discount` / `remove-addition`

`update-customer`

`update-address`