Documentação de Pedidos

Visão Geral

Um pedido (order) representa uma remessa ou unidade operacional da compra — reunindo informações como itens, status de processamento, armazém, rastreio e faturamento.

Pedidos podem estar associados a um grupo de pedido (order group), que representa a compra como um todo e centraliza dados como cliente, endereço e observações. Esse agrupamento permite gerenciar múltiplas remessas dentro de um mesmo contexto de compra.

Este módulo cobre as rotas /orders responsáveis pelo ciclo de vida do pedido, permitindo consultar registros com filtros avançados, acessar o detalhe e acompanhar sua evolução ao longo do processamento.

Também contempla atualizações de dados importantes, como status e armazém (inclusive em lote), além do rastreio de entrega, acesso ao conteúdo da nota fiscal (XML ou URL) no contexto do pedido, consulta de histórico e operações relacionadas ao grupo de pedido, como importação, cliente, endereço e observações.

O acesso aos dados segue o uso de escopos: operações de leitura utilizam ORDER_READ, enquanto alterações que modificam dados do pedido ou do grupo exigem ORDER_WRITE (ou combinações específicas indicadas em cada rota).

Entidades Envolvidas

Grupo de pedido (order group): representa a compra como um todo. É a entidade principal no fluxo — concentra dados como cliente, endereço e observações, além de agrupar um ou mais pedidos relacionados. Operações como alteração de cliente, endereço, observações e importação em massa acontecem nesse nível.

Pedido (order): representa uma remessa (ou unidade operacional) dentro de um grupo de pedido. Cada pedido possui seu próprio orderId e é usado para operações mais específicas do processamento, como status, armazém, rastreio, nota fiscal e histórico.

Histórico: trilha de eventos associada ao pedido ou ao grupo, permitindo acompanhar alterações e evolução ao longo do tempo.

Integrações de NF no pedido: acesso ao XML e à URL da nota fiscal vinculada a um pedido específico (remessa), normalmente utilizado para exibição ou integração com sistemas externos.

Notas e Considerações

A listagem (GET /orders) é o ponto de entrada para painéis e buscas; use fields e filtros conforme a documentação do endpoint para evitar payloads desnecessários.
Alteração de status em massa e alteração de armazém são operações distintas e podem ter throttle dedicado.
Para dados fiscais em lote (atualização fiscal sem foco em um único pedido na URL), veja o módulo Nota Fiscal nesta mesma área de documentação.

Listagem de Pedidos

GET /orders

Retorna a listagem avançada de pedidos com diversos filtros e relações.

Descrição

Este endpoint é o ponto central para a gestão de vendas, permitindo realizar buscas complexas e obter dados detalhados. 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, itens, pagamentos e histórico, otimizando o fluxo de dados em uma única consulta.

Quando o cliente e endereços vêm na resposta, a máscara de dados sensíveis segue a mesma lógica da busca por pedido: mais restritiva para usuário humano sem liberação recente.

O sistema suporta filtros exaustivos por status, datas, produtos, endereços e informações financeiras, servindo como base para painéis de acompanhamento e integração com ferramentas de BI.

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
orderGroup	Dados gerais do agrupador de pedidos.
productStorage	Informações do estoque de origem.
status	Detalhes do status atual do pedido.
customer	Dados completos do comprador.
addresses	Endereços de entrega e faturamento.
values	Composição de valores (subtotal, frete, descontos, total).
shipping	Dados logísticos e de rastreio.
items	Lista detalhada de produtos no pedido.
payments	Transações financeiras vinculadas.
paymentLogs	Histórico de comunicações de pagamento.
reserves	Informações de reservas de estoque.
invoice	Dados das notas fiscais emitidas.
discounts	Detalhamento de descontos.
additions	Detalhamento de acréscimos.
histories	Registro de auditoria do pedido.
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 do pedido (código, formas de pagamento permitidas e expiração).

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

Campo	Tipo	Descrição
id	integer	Identificador único do pedido.
orderStatusId	integer	ID do status atual.
productStorageId	integer	ID do armazém de origem.
customerId	integer	Identificador do cliente.
customerNameCorporateName	string	Nome ou Razão Social do cliente.
customerTradeName	string	Nome fantasia do cliente.
customerEmail	string	E-mail do comprador.
customerDocument	string	CPF ou CNPJ do cliente.
customerDocument2	string	RG ou Inscrição Estadual.
orderGroupId	integer	ID do grupo de pedido.
orderGroupCode	string	Código de referência do grupo.
orderGroupCreatedAt	date	Data de criação do grupo.
orderGroupIssuedAt	date	Data de emissão do grupo.
salesChannelId	integer	ID do canal de venda.
salesChannelDomain	string	Domínio do canal de venda.
tradePolicyId	integer	ID da política comercial.
paymentOptionId	integer	ID da opção de pagamento.
transactionId	string	ID da transação no gateway.
paymentStatus	string	Status financeiro (ex: `paid`, `pending`).
shippingTableId	integer	ID da tabela de frete utilizada.
externalOrderId	string	ID da remessa na integração de frete (ex.: `468-592`).
cartId	integer	ID do carrinho original.
addressId	integer	ID de um endereço vinculado.
zipCode	string	CEP de entrega.
state	string	UF de entrega.
city	string	Cidade de entrega.
country	string	País de entrega.
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.
orderItemAmount	number	Quantidade total de itens.
orderHistoryDate	date	Data de ocorrência no histórico.
orderHistoryStatusId	integer	Status registrado no histórico.
subtotalValue	number	Valor subtotal.
shippingValue	number	Valor do frete.
totalValue	number	Valor total da venda.
couponHash	string	Código do cupom utilizado.
customerAdditionalField	object	Filtro por campos adicionais do cliente.

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

