Ações em lote

Muda o status, atribui a forma de envio ou exporta as faturas de até 100 pedidos em uma só chamada.

Use o lote quando a mesma ação vale para muitos pedidos: marcar como "enviado" os 40 pedidos de uma carga, cancelar os pedidos de um dia com falha no gateway, ou baixar as faturas da semana. Em vez de 40 chamadas, uma chamada com a lista de ids.

Uma única chamada age sobre vários pedidos, em vez de uma chamada por pedido.

POST/api/v1/admin/orders/bulkAdmin

Ação em lote nos pedidos

Exige o privilégio manage_orders. Máximo de 100 pedidos por chamada. A mesma rota atende três ações, escolhidas por action:

`action`	O que faz	`value`
`update_status`	Muda o status de todos os pedidos da lista, um a um, pelas mesmas regras de Alterar o status (estoque, estorno, e-mails).	Código longo do status: `pending`, `processing`, `paid`, `shipped`, `delivered`, `completed`, `cancelled`, `refunded`, `failed`, `on_hold`, `chargeback`. A letra é recusada.
`assign_shipping`	Define a forma de envio dos pedidos.	UUID da forma de envio ativa. Só afeta pedidos em `pending`, `processing` ou `paid`.
`export_invoices`	Devolve os dados de fatura de cada pedido em JSON. Para o PDF, use Faturas e NF-e.	Não usa.

Cada pedido é processado de forma independente: os que não aceitam a mudança (por exemplo, uma transição proibida) ficam de fora e aparecem em failed; os demais mudam. O lote não é uma transação.

Corpo da requisição

order_idsarrayobrigatório

Ids (UUID) dos pedidos. De 1 a 100.

actionstringobrigatório

update_statusassign_shippingexport_invoices

Ação do lote.

valuestring

Parâmetro da ação (veja a tabela acima). Obrigatório em update_status e assign_shipping.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/orders/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": [
      "0932405c-a8c1-49b3-a7db-61aab4c4d666",
      "2b4bd680-b717-4295-a2be-8b5c6771a4d0"
    ],
    "action": "update_status",
    "value": "processing"
  }'

Resposta

200Lote aplicado

json

{
  "action": "update_status",
  "affected": 1,
  "failed": null,
  "message": "Updated 1 orders to status \"processing\""
}

200export_invoices (trecho)

json

{
  "action": "export_invoices",
  "count": 2,
  "invoices": [
    {
      "order": { "id": "0932405c-a8c1-49b3-a7db-61aab4c4d666", "order_number": "PEDIDO-20261011-0001-V2", "status": "processing", "currency": "BRL" },
      "customer": { "name": "Maria Souza", "email": "maria.souza@example.com" },
      "items": [{ "product_name": "Notebook Slim Rosa", "quantity": 2, "unit_price": 11500, "total": 23000 }],
      "totals": { "subtotal": 23000, "shipping_total": 241, "tax_total": 0, "discount_total": 0, "total": 23241 }
    }
  ]
}

Campos da resposta

actionstring

A ação executada.

affectedinteger

Quantos pedidos foram alterados. Compare com o tamanho da sua lista.

failedarray

Ids dos pedidos que não mudaram, ou null quando todos mudaram.

messagestring

Resumo em texto, em inglês.

countinteger

(export_invoices) Quantas faturas foram geradas.

invoicesarray

(export_invoices) Uma fatura por pedido, no formato de Faturas e NF-e. Valores em centavos.

Erros

Status	Quando	Corpo
400	`order_ids` vazio	`{"error":"order_ids is required and must not be empty"}`
400	Mais de 100 ids	`{"error":"maximum 100 orders per bulk action"}`
400	`action` ausente ou desconhecida	`{"error":"action is required"}` ou `{"error":"invalid action","detail":"action must be one of: update_status, export_invoices, assign_shipping"}`
400	`value` ausente	`{"error":"value is required for update_status action (new status)"}`
400	`value` em letra no `update_status`	`{"error":"invalid_status_format","detail":"order status in the wrong format for this route: \"P\" é a LETRA de order_statuses e esta rota espera o código longo; mande {\"value\":\"processing\"}. ..."}`
400	`value` não é um status válido	`{"error":"invalid_status","detail":"unknown target order status: \"bogus\" ..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_orders`	`{"error":"insufficient privileges","required":"manage_orders"}`
422	Nenhum pedido mudou (ids que não existem ou transição proibida para todos)	`{"error":"no order was updated","detail":"nenhum dos 1 ids é pedido desta loja: ... nada foi alterado"}`
500	Falha interna	`{"error":"failed to bulk update order status","detail":"..."}`

