Listagem de Grupos de Pedido

GET /orders/groups

Retorna a listagem avançada de grupos de pedido com filtros e relações expansíveis.

📋 Descrição

Este endpoint é a visão consolidada de vendas por grupo de pedido — a unidade que agrupa todos os pedidos gerados a partir de um mesmo carrinho, incluindo pedidos de múltiplos vendedores ou armazéns.

Enquanto o endpoint /orders retorna pedidos individuais, este retorna um registro por compra, tornando-o ideal para painéis de gestão de vendas, integrações com ERPs e relatórios financeiros que precisam do valor total da transação do cliente.

O acesso exige o escopo de permissão ORDER_READ.

Através do parâmetro fields, é possível expandir a resposta para incluir dados do cliente, endereços, pagamentos, pedidos filhos, itens e muito mais — tudo em uma única consulta.

Quando customer e addresses são solicitados, os dados sensíveis são mascarados de acordo com o nível de permissão do usuário autenticado. O campo masked: true indica quando a máscara está ativa.

🔧 Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

📦 Campos Disponíveis (`fields`)

Campo	Descrição
`customer`	Dados completos do comprador (nome, e-mail, documento, telefone).
`addresses`	Endereços de entrega e cobrança vinculados ao grupo.
`values`	Composição financeira consolidada do grupo (subtotal, frete, descontos, total).
`orders`	Lista dos pedidos filhos do grupo, cada um com seus dados individuais.
`productStorage`	Armazém de origem de cada pedido filho.
`status`	Status atual de cada pedido filho.
`items`	Itens de cada pedido filho com produto, quantidade e valores.
`shipping`	Dados logísticos e de rastreio de cada pedido filho.
`invoice`	Nota fiscal emitida para cada pedido filho.
`reserves`	Reservas de estoque vinculadas aos pedidos filhos.
`payments`	Transações financeiras vinculadas ao grupo.
`paymentLogs`	Histórico de comunicações com o gateway de pagamento.
`observations`	Observações internas registradas no grupo de pedido.
`discounts`	Descontos aplicados no nível do grupo.
`additions`	Acréscimos aplicados no nível do grupo.
`devices`	Dados de dispositivo coletados no momento da compra (IP, user-agent, cookies estratégicos e fingerprint do antifraude).
`paymentCode`	Links de pagamento gerados para o grupo de pedido (código, formas de pagamento permitidas e expiração).

🔍 Campos de Condição Disponíveis (`conditions`)

🗂️ Dados do Grupo

Campo	Tipo	Descrição
`id`	integer	ID do grupo de pedido.
`code`	string	Código de referência do grupo.
`cartId`	string	ID do carrinho de origem.
`createdAt`	date	Data de criação do grupo.
`issuedAt`	date	Data de emissão do grupo.
`tradePolicyId`	integer	ID da política comercial.
`salesChannelId`	integer	ID do canal de venda.
`salesChannelDomain`	string	Domínio do canal de venda.
`userId`	integer	ID do usuário que gerou o pedido (venda interna).
`marketplaceStoreCredentialId`	integer	ID da credencial de marketplace.
`marketplaceOrderGroupId`	string	ID do grupo no marketplace externo.

👤 Dados do Cliente

Campo	Tipo	Descrição
`customerId`	integer	Identificador do cliente.
`customerNameCorporateName`	string	Nome ou Razão Social do comprador.
`customerTradeName`	string	Nome fantasia do comprador.
`customerEmail`	string	E-mail do comprador.
`customerDocument`	string	CPF ou CNPJ do comprador.
`customerDocument2`	string	RG ou Inscrição Estadual do comprador.

💳 Dados de Pagamento

Campo	Tipo	Descrição
`orderPaymentId`	integer	ID de um pagamento vinculado.
`paymentOptionId`	integer	ID da opção de pagamento utilizada.
`paymentStatus`	string	Status financeiro da transação (ex: `captured`, `pending`).
`transactionId`	string	ID da transação no gateway de pagamento.

📍 Endereço e Logística

Campo	Tipo	Descrição
`addressId`	integer	ID de um endereço vinculado ao grupo.
`zipCode`	string	CEP de entrega.
`state`	string	UF de entrega.
`city`	string	Cidade de entrega.
`country`	string	País de entrega.
`shippingTableId`	integer	ID da tabela de frete utilizada.
`externalOrderId`	string	ID da remessa na integração de frete (ex.: `468-592`).

🛒 Itens e Estoque