Campo	Descrição
id	ID do pedido
orderStatusId	ID do status
orderGroupCreatedAt	Data de criação do grupo
orderGroupIssuedAt	Data de emissão do grupo

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": ["status", "customer", "values"],
6    "conditions": [
7      {
8        "field": "orderStatusId",
9        "value": 2
10      }
11    ]
12  }'
curl --request GET \
  --url {{MAIN_URL}}/orders \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": ["status", "customer", "values"],
    "conditions": [
      {
        "field": "orderStatusId",
        "value": 2
      }
    ]
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 123,
5      "orderGroupId": 456,
6      "productStorageId": 1,
7      "orderStatusId": 2,
8      "marketplaceOrderId": "MKTP-987654",
9      "masked": false,
10      "orderGroup": {
11        "id": 456,
12        "cartId": "cart_abc123",
13        "tradePolicyId": 1,
14        "userId": null,
15        "userEmail": "vendedor@loja.com.br",
16        "userName": "Vendedor Interno",
17        "code": "UAPPI-123456",
18        "salesChannelDomain": "loja.exemplo.com.br",
19        "marketplaceId": null,
20        "marketplaceName": null,
21        "marketplaceStoreCredentialId": null,
22        "marketplaceOrderGroupId": null,
23        "currency": "BRL",
24        "createdAt": "2026-04-27 10:00:00",
25        "issuedAt": "2026-04-27 10:05:00"
26      },
27      "productStorage": {
28        "id": 1,
29        "code": "abc123",
30        "corporateName": "Armazem Central LTDA",
31        "email": "contato@armazem.com.br",
32        "phone": "+5511999999999",
33        "tradeName": "Armazem Central",
34        "stateCode": "SP",
35        "countryCode": "BRA",
36        "document": "12345678000190",
37        "zipCode": "01001000",
38        "city": "São Paulo",
39        "address": "Avenida Paulista",
40        "district": "Bela Vista",
41        "number": "1000",
42        "complement": "Andar 10",
43        "latitude": "-23.561684",
44        "longitude": "-46.655981",
45        "active": true,
46        "observation": "Carga frágil",
47        "tradePolicyExceptions": [2, 3]
48      },
49      "status": {
50        "id": 2,
51        "orderStatusParentId": 1,
52        "code": "paid",
53        "name": "Pago",
54        "icon": "check-circle",
55        "children": [
56          {
57            "id": 3,
58            "orderStatusParentId": 2,
59            "code": "paid_confirmed",
60            "name": "Pagamento confirmado",
61            "icon": "check-double",
62            "children": []
63          }
64        ]
65      },
66      "customer": {
67        "orderGroupId": 456,
68        "customerId": 789,
69        "customerNameCorporateName": "João Silva",
70        "customerTradeName": "João Silva",
71        "customerEmail": "joao.silva@email.com.br",
72        "customerDocument": "123.456.789-00",
73        "customerDocument2": "RG 12.345.678-9",
74        "customerPhone": "(11) 98765-4321",
75        "customerIsCorporate": false,
76        "customerGender": "M",
77        "customerBirthdate": "1990-01-01"
78      },
79      "addresses": [
80        {
81          "orderGroupId": 456,
82          "customerAddressType": "shipping",
83          "customerAddressId": 123,
84          "addressZipCode": "01001-000",
85          "addressRecipient": "João Silva",
86          "addressStreet": "Praça da Sé",
87          "addressNumber": "100",
88          "addressDistrict": "Sé",
89          "addressCity": "São Paulo",
90          "addressState": "São Paulo",
91          "addressStateCode": "SP",
92          "addressCountryCode": "BRA",
93          "addressComplement": "Apto 1"
94        },
95        {
96          "orderGroupId": 456,
97          "customerAddressType": "billing",
98          "customerAddressId": 124,
99          "addressZipCode": "01001-000",
100          "addressRecipient": "João Silva",
101          "addressStreet": "Praça da Sé",
102          "addressNumber": "100",
103          "addressDistrict": "Sé",
104          "addressCity": "São Paulo",
105          "addressState": "São Paulo",
106          "addressStateCode": "SP",
107          "addressCountryCode": "BRA",
108          "addressComplement": "Apto 1"
109        }
110      ],
111      "values": {
112        "orderId": 123,
113        "subtotalValue": 140.00,
114        "additionValue": 0.00,
115        "shippingValue": 10.00,
116        "discountValue": 0.00,
117        "totalValue": 150.00
118      },
119      "shipping": {
120        "orderId": 123,
121        "externalOrderId": "1000456-123",
122        "shippingTableId": 5,
123        "label": "Entrega Expressa",
124        "shippingCarrierId": 5,
125        "shippingCarrier": "Transportadora Rápida",
126        "beginShippingTime": 2,
127        "endShippingTime": 5,
128        "shippingIntegrationCode": "code",
129        "initialDeliveryForecast": "2026-04-30",
130        "finalDeliveryForecast": "2026-05-02",
131        "shippingValue": 10.00,
132        "trackingCode": "TRK123456789",
133        "reverseLogisticsCode": null,
134        "trackingUrl": "https://carrier.com/track/TRK123456789",
135        "schedule": false,
136        "scheduleDay": null,
137        "scheduleHour": null,
138        "pickUpDetails": {
139          "pointName": "Ponto de retirada Centro",
140          "address": "Rua Exemplo, 100 - São Paulo/SP"
141        }
142      },
143      "discounts": [
144        {
145          "id": 1,
146          "orderId": 123,
147          "type": "coupon",
148          "entityId": "CUPOM10",
149          "value": 10.00
150        }
151      ],
152      "additions": [
153        {
154          "id": 1,
155          "orderId": 123,
156          "type": "tax",
157          "entityId": "ICMS_ST",
158          "value": 5.00
159        }
160      ],
161      "items": [
162        {
163          "id": 1,
164          "orderId": 123,
165          "productId": 50,
166          "name": "Camiseta Algodão Premium",
167          "description": "Camiseta algodão premium tamanho grande",
168          "sku": "TSHIRT-WHITE-G",
169          "priceRule":[ 
170            {
171              "id": 1,
172              "name": "Promoção de Verão",
173              "trigger": "code",
174              "ruleTarget": "product",
175              "origin": "trade_policy",
176              "applyInGroup": false,
177              "updateComparisonPrice": "none",
178              "basePriceField": "price",
179              "code": "VERAO2026",
180              "beginQuantity": null,
181              "endQuantity": null,
182              "value": 10,
183              "valueType": "percentage",
184              "priority": 10,
185              "active": true,
186              "scheduling": null,
187              "tradePolicies": [1],
188              "productIds": [],
189              "productCategoryIds": [],
190              "productBrandIds": [],
191              "lastUpdateUserName": null,
192              "createdAt": "2026-01-01 10:00:00",
193              "updatedAt": "2026-01-15 12:00:00"
194            },
195          ],
196          "priceRuleId": 1,
197          "quantity": 2.0,
198          "unitValue": 70.00,
199          "unitAdditionValue": 0.00,
200          "unitDiscountValue": 7.00,
201          "subtotalValue": 140.00,
202          "subtotalAdditionValue": 0.00,
203          "subtotalDiscountValue": 14.00,
204          "totalValue": 126.00,
205          "service": false,
206          "generateGiftCard": false,
207          "discounts": [
208            {
209              "orderDiscountId": 1,
210              "orderAdditionId": null,
211              "value": 14.00,
212              "detail": {
213                "entity": {
214                  "entity": "price_rule",
215                  "identifier": 1,
216                  "description": "Promoção de Lançamento",
217                  "type": "percentage",
218                  "target": "subtotal",
219                  "error": null
220                },
221                "target": "subtotal",
222                "value": 14.0
223              }
224            }
225          ],
226          "additions": [
227            {
228              "orderDiscountId": null,
229              "orderAdditionId": 1,
230              "value": 2.50,
231              "detail": {
232                "entity": {
233                  "entity": "tax",
234                  "identifier": "ICMS_ST",
235                  "description": "Substituição tributária",
236                  "type": "value",
237                  "target": "subtotal",
238                  "error": null
239                },
240                "value": 2.5
241              }
242            }
243          ],
244          "simpleProduct": {
245            "productId": 50,
246            "brandId": 10,
247            "brandName": "Marca X",
248            "mainCategoryId": 5,
249            "mainCategoryName": "Roupas",
250            "type": "simple",
251            "sku": "TSHIRT-WHITE-G",
252            "name": "Camiseta Algodão Premium",
253            "active": true,
254            "url": "https://loja.com.br/camiseta-algodao-premium",
255            "comparisonPrice": 80.00,
256            "stock": 100.0,
257            "medias": [
258              {
259                "id": 1,
260                "type": "image",
261                "title": "Frente da Camiseta",
262                "alternativeText": "Camiseta branca de algodão",
263                "file": "/upload/stores/1/media/img1.jpg",
264                "originalFile": "/upload/stores/1/media/img1_orig.jpg",
265                "size": 102400.0,
266                "originalSize": 512000.0,
267                "width": 800.0,
268                "height": 800.0,
269                "url": "https://cdn.uappi.com.br/upload/stores/1/media/img1.jpg"
270              }
271            ],
272            "combination": [1],
273            "currentAttributes": [
274              {
275                "id": 1,
276                "name": "Cor",
277                "value": {
278                  "id": 10,
279                  "label": "Branco",
280                  "image": null,
281                  "originalImage": null,
282                  "color": "#FFFFFF",
283                  "order": 1
284                }
285              }
286            ],
287            "restriction": {
288              "tradePolicyId": 1,
289              "requiredAge": 18
290            }
291          }
292        }
293      ],
294      "payments": [
295        {
296          "id": 1,
297          "orderGroupId": 456,
298          "orderId": 123,
299          "customerCardId": 123,
300          "paymentType": "credit-card",
301          "paymentProof": "https://gateway.com/proof/abc",
302          "paymentExpirationDate": "2026-04-27",
303          "paymentOptionId": 1,
304          "parentPaymentOptionId": null,
305          "paymentOptionLabel": "Visa",
306          "paymentOptionDetail": "Visa 1x",
307          "integrationName": "Vindi",
308          "transactionId": "trans_abc123",
309          "currentStatus": "captured",
310          "paymentAntiFraudId": "af_123",
311          "paymentAntiFraudCredentialId": 1,
312          "antiFraudStatus": "approved",
313          "pixQrCode": null,
314          "pixEmv": null,
315          "billetBarCode": null,
316          "billetDigitableLine": null,
317          "billetUrl": null,
318          "cardAutomaticCapture": true,
319          "cardMasked": "4111<strong></strong><strong></strong>1111",
320          "cardFlag": "visa",
321          "cardExpiration": "12/2028",
322          "internalDepositBank": {
323            "name": "Razão Social da Empresa LTDA",
324            "bankName": "Itaú Unibanco",
325            "bank": "341",
326            "agency": "0001",
327            "account": "12345-6",
328            "operation": "",
329            "document": "00.000.000/0001-00"
330          },
331          "value": 150.00,
332          "installment": 1,
333          "installmentValue": 150.00,
334          "fee": 0.00,
335          "orderGroup": {
336            "id": 456,
337            "code": "UAPPI-123456",
338            "subtotalValue": 140.00,
339            "additionValue": 0.00,
340            "shippingValue": 10.00,
341            "discountValue": 0.00,
342            "totalValue": 150.00
343          },
344          "logs": [
345            {
346              "id": 10,
347              "tradePolicyId": 1,
348              "orderPaymentId": 1,
349              "cartId": "cart_abc123",
350              "paymentOptionId": 1,
351              "paymentOptionLabel": "Visa",
352              "paymentOptionDetail": "Visa 1x",
353              "transactionId": "trans_abc123",
354              "userName": "Sistema",
355              "userEmail": "system@uappi.com.br",
356              "oldStatus": "pending",
357              "newStatus": "captured",
358              "origin": "gateway",
359              "request": {},
360              "response": {},
361              "createdAt": "2026-04-27 10:10:00"
362            }
363          ]
364        }
365      ],
366      "reserves": [
367        {
368          "id": 1,
369          "customerId": 789,
370          "customerName": "João Silva",
371          "orderId": 123,
372          "type": "order",
373          "status": "active",
374          "reason": "Pedido Realizado",
375          "reserveCustomer": {
376            "id": 789,
377            "tradePolicyId": 1,
378            "email": "joao.silva@email.com.br",
379            "nameCorporateName": "João Silva",
380            "phone": "(11) 98765-4321",
381            "active": true,
382            "masked": false
383          },
384          "items": [
385            {
386              "productId": 50,
387              "productStorageId": 1,
388              "amount": 2
389            }
390          ],
391          "userId": null,
392          "userName": null,
393          "userEmail": null,
394          "reserveUserId": null,
395          "reserveUserName": null,
396          "reserveUserEmail": null,
397          "cancelUserId": null,
398          "cancelUserName": null,
399          "cancelUserEmail": null,
400          "createdAt": "2026-04-27 10:00:00",
401          "completedAt": null,
402          "canceledAt": null
403        }
404      ],
405      "invoice": {
406        "orderId": 123,
407        "number": "000123456",
408        "key": "35210112345678000190550010001234561234567890",
409        "serie": "1",
410        "url": "https://cdn.uappi.com.br/invoices/123.pdf",
411        "xml": null
412      },
413      "histories": [
414        {
415          "id": 2,
416          "userId": 1,
417          "userName": "Sistema",
418          "userEmail": "system@uappi.com.br",
419          "origin": "webhook",
420          "action": "order_paid",
421          "createdAt": "2026-04-27 10:10:00",
422          "before": {
423            "orderStatusId": 1
424          },
425          "after": {
426            "orderStatusId": 2
427          },
428          "orderGroupId": 456,
429          "orderId": 123,
430          "newOrderStatusId": 2
431        }
432      ],
433      "devices": [
434        {
435          "deviceInfoCode": "remote-address",
436          "value": "203.0.113.10"
437        },
438        {
439          "deviceInfoCode": "user-agent",
440          "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
441        },
442        {
443          "deviceInfoCode": "cookies",
444          "value": "{\"_fbc\":\"fb.1.123456789.abcdef\",\"_fbp\":\"fb.1.123456789.ghijkl\",\"utm_source\":\"instagram\"}"
445        },
446        {
447          "deviceInfoCode": "antifraud-fingerprint",
448          "value": "cart_abc123"
449        }
450      ]
451    }
452  ],
453  "pagination": {
454    "limit": 10,
455    "offset": 0,
456    "pages": 1,
457    "registers": 1
458  }
459}
{
  "registers": [
    {
      "id": 123,
      "orderGroupId": 456,
      "productStorageId": 1,
      "orderStatusId": 2,
      "marketplaceOrderId": "MKTP-987654",
      "masked": false,
      "orderGroup": {
        "id": 456,
        "cartId": "cart_abc123",
        "tradePolicyId": 1,
        "userId": null,
        "userEmail": "vendedor@loja.com.br",
        "userName": "Vendedor Interno",
        "code": "UAPPI-123456",
        "salesChannelDomain": "loja.exemplo.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"
      },
      "productStorage": {
        "id": 1,
        "code": "abc123",
        "corporateName": "Armazem Central LTDA",
        "email": "contato@armazem.com.br",
        "phone": "+5511999999999",
        "tradeName": "Armazem 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": "Carga frágil",
        "tradePolicyExceptions": [2, 3]
      },
      "status": {
        "id": 2,
        "orderStatusParentId": 1,
        "code": "paid",
        "name": "Pago",
        "icon": "check-circle",
        "children": [
          {
            "id": 3,
            "orderStatusParentId": 2,
            "code": "paid_confirmed",
            "name": "Pagamento confirmado",
            "icon": "check-double",
            "children": []
          }
        ]
      },
      "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": {
        "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": "code",
        "initialDeliveryForecast": "2026-04-30",
        "finalDeliveryForecast": "2026-05-02",
        "shippingValue": 10.00,
        "trackingCode": "TRK123456789",
        "reverseLogisticsCode": null,
        "trackingUrl": "https://carrier.com/track/TRK123456789",
        "schedule": false,
        "scheduleDay": null,
        "scheduleHour": null,
        "pickUpDetails": {
          "pointName": "Ponto de retirada Centro",
          "address": "Rua Exemplo, 100 - São Paulo/SP"
        }
      },
      "discounts": [
        {
          "id": 1,
          "orderId": 123,
          "type": "coupon",
          "entityId": "CUPOM10",
          "value": 10.00
        }
      ],
      "additions": [
        {
          "id": 1,
          "orderId": 123,
          "type": "tax",
          "entityId": "ICMS_ST",
          "value": 5.00
        }
      ],
      "items": [
        {
          "id": 1,
          "orderId": 123,
          "productId": 50,
          "name": "Camiseta Algodão Premium",
          "description": "Camiseta algodão premium tamanho grande",
          "sku": "TSHIRT-WHITE-G",
          "priceRule":[ 
            {
              "id": 1,
              "name": "Promoção de Verão",
              "trigger": "code",
              "ruleTarget": "product",
              "origin": "trade_policy",
              "applyInGroup": false,
              "updateComparisonPrice": "none",
              "basePriceField": "price",
              "code": "VERAO2026",
              "beginQuantity": null,
              "endQuantity": null,
              "value": 10,
              "valueType": "percentage",
              "priority": 10,
              "active": true,
              "scheduling": null,
              "tradePolicies": [1],
              "productIds": [],
              "productCategoryIds": [],
              "productBrandIds": [],
              "lastUpdateUserName": null,
              "createdAt": "2026-01-01 10:00:00",
              "updatedAt": "2026-01-15 12:00:00"
            },
          ],
          "priceRuleId": 1,
          "quantity": 2.0,
          "unitValue": 70.00,
          "unitAdditionValue": 0.00,
          "unitDiscountValue": 7.00,
          "subtotalValue": 140.00,
          "subtotalAdditionValue": 0.00,
          "subtotalDiscountValue": 14.00,
          "totalValue": 126.00,
          "service": false,
          "generateGiftCard": false,
          "discounts": [
            {
              "orderDiscountId": 1,
              "orderAdditionId": null,
              "value": 14.00,
              "detail": {
                "entity": {
                  "entity": "price_rule",
                  "identifier": 1,
                  "description": "Promoção de Lançamento",
                  "type": "percentage",
                  "target": "subtotal",
                  "error": null
                },
                "target": "subtotal",
                "value": 14.0
              }
            }
          ],
          "additions": [
            {
              "orderDiscountId": null,
              "orderAdditionId": 1,
              "value": 2.50,
              "detail": {
                "entity": {
                  "entity": "tax",
                  "identifier": "ICMS_ST",
                  "description": "Substituição tributária",
                  "type": "value",
                  "target": "subtotal",
                  "error": null
                },
                "value": 2.5
              }
            }
          ],
          "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://loja.com.br/camiseta-algodao-premium",
            "comparisonPrice": 80.00,
            "stock": 100.0,
            "medias": [
              {
                "id": 1,
                "type": "image",
                "title": "Frente da Camiseta",
                "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": {
              "tradePolicyId": 1,
              "requiredAge": 18
            }
          }
        }
      ],
      "payments": [
        {
          "id": 1,
          "orderGroupId": 456,
          "orderId": 123,
          "customerCardId": 123,
          "paymentType": "credit-card",
          "paymentProof": "https://gateway.com/proof/abc",
          "paymentExpirationDate": "2026-04-27",
          "paymentOptionId": 1,
          "parentPaymentOptionId": null,
          "paymentOptionLabel": "Visa",
          "paymentOptionDetail": "Visa 1x",
          "integrationName": "Vindi",
          "transactionId": "trans_abc123",
          "currentStatus": "captured",
          "paymentAntiFraudId": "af_123",
          "paymentAntiFraudCredentialId": 1,
          "antiFraudStatus": "approved",
          "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-123456",
            "subtotalValue": 140.00,
            "additionValue": 0.00,
            "shippingValue": 10.00,
            "discountValue": 0.00,
            "totalValue": 150.00
          },
          "logs": [
            {
              "id": 10,
              "tradePolicyId": 1,
              "orderPaymentId": 1,
              "cartId": "cart_abc123",
              "paymentOptionId": 1,
              "paymentOptionLabel": "Visa",
              "paymentOptionDetail": "Visa 1x",
              "transactionId": "trans_abc123",
              "userName": "Sistema",
              "userEmail": "system@uappi.com.br",
              "oldStatus": "pending",
              "newStatus": "captured",
              "origin": "gateway",
              "request": {},
              "response": {},
              "createdAt": "2026-04-27 10:10:00"
            }
          ]
        }
      ],
      "reserves": [
        {
          "id": 1,
          "customerId": 789,
          "customerName": "João Silva",
          "orderId": 123,
          "type": "order",
          "status": "active",
          "reason": "Pedido Realizado",
          "reserveCustomer": {
            "id": 789,
            "tradePolicyId": 1,
            "email": "joao.silva@email.com.br",
            "nameCorporateName": "João Silva",
            "phone": "(11) 98765-4321",
            "active": true,
            "masked": false
          },
          "items": [
            {
              "productId": 50,
              "productStorageId": 1,
              "amount": 2
            }
          ],
          "userId": null,
          "userName": null,
          "userEmail": null,
          "reserveUserId": null,
          "reserveUserName": null,
          "reserveUserEmail": null,
          "cancelUserId": null,
          "cancelUserName": null,
          "cancelUserEmail": null,
          "createdAt": "2026-04-27 10:00:00",
          "completedAt": null,
          "canceledAt": null
        }
      ],
      "invoice": {
        "orderId": 123,
        "number": "000123456",
        "key": "35210112345678000190550010001234561234567890",
        "serie": "1",
        "url": "https://cdn.uappi.com.br/invoices/123.pdf",
        "xml": null
      },
      "histories": [
        {
          "id": 2,
          "userId": 1,
          "userName": "Sistema",
          "userEmail": "system@uappi.com.br",
          "origin": "webhook",
          "action": "order_paid",
          "createdAt": "2026-04-27 10:10:00",
          "before": {
            "orderStatusId": 1
          },
          "after": {
            "orderStatusId": 2
          },
          "orderGroupId": 456,
          "orderId": 123,
          "newOrderStatusId": 2
        }
      ],
      "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": "cart_abc123"
        }
      ]
    }
  ],
  "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_NOT_FOUND	404	Nenhum pedido foi localizado com os critérios informados.