Veja também

Ações em lote

Muda o status, atribui a forma de envio ou exporta as faturas de até 100 pedidos em uma só chamada.

Uma única chamada age sobre vários pedidos, em vez de uma chamada por pedido.

POST/api/v1/admin/orders/bulkAdmin

Ação em lote nos pedidos

Exige o privilégio manage_orders. Máximo de 100 pedidos por chamada. A mesma rota atende três ações, escolhidas por action:

`action`	O que faz	`value`
`update_status`	Muda o status de todos os pedidos da lista, um a um, pelas mesmas regras de Alterar o status (estoque, estorno, e-mails).	Código longo do status: `pending`, `processing`, `paid`, `shipped`, `delivered`, `completed`, `cancelled`, `refunded`, `failed`, `on_hold`, `chargeback`. A letra é recusada.
`assign_shipping`	Define a forma de envio dos pedidos.	UUID da forma de envio ativa. Só afeta pedidos em `pending`, `processing` ou `paid`.
`export_invoices`	Devolve os dados de fatura de cada pedido em JSON. Para o PDF, use Faturas e NF-e.	Não usa.

Corpo da requisição

order_idsarrayobrigatório

Ids (UUID) dos pedidos. De 1 a 100.

actionstringobrigatório

update_statusassign_shippingexport_invoices

Ação do lote.

valuestring

Parâmetro da ação (veja a tabela acima). Obrigatório em update_status e assign_shipping.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/orders/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": [
      "0932405c-a8c1-49b3-a7db-61aab4c4d666",
      "2b4bd680-b717-4295-a2be-8b5c6771a4d0"
    ],
    "action": "update_status",
    "value": "processing"
  }'

Resposta

200Lote aplicado

json

{
  "action": "update_status",
  "affected": 1,
  "failed": null,
  "message": "Updated 1 orders to status \"processing\""
}

200export_invoices (trecho)

json

{
  "action": "export_invoices",
  "count": 2,
  "invoices": [
    {
      "order": { "id": "0932405c-a8c1-49b3-a7db-61aab4c4d666", "order_number": "PEDIDO-20261011-0001-V2", "status": "processing", "currency": "BRL" },
      "customer": { "name": "Maria Souza", "email": "maria.souza@example.com" },
      "items": [{ "product_name": "Notebook Slim Rosa", "quantity": 2, "unit_price": 11500, "total": 23000 }],
      "totals": { "subtotal": 23000, "shipping_total": 241, "tax_total": 0, "discount_total": 0, "total": 23241 }
    }
  ]
}

Campos da resposta

actionstring

A ação executada.

affectedinteger

Quantos pedidos foram alterados. Compare com o tamanho da sua lista.

failedarray

Ids dos pedidos que não mudaram, ou null quando todos mudaram.

messagestring

Resumo em texto, em inglês.

countinteger

(export_invoices) Quantas faturas foram geradas.

invoicesarray

(export_invoices) Uma fatura por pedido, no formato de Faturas e NF-e. Valores em centavos.

Erros

Status	Quando	Corpo
400	`order_ids` vazio	`{"error":"order_ids is required and must not be empty"}`
400	Mais de 100 ids	`{"error":"maximum 100 orders per bulk action"}`
400	`action` ausente ou desconhecida	`{"error":"action is required"}` ou `{"error":"invalid action","detail":"action must be one of: update_status, export_invoices, assign_shipping"}`
400	`value` ausente	`{"error":"value is required for update_status action (new status)"}`
400	`value` em letra no `update_status`	`{"error":"invalid_status_format","detail":"order status in the wrong format for this route: \"P\" é a LETRA de order_statuses e esta rota espera o código longo; mande {\"value\":\"processing\"}. ..."}`
400	`value` não é um status válido	`{"error":"invalid_status","detail":"unknown target order status: \"bogus\" ..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_orders`	`{"error":"insufficient privileges","required":"manage_orders"}`
422	Nenhum pedido mudou (ids que não existem ou transição proibida para todos)	`{"error":"no order was updated","detail":"nenhum dos 1 ids é pedido desta loja: ... nada foi alterado"}`
500	Falha interna	`{"error":"failed to bulk update order status","detail":"..."}`