Campo	Tipo	Descrição
`orderItemId`	integer	ID de um item no pedido.
`orderItemProductId`	integer	ID de um produto no pedido.
`orderItemProductName`	string	Nome de um produto no pedido.
`orderItemProductSku`	string	SKU de um item no pedido.
`priceRuleId`	integer	ID da regra de preço aplicada.
`orderItemProductAmount`	number	Quantidade de um produto específico no pedido.
`orderItemAmount`	number	Quantidade total de itens no pedido.
`productStorageId`	integer	ID do armazém de origem.

💰 Status e Valores

Campo	Tipo	Descrição
`orderStatusId`	integer	ID do status de um pedido filho.
`subtotalValue`	number	Valor subtotal do grupo.
`shippingValue`	number	Valor do frete do grupo.
`totalValue`	number	Valor total do grupo.
`couponHash`	string	Código do cupom aplicado.
`customerAdditionalField`	object	Filtro por campos adicionais do cliente.

↕️ Campos de Ordenação Disponíveis (`order`)

Campo	Descrição
`id`	ID do grupo de pedido
`createdAt`	Data de criação do grupo
`issuedAt`	Data de emissão do grupo

🚀 Exemplo de Requisição

1curl --request GET \
2  --url https://sua-loja-uappi.com.br/api/v3/orders/groups \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": ["customer", "addresses", "values", "orders", "payments"],
6    "conditions": [
7      {
8        "field": "createdAt",
9        "operator": ">=",
10        "value": "2026-01-01"
11      }
12    ],
13    "order": [
14      {
15        "field": "createdAt",
16        "direction": "DESC"
17      }
18    ],
19    "limit": 10,
20    "offset": 0
21  }'
curl --request GET \
  --url https://sua-loja-uappi.com.br/api/v3/orders/groups \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": ["customer", "addresses", "values", "orders", "payments"],
    "conditions": [
      {
        "field": "createdAt",
        "operator": ">=",
        "value": "2026-01-01"
      }
    ],
    "order": [
      {
        "field": "createdAt",
        "direction": "DESC"
      }
    ],
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 456,
5      "cartId": "ac66ca1d61577b216979169",
6      "tradePolicyId": 1,
7      "salesChannelId": 1,
8      "userId": null,
9      "userEmail": null,
10      "userName": null,
11      "code": "UAPPI-456",
12      "salesChannelDomain": "sua-loja.com.br",
13      "marketplaceId": null,
14      "marketplaceName": null,
15      "marketplaceStoreCredentialId": null,
16      "marketplaceOrderGroupId": null,
17      "currency": "BRL",
18      "createdAt": "2026-04-27 10:00:00",
19      "issuedAt": "2026-04-27 10:05:00",
20      "masked": false,
21      "customer": {
22        "orderGroupId": 456,
23        "customerId": 789,
24        "customerNameCorporateName": "João Silva",
25        "customerTradeName": "João Silva",
26        "customerEmail": "joao.silva@email.com.br",
27        "customerDocument": "123.456.789-00",
28        "customerDocument2": "RG 12.345.678-9",
29        "customerPhone": "(11) 98765-4321",
30        "customerIsCorporate": false,
31        "customerGender": "M",
32        "customerBirthdate": "1990-01-01"
33      },
34      "addresses": [
35        {
36          "orderGroupId": 456,
37          "customerAddressType": "shipping",
38          "customerAddressId": 123,
39          "addressZipCode": "01001-000",
40          "addressRecipient": "João Silva",
41          "addressStreet": "Praça da Sé",
42          "addressNumber": "100",
43          "addressDistrict": "Sé",
44          "addressCity": "São Paulo",
45          "addressState": "São Paulo",
46          "addressStateCode": "SP",
47          "addressCountryCode": "BRA",
48          "addressComplement": "Apto 1"
49        },
50        {
51          "orderGroupId": 456,
52          "customerAddressType": "billing",
53          "customerAddressId": 124,
54          "addressZipCode": "01001-000",
55          "addressRecipient": "João Silva",
56          "addressStreet": "Praça da Sé",
57          "addressNumber": "100",
58          "addressDistrict": "Sé",
59          "addressCity": "São Paulo",
60          "addressState": "São Paulo",
61          "addressStateCode": "SP",
62          "addressCountryCode": "BRA",
63          "addressComplement": "Apto 1"
64        }
65      ],
66      "values": {
67        "orderGroupId": 456,
68        "subtotalValue": 140.00,
69        "additionValue": 0.00,
70        "shippingValue": 10.00,
71        "discountValue": 0.00,
72        "totalValue": 150.00
73      },
74      "discounts": [
75        {
76          "id": 1,
77          "orderGroupId": 456,
78          "orderId": null,
79          "type": "coupon",
80          "entityId": "CUPOM10",
81          "value": 10.00
82        }
83      ],
84      "additions": [
85        {
86          "id": 2,
87          "orderGroupId": 456,
88          "orderId": null,
89          "type": "tax",
90          "entityId": "ICMS_ST",
91          "value": 5.00
92        }
93      ],
94      "payments": [
95        {
96          "id": 1,
97          "orderGroupId": 456,
98          "orderId": 123,
99          "customerCardId": null,
100          "paymentType": "credit-card",
101          "paymentProof": null,
102          "paymentExpirationDate": null,
103          "paymentOptionId": 1,
104          "parentPaymentOptionId": null,
105          "paymentOptionLabel": "Cartão de Crédito",
106          "paymentOptionDetail": "Cartão de Crédito 1x",
107          "integrationName": "Pagar.me",
108          "transactionId": "trans_abc123",
109          "currentStatus": "captured",
110          "paymentAntiFraudId": null,
111          "paymentAntiFraudCredentialId": null,
112          "antiFraudStatus": null,
113          "pixQrCode": null,
114          "pixEmv": null,
115          "billetBarCode": null,
116          "billetDigitableLine": null,
117          "billetUrl": null,
118          "cardAutomaticCapture": true,
119          "cardMasked": "4111<strong></strong><strong></strong>1111",
120          "cardFlag": "visa",
121          "cardExpiration": "12/2028",
122          "internalDepositBank": {
123            "name": "Razão Social da Empresa LTDA",
124            "bankName": "Itaú Unibanco",
125            "bank": "341",
126            "agency": "0001",
127            "account": "12345-6",
128            "operation": "",
129            "document": "00.000.000/0001-00"
130          },
131          "value": 150.00,
132          "installment": 1,
133          "installmentValue": 150.00,
134          "fee": 0.00,
135          "orderGroup": {
136            "id": 456,
137            "code": "UAPPI-456",
138            "subtotalValue": 140.00,
139            "additionValue": 0.00,
140            "shippingValue": 10.00,
141            "discountValue": 0.00,
142            "totalValue": 150.00
143          },
144          "logs": []
145        }
146      ],
147      "observations": [
148        {
149          "id": 1,
150          "orderGroupId": 456,
151          "userId": 10,
152          "userName": "Atendente",
153          "userEmail": "atendente@loja.com.br",
154          "observation": "Cliente solicitou embalagem para presente.",
155          "createdAt": "2026-04-27 11:00:00"
156        }
157      ],
158      "orders": [
159        {
160          "id": 123,
161          "orderGroupId": 456,
162          "productStorageId": 1,
163          "orderStatusId": 2,
164          "marketplaceOrderId": null,
165          "masked": false,
166          "productStorage": {
167            "id": 1,
168            "code": "CD-SP-01",
169            "corporateName": "Armazém Central LTDA",
170            "email": "contato@armazem.com.br",
171            "phone": "+5511999999999",
172            "tradeName": "Armazém Central",
173            "stateCode": "SP",
174            "countryCode": "BRA",
175            "document": "12345678000190",
176            "zipCode": "01001000",
177            "city": "São Paulo",
178            "address": "Avenida Paulista",
179            "district": "Bela Vista",
180            "number": "1000",
181            "complement": "Andar 10",
182            "latitude": "-23.561684",
183            "longitude": "-46.655981",
184            "active": true,
185            "observation": null,
186            "tradePolicyExceptions": []
187          },
188          "status": {
189            "id": 2,
190            "orderStatusParentId": 1,
191            "code": "paid",
192            "name": "Pago",
193            "icon": "check-circle",
194            "children": []
195          },
196          "values": {
197            "orderId": 123,
198            "subtotalValue": 140.00,
199            "additionValue": 0.00,
200            "shippingValue": 10.00,
201            "discountValue": 0.00,
202            "totalValue": 150.00
203          },
204          "shipping": {
205            "orderId": 123,
206            "externalOrderId": "1000456-123",
207            "shippingTableId": 5,
208            "label": "Entrega Expressa",
209            "shippingCarrierId": 5,
210            "shippingCarrier": "Transportadora Rápida",
211            "beginShippingTime": 2,
212            "endShippingTime": 5,
213            "shippingIntegrationCode": "EXPR",
214            "initialDeliveryForecast": "2026-04-30",
215            "finalDeliveryForecast": "2026-05-02",
216            "shippingValue": 10.00,
217            "trackingCode": "TRK123456789BR",
218            "reverseLogisticsCode": null,
219            "trackingUrl": "https://rastreamento.transportadora.com.br/TRK123456789BR",
220            "schedule": false,
221            "scheduleDay": null,
222            "scheduleHour": null,
223            "pickUpDetails": null
224          },
225          "invoice": {
226            "orderId": 123,
227            "number": "000123456",
228            "key": "35210112345678000190550010001234561234567890",
229            "serie": "1",
230            "url": "https://cdn.uappi.com.br/invoices/123.pdf",
231            "xml": null
232          },
233          "reserves": [
234            {
235              "id": 1,
236              "customerId": 789,
237              "customerName": "João Silva",
238              "orderId": 123,
239              "type": "order",
240              "status": "active",
241              "reason": "Pedido Realizado",
242              "items": [
243                {
244                  "productId": 50,
245                  "productStorageId": 1,
246                  "amount": 2
247                }
248              ],
249              "userId": null,
250              "userName": null,
251              "userEmail": null,
252              "createdAt": "2026-04-27 10:00:00",
253              "completedAt": null,
254              "canceledAt": null
255            }
256          ],
257          "items": [
258            {
259              "id": 1,
260              "orderId": 123,
261              "productId": 50,
262              "name": "Camiseta Algodão Premium",
263              "description": "Camiseta algodão premium tamanho grande",
264              "sku": "TSHIRT-WHITE-G",
265              "priceRuleId": null,
266              "priceRule": [],
267              "quantity": 2.0,
268              "unitValue": 70.00,
269              "unitAdditionValue": 0.00,
270              "unitDiscountValue": 0.00,
271              "subtotalValue": 140.00,
272              "subtotalAdditionValue": 0.00,
273              "subtotalDiscountValue": 0.00,
274              "totalValue": 140.00,
275              "service": false,
276              "generateGiftCard": false,
277              "discounts": [],
278              "additions": [],
279              "simpleProduct": {
280                "productId": 50,
281                "brandId": 10,
282                "brandName": "Marca X",
283                "mainCategoryId": 5,
284                "mainCategoryName": "Roupas",
285                "type": "simple",
286                "sku": "TSHIRT-WHITE-G",
287                "name": "Camiseta Algodão Premium",
288                "active": true,
289                "url": "https://sua-loja.com.br/camiseta-algodao-premium",
290                "comparisonPrice": 80.00,
291                "stock": 98.0,
292                "medias": [
293                  {
294                    "id": 1,
295                    "type": "image",
296                    "title": "Frente",
297                    "alternativeText": "Camiseta branca de algodão",
298                    "file": "/upload/stores/1/media/img1.jpg",
299                    "originalFile": "/upload/stores/1/media/img1_orig.jpg",
300                    "size": 102400.0,
301                    "originalSize": 512000.0,
302                    "width": 800.0,
303                    "height": 800.0,
304                    "url": "https://cdn.uappi.com.br/upload/stores/1/media/img1.jpg"
305                  }
306                ],
307                "combination": [1],
308                "currentAttributes": [
309                  {
310                    "id": 1,
311                    "name": "Cor",
312                    "value": {
313                      "id": 10,
314                      "label": "Branco",
315                      "image": null,
316                      "originalImage": null,
317                      "color": "#FFFFFF",
318                      "order": 1
319                    }
320                  }
321                ],
322                "restriction": null
323              }
324            }
325          ]
326        }
327      ],
328      "devices": [
329        {
330          "deviceInfoCode": "remote-address",
331          "value": "203.0.113.10"
332        },
333        {
334          "deviceInfoCode": "user-agent",
335          "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
336        },
337        {
338          "deviceInfoCode": "cookies",
339          "value": "{\"_fbc\":\"fb.1.123456789.abcdef\",\"_fbp\":\"fb.1.123456789.ghijkl\",\"utm_source\":\"instagram\"}"
340        },
341        {
342          "deviceInfoCode": "antifraud-fingerprint",
343          "value": "ac66ca1d61577b216979169"
344        }
345      ]
346    }
347  ],
348  "pagination": {
349    "limit": 10,
350    "offset": 0,
351    "pages": 1,
352    "registers": 1
353  }
354}
{
  "registers": [
    {
      "id": 456,
      "cartId": "ac66ca1d61577b216979169",
      "tradePolicyId": 1,
      "salesChannelId": 1,
      "userId": null,
      "userEmail": null,
      "userName": null,
      "code": "UAPPI-456",
      "salesChannelDomain": "sua-loja.com.br",
      "marketplaceId": null,
      "marketplaceName": null,
      "marketplaceStoreCredentialId": null,
      "marketplaceOrderGroupId": null,
      "currency": "BRL",
      "createdAt": "2026-04-27 10:00:00",
      "issuedAt": "2026-04-27 10:05:00",
      "masked": false,
      "customer": {
        "orderGroupId": 456,
        "customerId": 789,
        "customerNameCorporateName": "João Silva",
        "customerTradeName": "João Silva",
        "customerEmail": "joao.silva@email.com.br",
        "customerDocument": "123.456.789-00",
        "customerDocument2": "RG 12.345.678-9",
        "customerPhone": "(11) 98765-4321",
        "customerIsCorporate": false,
        "customerGender": "M",
        "customerBirthdate": "1990-01-01"
      },
      "addresses": [
        {
          "orderGroupId": 456,
          "customerAddressType": "shipping",
          "customerAddressId": 123,
          "addressZipCode": "01001-000",
          "addressRecipient": "João Silva",
          "addressStreet": "Praça da Sé",
          "addressNumber": "100",
          "addressDistrict": "Sé",
          "addressCity": "São Paulo",
          "addressState": "São Paulo",
          "addressStateCode": "SP",
          "addressCountryCode": "BRA",
          "addressComplement": "Apto 1"
        },
        {
          "orderGroupId": 456,
          "customerAddressType": "billing",
          "customerAddressId": 124,
          "addressZipCode": "01001-000",
          "addressRecipient": "João Silva",
          "addressStreet": "Praça da Sé",
          "addressNumber": "100",
          "addressDistrict": "Sé",
          "addressCity": "São Paulo",
          "addressState": "São Paulo",
          "addressStateCode": "SP",
          "addressCountryCode": "BRA",
          "addressComplement": "Apto 1"
        }
      ],
      "values": {
        "orderGroupId": 456,
        "subtotalValue": 140.00,
        "additionValue": 0.00,
        "shippingValue": 10.00,
        "discountValue": 0.00,
        "totalValue": 150.00
      },
      "discounts": [
        {
          "id": 1,
          "orderGroupId": 456,
          "orderId": null,
          "type": "coupon",
          "entityId": "CUPOM10",
          "value": 10.00
        }
      ],
      "additions": [
        {
          "id": 2,
          "orderGroupId": 456,
          "orderId": null,
          "type": "tax",
          "entityId": "ICMS_ST",
          "value": 5.00
        }
      ],
      "payments": [
        {
          "id": 1,
          "orderGroupId": 456,
          "orderId": 123,
          "customerCardId": null,
          "paymentType": "credit-card",
          "paymentProof": null,
          "paymentExpirationDate": null,
          "paymentOptionId": 1,
          "parentPaymentOptionId": null,
          "paymentOptionLabel": "Cartão de Crédito",
          "paymentOptionDetail": "Cartão de Crédito 1x",
          "integrationName": "Pagar.me",
          "transactionId": "trans_abc123",
          "currentStatus": "captured",
          "paymentAntiFraudId": null,
          "paymentAntiFraudCredentialId": null,
          "antiFraudStatus": null,
          "pixQrCode": null,
          "pixEmv": null,
          "billetBarCode": null,
          "billetDigitableLine": null,
          "billetUrl": null,
          "cardAutomaticCapture": true,
          "cardMasked": "4111<strong></strong><strong></strong>1111",
          "cardFlag": "visa",
          "cardExpiration": "12/2028",
          "internalDepositBank": {
            "name": "Razão Social da Empresa LTDA",
            "bankName": "Itaú Unibanco",
            "bank": "341",
            "agency": "0001",
            "account": "12345-6",
            "operation": "",
            "document": "00.000.000/0001-00"
          },
          "value": 150.00,
          "installment": 1,
          "installmentValue": 150.00,
          "fee": 0.00,
          "orderGroup": {
            "id": 456,
            "code": "UAPPI-456",
            "subtotalValue": 140.00,
            "additionValue": 0.00,
            "shippingValue": 10.00,
            "discountValue": 0.00,
            "totalValue": 150.00
          },
          "logs": []
        }
      ],
      "observations": [
        {
          "id": 1,
          "orderGroupId": 456,
          "userId": 10,
          "userName": "Atendente",
          "userEmail": "atendente@loja.com.br",
          "observation": "Cliente solicitou embalagem para presente.",
          "createdAt": "2026-04-27 11:00:00"
        }
      ],
      "orders": [
        {
          "id": 123,
          "orderGroupId": 456,
          "productStorageId": 1,
          "orderStatusId": 2,
          "marketplaceOrderId": null,
          "masked": false,
          "productStorage": {
            "id": 1,
            "code": "CD-SP-01",
            "corporateName": "Armazém Central LTDA",
            "email": "contato@armazem.com.br",
            "phone": "+5511999999999",
            "tradeName": "Armazém Central",
            "stateCode": "SP",
            "countryCode": "BRA",
            "document": "12345678000190",
            "zipCode": "01001000",
            "city": "São Paulo",
            "address": "Avenida Paulista",
            "district": "Bela Vista",
            "number": "1000",
            "complement": "Andar 10",
            "latitude": "-23.561684",
            "longitude": "-46.655981",
            "active": true,
            "observation": null,
            "tradePolicyExceptions": []
          },
          "status": {
            "id": 2,
            "orderStatusParentId": 1,
            "code": "paid",
            "name": "Pago",
            "icon": "check-circle",
            "children": []
          },
          "values": {
            "orderId": 123,
            "subtotalValue": 140.00,
            "additionValue": 0.00,
            "shippingValue": 10.00,
            "discountValue": 0.00,
            "totalValue": 150.00
          },
          "shipping": {
            "orderId": 123,
            "externalOrderId": "1000456-123",
            "shippingTableId": 5,
            "label": "Entrega Expressa",
            "shippingCarrierId": 5,
            "shippingCarrier": "Transportadora Rápida",
            "beginShippingTime": 2,
            "endShippingTime": 5,
            "shippingIntegrationCode": "EXPR",
            "initialDeliveryForecast": "2026-04-30",
            "finalDeliveryForecast": "2026-05-02",
            "shippingValue": 10.00,
            "trackingCode": "TRK123456789BR",
            "reverseLogisticsCode": null,
            "trackingUrl": "https://rastreamento.transportadora.com.br/TRK123456789BR",
            "schedule": false,
            "scheduleDay": null,
            "scheduleHour": null,
            "pickUpDetails": null
          },
          "invoice": {
            "orderId": 123,
            "number": "000123456",
            "key": "35210112345678000190550010001234561234567890",
            "serie": "1",
            "url": "https://cdn.uappi.com.br/invoices/123.pdf",
            "xml": null
          },
          "reserves": [
            {
              "id": 1,
              "customerId": 789,
              "customerName": "João Silva",
              "orderId": 123,
              "type": "order",
              "status": "active",
              "reason": "Pedido Realizado",
              "items": [
                {
                  "productId": 50,
                  "productStorageId": 1,
                  "amount": 2
                }
              ],
              "userId": null,
              "userName": null,
              "userEmail": null,
              "createdAt": "2026-04-27 10:00:00",
              "completedAt": null,
              "canceledAt": null
            }
          ],
          "items": [
            {
              "id": 1,
              "orderId": 123,
              "productId": 50,
              "name": "Camiseta Algodão Premium",
              "description": "Camiseta algodão premium tamanho grande",
              "sku": "TSHIRT-WHITE-G",
              "priceRuleId": null,
              "priceRule": [],
              "quantity": 2.0,
              "unitValue": 70.00,
              "unitAdditionValue": 0.00,
              "unitDiscountValue": 0.00,
              "subtotalValue": 140.00,
              "subtotalAdditionValue": 0.00,
              "subtotalDiscountValue": 0.00,
              "totalValue": 140.00,
              "service": false,
              "generateGiftCard": false,
              "discounts": [],
              "additions": [],
              "simpleProduct": {
                "productId": 50,
                "brandId": 10,
                "brandName": "Marca X",
                "mainCategoryId": 5,
                "mainCategoryName": "Roupas",
                "type": "simple",
                "sku": "TSHIRT-WHITE-G",
                "name": "Camiseta Algodão Premium",
                "active": true,
                "url": "https://sua-loja.com.br/camiseta-algodao-premium",
                "comparisonPrice": 80.00,
                "stock": 98.0,
                "medias": [
                  {
                    "id": 1,
                    "type": "image",
                    "title": "Frente",
                    "alternativeText": "Camiseta branca de algodão",
                    "file": "/upload/stores/1/media/img1.jpg",
                    "originalFile": "/upload/stores/1/media/img1_orig.jpg",
                    "size": 102400.0,
                    "originalSize": 512000.0,
                    "width": 800.0,
                    "height": 800.0,
                    "url": "https://cdn.uappi.com.br/upload/stores/1/media/img1.jpg"
                  }
                ],
                "combination": [1],
                "currentAttributes": [
                  {
                    "id": 1,
                    "name": "Cor",
                    "value": {
                      "id": 10,
                      "label": "Branco",
                      "image": null,
                      "originalImage": null,
                      "color": "#FFFFFF",
                      "order": 1
                    }
                  }
                ],
                "restriction": null
              }
            }
          ]
        }
      ],
      "devices": [
        {
          "deviceInfoCode": "remote-address",
          "value": "203.0.113.10"
        },
        {
          "deviceInfoCode": "user-agent",
          "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
        },
        {
          "deviceInfoCode": "cookies",
          "value": "{\"_fbc\":\"fb.1.123456789.abcdef\",\"_fbp\":\"fb.1.123456789.ghijkl\",\"utm_source\":\"instagram\"}"
        },
        {
          "deviceInfoCode": "antifraud-fingerprint",
          "value": "ac66ca1d61577b216979169"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 1
  }
}

⚠️ 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_ORDER_GROUP_NOT_FOUND`	404	Nenhum grupo de pedido foi localizado com os critérios informados.
`USER_PROFILE_TRADE_POLICY_MISCONFIGURED`	422	O perfil do usuário possui restrição de política comercial ativa, mas nenhuma política comercial permitida está configurada.

Detalhe de Grupo de Pedido

GET /orders/groups/{orderGroupId}

Retorna os dados completos de um grupo de pedido específico

📋 Descrição

Endpoint responsável por retornar o detalhe completo de um grupo de pedido específico, identificado pelo orderGroupId.

O grupo de pedido representa a compra completa — inclui todas as remessas geradas (orders), os pagamentos realizados, os valores consolidados e as observações internas registradas.

> A estrutura de resposta é idêntica à da listagem (GET /orders/groups), com a diferença de que a resposta é o objeto do grupo diretamente, sem registers nem pagination.

O acesso exige o escopo de permissão ORDER_READ.

📌 Campos sempre presentes na resposta

Os mesmos da listagem se aplicam aqui. Consulte a documentação de Listagem de Grupos de Pedido para referência completa dos campos e do parâmetro fields.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

🔗 Parâmetros de URL

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

📥 Body (opcional)

1{
2  "fields": ["customer", "addresses", "values", "orders", "payments"]
3}
{
  "fields": ["customer", "addresses", "values", "orders", "payments"]
}

Os campos disponíveis em fields são os mesmos da listagem. Consulte a documentação de Listagem de Grupos de Pedido.

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/orders/groups/456' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "fields": ["customer", "addresses", "orders"]
7  }'
curl --request GET \
  --url '{{MAIN_URL}}/orders/groups/456' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": ["customer", "addresses", "orders"]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 456,
3  "cartId": "ac66ca1d61577b216979169",
4  "tradePolicyId": 1,
5  "salesChannelId": 1,
6  "userId": null,
7  "userEmail": null,
8  "userName": null,
9  "code": "UAPPI-456",
10  "salesChannelDomain": "sua-loja.com.br",
11  "marketplaceId": null,
12  "marketplaceName": null,
13  "marketplaceStoreCredentialId": null,
14  "marketplaceOrderGroupId": null,
15  "currency": "BRL",
16  "createdAt": "2026-04-27 10:00:00",
17  "issuedAt": "2026-04-27 10:05:00",
18  "masked": false,
19  "payments": [],
20  "customer": {
21    "orderGroupId": 456,
22    "customerId": 789,
23    "customerNameCorporateName": "João Silva",
24    "customerTradeName": "João Silva",
25    "customerEmail": "joao.silva@email.com.br",
26    "customerDocument": "123.456.789-00",
27    "customerDocument2": "RG 12.345.678-9",
28    "customerPhone": "(11) 98765-4321",
29    "customerIsCorporate": false,
30    "customerGender": "M",
31    "customerBirthdate": "1990-01-01"
32  },
33  "addresses": [
34    {
35      "orderGroupId": 456,
36      "customerAddressType": "shipping",
37      "customerAddressId": 123,
38      "addressZipCode": "01001-000",
39      "addressRecipient": "João Silva",
40      "addressStreet": "Praça da Sé",
41      "addressNumber": "100",
42      "addressDistrict": "Sé",
43      "addressCity": "São Paulo",
44      "addressState": "São Paulo",
45      "addressStateCode": "SP",
46      "addressCountryCode": "BRA",
47      "addressComplement": "Apto 1"
48    }
49  ],
50  "values": null,
51  "observations": null,
52  "discounts": null,
53  "additions": null,
54  "orders": [
55    {
56      "id": 123,
57      "orderGroupId": 456,
58      "productStorageId": 1,
59      "orderStatusId": 2,
60      "marketplaceOrderId": null,
61      "masked": false,
62      "customer": null,
63      "addresses": null,
64      "values": null,
65      "shipping": null,
66      "discounts": null,
67      "additions": null,
68      "items": null,
69      "payments": null,
70      "reserves": null,
71      "invoice": null,
72      "histories": null
73    }
74  ],
75  "devices": []
76}
{
  "id": 456,
  "cartId": "ac66ca1d61577b216979169",
  "tradePolicyId": 1,
  "salesChannelId": 1,
  "userId": null,
  "userEmail": null,
  "userName": null,
  "code": "UAPPI-456",
  "salesChannelDomain": "sua-loja.com.br",
  "marketplaceId": null,
  "marketplaceName": null,
  "marketplaceStoreCredentialId": null,
  "marketplaceOrderGroupId": null,
  "currency": "BRL",
  "createdAt": "2026-04-27 10:00:00",
  "issuedAt": "2026-04-27 10:05:00",
  "masked": false,
  "payments": [],
  "customer": {
    "orderGroupId": 456,
    "customerId": 789,
    "customerNameCorporateName": "João Silva",
    "customerTradeName": "João Silva",
    "customerEmail": "joao.silva@email.com.br",
    "customerDocument": "123.456.789-00",
    "customerDocument2": "RG 12.345.678-9",
    "customerPhone": "(11) 98765-4321",
    "customerIsCorporate": false,
    "customerGender": "M",
    "customerBirthdate": "1990-01-01"
  },
  "addresses": [
    {
      "orderGroupId": 456,
      "customerAddressType": "shipping",
      "customerAddressId": 123,
      "addressZipCode": "01001-000",
      "addressRecipient": "João Silva",
      "addressStreet": "Praça da Sé",
      "addressNumber": "100",
      "addressDistrict": "Sé",
      "addressCity": "São Paulo",
      "addressState": "São Paulo",
      "addressStateCode": "SP",
      "addressCountryCode": "BRA",
      "addressComplement": "Apto 1"
    }
  ],
  "values": null,
  "observations": null,
  "discounts": null,
  "additions": null,
  "orders": [
    {
      "id": 123,
      "orderGroupId": 456,
      "productStorageId": 1,
      "orderStatusId": 2,
      "marketplaceOrderId": null,
      "masked": false,
      "customer": null,
      "addresses": null,
      "values": null,
      "shipping": null,
      "discounts": null,
      "additions": null,
      "items": null,
      "payments": null,
      "reserves": null,
      "invoice": null,
      "histories": null
    }
  ],
  "devices": []
}

⚠️ 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_ORDER_GROUP_NOT_FOUND`	404	O grupo de pedido solicitado através do `orderGroupId` não foi encontrado.
`USER_PROFILE_TRADE_POLICY_MISCONFIGURED`	422	O perfil do usuário possui restrição de política comercial ativa, mas nenhuma política comercial permitida está configurada.

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

Listagem de Grupos de Pedido

📋 Descrição

🔧 Parâmetros

Headers Obrigatórios

📦 Campos Disponíveis (fields)

🔍 Campos de Condição Disponíveis (conditions)

🗂️ Dados do Grupo

👤 Dados do Cliente

💳 Dados de Pagamento

📍 Endereço e Logística

🛒 Itens e Estoque

💰 Status e Valores

↕️ Campos de Ordenação Disponíveis (order)

🚀 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Detalhe de Grupo de Pedido

📋 Descrição

📌 Campos sempre presentes na resposta

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

📥 Body (opcional)

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Nesta página

Institucional

📦 Campos Disponíveis (`fields`)

🔍 Campos de Condição Disponíveis (`conditions`)

↕️ Campos de Ordenação Disponíveis (`order`)