UAPPI_STORE_TRADE_POLICY_NOT_FOUND	404	A política comercial solicitada não foi encontrada.
UAPPI_STORE_INVALID_SEARCH_FIELDS	400	Um ou mais campos de busca informados não são permitidos.
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.

Busca de Pedido

GET /orders/{orderId}

Retorna as informações detalhadas de um pedido específico.

Descrição

Este endpoint permite a consulta individual de um pedido através do seu identificador único. O acesso exige o escopo de permissão ORDER_READ.

Dados sensíveis do cliente (nome, e-mail, documento, telefone e parte do endereço) podem ser devolvidos mascarados quando a autenticação for de usuário humano e não houver liberação recente de acesso aos dados sensíveis no fluxo da API.

Tokens de integração (userType de integração) seguem outro critério e costumam receber o payload sem essa camada de mascaramento.

Assim como na listagem, o parâmetro fields pode ser utilizado para expandir as relações do pedido, permitindo visualizar em uma única chamada os itens comprados, endereços, pagamentos e até mesmo logs de erro financeiros.

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 da URL

Parâmetro	Tipo	Obrigatório	Descrição
orderId	integer	Sim	ID único do pedido

Campos Disponíveis (fields)

Campo	Descrição
orderGroup	Dados gerais do grupo de pedido.
productStorage	Informações do estoque de origem.
status	Detalhes do status atual do pedido.
customer	Dados completos do comprador.
addresses	Endereços de entrega e faturamento.
values	Detalhamento de valores (subtotal, frete, descontos, total).
shipping	Informações de logística e entrega.
items	Lista detalhada de produtos no pedido.
payments	Dados das transações de pagamento realizadas.
paymentLogs	Histórico de logs e comunicações de pagamento.
reserves	Informações de reservas de estoque vinculadas.
invoice	Informações fiscais (nota fiscal).
discounts	Detalhamento de descontos aplicados.
additions	Detalhamento de acréscimos aplicados ao valor.
histories	Histórico completo de auditoria e alterações.
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 do pedido (código, formas de pagamento permitidas e expiração).

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders/123 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": ["orderGroup", "customer", "items", "values", "shipping", "payments", "addresses", "invoice"]
6  }'
curl --request GET \
  --url {{MAIN_URL}}/orders/123 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": ["orderGroup", "customer", "items", "values", "shipping", "payments", "addresses", "invoice"]
  }'

✅ Resposta de Sucesso

1{
2  "id": 123,
3  "orderGroupId": 456,
4  "productStorageId": 1,
5  "orderStatusId": 2,
6  "marketplaceOrderId": "MKTP-987654",
7  "masked": false,
8  "orderGroup": {
9    "id": 456,
10    "cartId": "cart_abc123",
11    "tradePolicyId": 1,
12    "userId": null,
13    "userEmail": "vendedor@loja.com.br",
14    "userName": "Vendedor Interno",
15    "code": "UAPPI-123456",
16    "salesChannelDomain": "loja.exemplo.com.br",
17    "marketplaceId": null,
18    "marketplaceName": null,
19    "marketplaceStoreCredentialId": null,
20    "marketplaceOrderGroupId": null,
21    "currency": "BRL",
22    "createdAt": "2026-04-27 10:00:00",
23    "issuedAt": "2026-04-27 10:05:00"
24  },
25  "productStorage": {
26    "id": 1,
27    "code": "abc123",
28    "corporateName": "Armazem Central LTDA",
29    "email": "contato@armazem.com.br",
30    "phone": "+5511999999999",
31    "tradeName": "Armazem Central",
32    "stateCode": "SP",
33    "countryCode": "BRA",
34    "document": "12345678000190",
35    "zipCode": "01001000",
36    "city": "São Paulo",
37    "address": "Avenida Paulista",
38    "district": "Bela Vista",
39    "number": "1000",
40    "complement": "Andar 10",
41    "latitude": "-23.561684",
42    "longitude": "-46.655981",
43    "active": true,
44    "observation": "Carga frágil",
45    "tradePolicyExceptions": [2, 3]
46  },
47  "status": {
48    "id": 2,
49    "orderStatusParentId": 1,
50    "code": "paid",
51    "name": "Pago",
52    "icon": "check-circle",
53    "children": [
54      {
55        "id": 3,
56        "orderStatusParentId": 2,
57        "code": "paid_confirmed",
58        "name": "Pagamento confirmado",
59        "icon": "check-double",
60        "children": []
61      }
62    ]
63  },
64  "customer": {
65    "orderGroupId": 456,
66    "customerId": 789,
67    "customerNameCorporateName": "João Silva",
68    "customerTradeName": "João Silva",
69    "customerEmail": "joao.silva@email.com.br",
70    "customerDocument": "123.456.789-00",
71    "customerDocument2": "RG 12.345.678-9",
72    "customerPhone": "(11) 98765-4321",
73    "customerIsCorporate": false,
74    "customerGender": "M",
75    "customerBirthdate": "1990-01-01"
76  },
77  "addresses": [
78    {
79      "orderGroupId": 456,
80      "customerAddressType": "shipping",
81      "customerAddressId": 123,
82      "addressZipCode": "01001-000",
83      "addressRecipient": "João Silva",
84      "addressStreet": "Praça da Sé",
85      "addressNumber": "100",
86      "addressDistrict": "Sé",
87      "addressCity": "São Paulo",
88      "addressState": "São Paulo",
89      "addressStateCode": "SP",
90      "addressCountryCode": "BRA",
91      "addressComplement": "Apto 1"
92    },
93    {
94      "orderGroupId": 456,
95      "customerAddressType": "billing",
96      "customerAddressId": 124,
97      "addressZipCode": "01001-000",
98      "addressRecipient": "João Silva",
99      "addressStreet": "Praça da Sé",
100      "addressNumber": "100",
101      "addressDistrict": "Sé",
102      "addressCity": "São Paulo",
103      "addressState": "São Paulo",
104      "addressStateCode": "SP",
105      "addressCountryCode": "BRA",
106      "addressComplement": "Apto 1"
107    }
108  ],
109  "values": {
110    "orderId": 123,
111    "subtotalValue": 140.00,
112    "additionValue": 0.00,
113    "shippingValue": 10.00,
114    "discountValue": 0.00,
115    "totalValue": 150.00
116  },
117  "shipping": {
118    "orderId": 123,
119    "externalOrderId": "1000456-123",
120    "shippingTableId": 5,
121    "label": "Entrega Expressa",
122    "shippingCarrierId": 5,
123    "shippingCarrier": "Transportadora Rápida",
124    "beginShippingTime": 2,
125    "endShippingTime": 5,
126    "shippingIntegrationCode": "code",
127    "initialDeliveryForecast": "2026-04-30",
128    "finalDeliveryForecast": "2026-05-02",
129    "shippingValue": 10.00,
130    "trackingCode": "TRK123456789",
131    "reverseLogisticsCode": null,
132    "trackingUrl": "https://carrier.com/track/TRK123456789",
133    "schedule": false,
134    "scheduleDay": null,
135    "scheduleHour": null,
136    "pickUpDetails": {
137      "pointName": "Ponto de retirada Centro",
138      "address": "Rua Exemplo, 100 - São Paulo/SP"
139    }
140  },
141  "discounts": [
142    {
143      "id": 1,
144      "orderId": 123,
145      "type": "coupon",
146      "entityId": "CUPOM10",
147      "value": 10.00
148    }
149  ],
150  "additions": [
151    {
152      "id": 1,
153      "orderId": 123,
154      "type": "tax",
155      "entityId": "ICMS_ST",
156      "value": 5.00
157    }
158  ],
159  "items": [
160    {
161      "id": 1,
162      "orderId": 123,
163      "productId": 50,
164      "name": "Camiseta Algodão Premium",
165      "description": "Camiseta algodão premium tamanho grande",
166      "sku": "TSHIRT-WHITE-G",
167      "priceRule":[ 
168        {
169          "id": 1,
170          "name": "Promoção de Verão",
171          "trigger": "code",
172          "ruleTarget": "product",
173          "origin": "trade_policy",
174          "applyInGroup": false,
175          "updateComparisonPrice": "none",
176          "basePriceField": "price",
177          "code": "VERAO2026",
178          "beginQuantity": null,
179          "endQuantity": null,
180          "value": 10,
181          "valueType": "percentage",
182          "priority": 10,
183          "active": true,
184          "scheduling": null,
185          "tradePolicies": [1],
186          "productIds": [],
187          "productCategoryIds": [],
188          "productBrandIds": [],
189          "lastUpdateUserName": null,
190          "createdAt": "2026-01-01 10:00:00",
191          "updatedAt": "2026-01-15 12:00:00"
192        },
193      ],
194      "priceRuleId": 1,
195      "quantity": 2.0,
196      "unitValue": 70.00,
197      "unitAdditionValue": 0.00,
198      "unitDiscountValue": 7.00,
199      "subtotalValue": 140.00,
200      "subtotalAdditionValue": 0.00,
201      "subtotalDiscountValue": 14.00,
202      "totalValue": 126.00,
203      "service": false,
204      "generateGiftCard": false,
205      "discounts": [
206        {
207          "orderDiscountId": 1,
208          "orderAdditionId": null,
209          "value": 14.00,
210          "detail": {
211            "entity": {
212              "entity": "price_rule",
213              "identifier": 1,
214              "description": "Promoção de Lançamento",
215              "type": "percentage",
216              "target": "subtotal",
217              "error": null
218            },
219            "target": "subtotal",
220            "value": 14.0
221          }
222        }
223      ],
224      "additions": [
225        {
226          "orderDiscountId": null,
227          "orderAdditionId": 1,
228          "value": 2.50,
229          "detail": {
230            "entity": {
231              "entity": "tax",
232              "identifier": "ICMS_ST",
233              "description": "Substituição tributária",
234              "type": "value",
235              "target": "subtotal",
236              "error": null
237            },
238            "value": 2.5
239          }
240        }
241      ],
242      "simpleProduct": {
243        "productId": 50,
244        "brandId": 10,
245        "brandName": "Marca X",
246        "mainCategoryId": 5,
247        "mainCategoryName": "Roupas",
248        "type": "simple",
249        "sku": "TSHIRT-WHITE-G",
250        "name": "Camiseta Algodão Premium",
251        "active": true,
252        "url": "https://loja.com.br/camiseta-algodao-premium",
253        "comparisonPrice": 80.00,
254        "stock": 100.0,
255        "medias": [
256          {
257            "id": 1,
258            "type": "image",
259            "title": "Frente da Camiseta",
260            "alternativeText": "Camiseta branca de algodão",
261            "file": "/upload/stores/1/media/img1.jpg",
262            "originalFile": "/upload/stores/1/media/img1_orig.jpg",
263            "size": 102400.0,
264            "originalSize": 512000.0,
265            "width": 800.0,
266            "height": 800.0,
267            "url": "https://cdn.uappi.com.br/upload/stores/1/media/img1.jpg"
268          }
269        ],
270        "combination": [1],
271        "currentAttributes": [
272          {
273            "id": 1,
274            "name": "Cor",
275            "value": {
276              "id": 10,
277              "label": "Branco",
278              "image": null,
279              "originalImage": null,
280              "color": "#FFFFFF",
281              "order": 1
282            }
283          }
284        ],
285        "restriction": {
286          "tradePolicyId": 1,
287          "requiredAge": 18
288        }
289      }
290    }
291  ],
292  "payments": [
293    {
294      "id": 1,
295      "orderGroupId": 456,
296      "orderId": 123,
297      "customerCardId": 123,
298      "paymentType": "credit-card",
299      "paymentProof": "https://gateway.com/proof/abc",
300      "paymentExpirationDate": "2026-04-27",
301      "paymentOptionId": 1,
302      "parentPaymentOptionId": null,
303      "paymentOptionLabel": "Visa",
304      "paymentOptionDetail": "Visa 1x",
305      "integrationName": "Vindi",
306      "transactionId": "trans_abc123",
307      "currentStatus": "captured",
308      "paymentAntiFraudId": "af_123",
309      "paymentAntiFraudCredentialId": 1,
310      "antiFraudStatus": "approved",
311      "pixQrCode": null,
312      "pixEmv": null,
313      "billetBarCode": null,
314      "billetDigitableLine": null,
315      "billetUrl": null,
316      "cardAutomaticCapture": true,
317      "cardMasked": "4111<strong></strong><strong></strong>1111",
318      "cardFlag": "visa",
319      "cardExpiration": "12/2028",
320      "internalDepositBank": {
321        "name": "Razão Social da Empresa LTDA",
322        "bankName": "Itaú Unibanco",
323        "bank": "341",
324        "agency": "0001",
325        "account": "12345-6",
326        "operation": "",
327        "document": "00.000.000/0001-00"
328      },
329      "value": 150.00,
330      "installment": 1,
331      "installmentValue": 150.00,
332      "fee": 0.00,
333      "orderGroup": {
334        "id": 456,
335        "code": "UAPPI-123456",
336        "subtotalValue": 140.00,
337        "additionValue": 0.00,
338        "shippingValue": 10.00,
339        "discountValue": 0.00,
340        "totalValue": 150.00
341      },
342      "logs": [
343        {
344          "id": 10,
345          "tradePolicyId": 1,
346          "orderPaymentId": 1,
347          "cartId": "cart_abc123",
348          "paymentOptionId": 1,
349          "paymentOptionLabel": "Visa",
350          "paymentOptionDetail": "Visa 1x",
351          "transactionId": "trans_abc123",
352          "userName": "Sistema",
353          "userEmail": "system@uappi.com.br",
354          "oldStatus": "pending",
355          "newStatus": "captured",
356          "origin": "gateway",
357          "request": {},
358          "response": {},
359          "createdAt": "2026-04-27 10:10:00"
360        }
361      ]
362    }
363  ],
364  "reserves": [
365    {
366      "id": 1,
367      "customerId": 789,
368      "customerName": "João Silva",
369      "orderId": 123,
370      "type": "order",
371      "status": "active",
372      "reason": "Pedido Realizado",
373      "reserveCustomer": {
374        "id": 789,
375        "tradePolicyId": 1,
376        "email": "joao.silva@email.com.br",
377        "nameCorporateName": "João Silva",
378        "phone": "(11) 98765-4321",
379        "active": true,
380        "masked": false
381      },
382      "items": [
383        {
384          "productId": 50,
385          "productStorageId": 1,
386          "amount": 2
387        }
388      ],
389      "userId": null,
390      "userName": null,
391      "userEmail": null,
392      "reserveUserId": null,
393      "reserveUserName": null,
394      "reserveUserEmail": null,
395      "cancelUserId": null,
396      "cancelUserName": null,
397      "cancelUserEmail": null,
398      "createdAt": "2026-04-27 10:00:00",
399      "completedAt": null,
400      "canceledAt": null
401    }
402  ],
403  "invoice": {
404    "orderId": 123,
405    "number": "000123456",
406    "key": "35210112345678000190550010001234561234567890",
407    "serie": "1",
408    "url": "https://cdn.uappi.com.br/invoices/123.pdf",
409    "xml": null
410  },
411  "histories": [
412    {
413      "id": 2,
414      "userId": 1,
415      "userName": "Sistema",
416      "userEmail": "system@uappi.com.br",
417      "origin": "webhook",
418      "action": "order_paid",
419      "createdAt": "2026-04-27 10:10:00",
420      "before": {
421        "orderStatusId": 1
422      },
423      "after": {
424        "orderStatusId": 2
425      },
426      "orderGroupId": 456,
427      "orderId": 123,
428      "newOrderStatusId": 2
429    }
430  ],
431  "devices": [
432    {
433      "deviceInfoCode": "remote-address",
434      "value": "203.0.113.10"
435    },
436    {
437      "deviceInfoCode": "user-agent",
438      "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
439    },
440    {
441      "deviceInfoCode": "cookies",
442      "value": "{\"_fbc\":\"fb.1.123456789.abcdef\",\"_fbp\":\"fb.1.123456789.ghijkl\",\"utm_source\":\"instagram\"}"
443    },
444    {
445      "deviceInfoCode": "antifraud-fingerprint",
446      "value": "cart_abc123"
447    }
448  ]
449}
{
  "id": 123,
  "orderGroupId": 456,
  "productStorageId": 1,
  "orderStatusId": 2,
  "marketplaceOrderId": "MKTP-987654",
  "masked": false,
  "orderGroup": {
    "id": 456,
    "cartId": "cart_abc123",
    "tradePolicyId": 1,
    "userId": null,
    "userEmail": "vendedor@loja.com.br",
    "userName": "Vendedor Interno",
    "code": "UAPPI-123456",
    "salesChannelDomain": "loja.exemplo.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"
  },
  "productStorage": {
    "id": 1,
    "code": "abc123",
    "corporateName": "Armazem Central LTDA",
    "email": "contato@armazem.com.br",
    "phone": "+5511999999999",
    "tradeName": "Armazem 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": "Carga frágil",
    "tradePolicyExceptions": [2, 3]
  },
  "status": {
    "id": 2,
    "orderStatusParentId": 1,
    "code": "paid",
    "name": "Pago",
    "icon": "check-circle",
    "children": [
      {
        "id": 3,
        "orderStatusParentId": 2,
        "code": "paid_confirmed",
        "name": "Pagamento confirmado",
        "icon": "check-double",
        "children": []
      }
    ]
  },
  "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": {
    "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": "code",
    "initialDeliveryForecast": "2026-04-30",
    "finalDeliveryForecast": "2026-05-02",
    "shippingValue": 10.00,
    "trackingCode": "TRK123456789",
    "reverseLogisticsCode": null,
    "trackingUrl": "https://carrier.com/track/TRK123456789",
    "schedule": false,
    "scheduleDay": null,
    "scheduleHour": null,
    "pickUpDetails": {
      "pointName": "Ponto de retirada Centro",
      "address": "Rua Exemplo, 100 - São Paulo/SP"
    }
  },
  "discounts": [
    {
      "id": 1,
      "orderId": 123,
      "type": "coupon",
      "entityId": "CUPOM10",
      "value": 10.00
    }
  ],
  "additions": [
    {
      "id": 1,
      "orderId": 123,
      "type": "tax",
      "entityId": "ICMS_ST",
      "value": 5.00
    }
  ],
  "items": [
    {
      "id": 1,
      "orderId": 123,
      "productId": 50,
      "name": "Camiseta Algodão Premium",
      "description": "Camiseta algodão premium tamanho grande",
      "sku": "TSHIRT-WHITE-G",
      "priceRule":[ 
        {
          "id": 1,
          "name": "Promoção de Verão",
          "trigger": "code",
          "ruleTarget": "product",
          "origin": "trade_policy",
          "applyInGroup": false,
          "updateComparisonPrice": "none",
          "basePriceField": "price",
          "code": "VERAO2026",
          "beginQuantity": null,
          "endQuantity": null,
          "value": 10,
          "valueType": "percentage",
          "priority": 10,
          "active": true,
          "scheduling": null,
          "tradePolicies": [1],
          "productIds": [],
          "productCategoryIds": [],
          "productBrandIds": [],
          "lastUpdateUserName": null,
          "createdAt": "2026-01-01 10:00:00",
          "updatedAt": "2026-01-15 12:00:00"
        },
      ],
      "priceRuleId": 1,
      "quantity": 2.0,
      "unitValue": 70.00,
      "unitAdditionValue": 0.00,
      "unitDiscountValue": 7.00,
      "subtotalValue": 140.00,
      "subtotalAdditionValue": 0.00,
      "subtotalDiscountValue": 14.00,
      "totalValue": 126.00,
      "service": false,
      "generateGiftCard": false,
      "discounts": [
        {
          "orderDiscountId": 1,
          "orderAdditionId": null,
          "value": 14.00,
          "detail": {
            "entity": {
              "entity": "price_rule",
              "identifier": 1,
              "description": "Promoção de Lançamento",
              "type": "percentage",
              "target": "subtotal",
              "error": null
            },
            "target": "subtotal",
            "value": 14.0
          }
        }
      ],
      "additions": [
        {
          "orderDiscountId": null,
          "orderAdditionId": 1,
          "value": 2.50,
          "detail": {
            "entity": {
              "entity": "tax",
              "identifier": "ICMS_ST",
              "description": "Substituição tributária",
              "type": "value",
              "target": "subtotal",
              "error": null
            },
            "value": 2.5
          }
        }
      ],
      "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://loja.com.br/camiseta-algodao-premium",
        "comparisonPrice": 80.00,
        "stock": 100.0,
        "medias": [
          {
            "id": 1,
            "type": "image",
            "title": "Frente da Camiseta",
            "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": {
          "tradePolicyId": 1,
          "requiredAge": 18
        }
      }
    }
  ],
  "payments": [
    {
      "id": 1,
      "orderGroupId": 456,
      "orderId": 123,
      "customerCardId": 123,
      "paymentType": "credit-card",
      "paymentProof": "https://gateway.com/proof/abc",
      "paymentExpirationDate": "2026-04-27",
      "paymentOptionId": 1,
      "parentPaymentOptionId": null,
      "paymentOptionLabel": "Visa",
      "paymentOptionDetail": "Visa 1x",
      "integrationName": "Vindi",
      "transactionId": "trans_abc123",
      "currentStatus": "captured",
      "paymentAntiFraudId": "af_123",
      "paymentAntiFraudCredentialId": 1,
      "antiFraudStatus": "approved",
      "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-123456",
        "subtotalValue": 140.00,
        "additionValue": 0.00,
        "shippingValue": 10.00,
        "discountValue": 0.00,
        "totalValue": 150.00
      },
      "logs": [
        {
          "id": 10,
          "tradePolicyId": 1,
          "orderPaymentId": 1,
          "cartId": "cart_abc123",
          "paymentOptionId": 1,
          "paymentOptionLabel": "Visa",
          "paymentOptionDetail": "Visa 1x",
          "transactionId": "trans_abc123",
          "userName": "Sistema",
          "userEmail": "system@uappi.com.br",
          "oldStatus": "pending",
          "newStatus": "captured",
          "origin": "gateway",
          "request": {},
          "response": {},
          "createdAt": "2026-04-27 10:10:00"
        }
      ]
    }
  ],
  "reserves": [
    {
      "id": 1,
      "customerId": 789,
      "customerName": "João Silva",
      "orderId": 123,
      "type": "order",
      "status": "active",
      "reason": "Pedido Realizado",
      "reserveCustomer": {
        "id": 789,
        "tradePolicyId": 1,
        "email": "joao.silva@email.com.br",
        "nameCorporateName": "João Silva",
        "phone": "(11) 98765-4321",
        "active": true,
        "masked": false
      },
      "items": [
        {
          "productId": 50,
          "productStorageId": 1,
          "amount": 2
        }
      ],
      "userId": null,
      "userName": null,
      "userEmail": null,
      "reserveUserId": null,
      "reserveUserName": null,
      "reserveUserEmail": null,
      "cancelUserId": null,
      "cancelUserName": null,
      "cancelUserEmail": null,
      "createdAt": "2026-04-27 10:00:00",
      "completedAt": null,
      "canceledAt": null
    }
  ],
  "invoice": {
    "orderId": 123,
    "number": "000123456",
    "key": "35210112345678000190550010001234561234567890",
    "serie": "1",
    "url": "https://cdn.uappi.com.br/invoices/123.pdf",
    "xml": null
  },
  "histories": [
    {
      "id": 2,
      "userId": 1,
      "userName": "Sistema",
      "userEmail": "system@uappi.com.br",
      "origin": "webhook",
      "action": "order_paid",
      "createdAt": "2026-04-27 10:10:00",
      "before": {
        "orderStatusId": 1
      },
      "after": {
        "orderStatusId": 2
      },
      "orderGroupId": 456,
      "orderId": 123,
      "newOrderStatusId": 2
    }
  ],
  "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": "cart_abc123"
    }
  ]
}

⚠️ 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_NOT_FOUND	404	O pedido solicitado através do `orderId` 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.

Alteração de Status em Massa

PUT /orders/change-status

Realiza a alteração do status de múltiplos pedidos simultaneamente.

Descrição

Este endpoint permite atualizar o status de vários pedidos de uma só vez, facilitando ações em lote no fluxo operacional (como avançar pedidos para envio ou marcar como cancelados).

Para cada pedido informado, o sistema valida se o pedido existe e se o status de destino é válido. Em seguida, aplica automaticamente regras importantes — como reserva ou liberação de estoque, dependendo do tipo de status — e registra um evento, que pode disparar integrações ou notificações configuradas na loja.

Esse recurso é especialmente útil para rotinas de logística e expedição, onde é comum precisar atualizar diversos pedidos ao mesmo tempo.

O uso deste endpoint exige o escopo ORDER_WRITE.

---

Fases padrão de status

A loja pode ter vários status personalizados, mas todos eles se baseiam em algumas fases padrão do fluxo do pedido:

1 pending → aguardando
2 paid → pago
3invoiced → faturado
4 sent → enviado
5 delivered → entregue
6 canceled → cancelado
7 returned → devolvido

Cada status cadastrado pertence a uma dessas fases.

> Importante: > Ao enviar um novo status (newStatusId), utilize sempre o id retornado por GET /orders/status. > Nem todo status válido está entre os IDs das fases padrão (1 a 7), pois status personalizados também podem ser usados.

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 Corpo

Parâmetro	Tipo	Obrigatório	Descrição
orders	array	Sim	Lista de instruções de alteração. Máximo 100 itens.
orders.*.orderId	integer	Sim	ID único do pedido a ser alterado.
orders.*.newStatusId	integer	Sim	ID do novo status desejado.
orders.*.retroactiveDate	date	Não	Data retroativa para o registro (YYYY-MM-DD).

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/change-status \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orders": [
7      {
8        "orderId": 123,
9        "newStatusId": 5,
10        "retroactiveDate": "2026-04-26"
11      }
12    ]
13  }'
curl --request PUT \
  --url {{MAIN_URL}}/orders/change-status \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "orders": [
      {
        "orderId": 123,
        "newStatusId": 5,
        "retroactiveDate": "2026-04-26"
      }
    ]
  }'

✅ Resposta de Sucesso

1[
2  {
3    "orderId": 123,
4    "newStatusId": 5,
5    "oldStatusId": 4,
6    "retroactiveDate": "2026-04-26",
7    "error": null
8  }
9]
[
  {
    "orderId": 123,
    "newStatusId": 5,
    "oldStatusId": 4,
    "retroactiveDate": "2026-04-26",
    "error": 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_ORDER_NOT_FOUND	404	O pedido solicitado não foi encontrado (erro retornado no campo `error` do item).
UAPPI_STORE_ORDER_STATUS_NOT_FOUND	404	O status informado não existe no sistema.

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

Documentação de Pedidos

Visão Geral

Entidades Envolvidas

Notas e Considerações

Listagem de Pedidos

Descrição

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

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

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

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Busca de Pedido

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Campos Disponíveis (fields)

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Alteração de Status em Massa

Descrição

Fases padrão de status

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição