VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Guia rápido/Pedidos

Pedidos por token de app

Acesso de aplicativos de terceiros aos pedidos, com token vat_ e escopos read_orders e write_orders, sem usuário administrador.

Um app de terceiros (um conector de ERP, um sistema de logística, uma ferramenta de BI) normalmente não deve usar o login de uma pessoa. A plataforma oferece outra forma de acesso: o app é cadastrado no portal de desenvolvedores da loja, recebe um token de app (começa com vat_live_ ou vat_test_) e só pode o que os escopos aprovados permitem.

As rotas de pedidos para apps ficam sob /api/admin/... (sem /v1.0) e aceitam esse token. Elas têm o seu próprio formato de resposta: valores em centavos (inteiros), datas em RFC 3339 e ids UUID, diferente das rotas /api/v1.0 desta seção, que usam string decimal e Unix timestamp. Esta página descreve o cabeçalho, os escopos, as rotas disponíveis e o formato de cada uma.

Pontos-chave
  • Cabeçalho: Authorization: Bearer vat_live_... (o token do app, não um JWT de usuário).
  • Escopos: read_orders para ler, write_orders para alterar. Sem o escopo, a resposta é 403.
  • Aceita somente token de app. Um JWT de usuário nestas rotas responde 401 app_token_required.
  • Mudança de status por token de app conta como "sistema" (não como administrador) no fluxo de status da loja.
  • Os privilégios finos do painel (como manage_orders) não são verificados aqui; o que vale é o escopo aprovado para o app.

Rotas disponíveis com token de app

RotaEscopoO que faz
GET /api/admin/ordersread_ordersLista pedidos, com filtros e paginação.
GET /api/admin/orders/{id}read_ordersConsulta um pedido com itens, endereços e histórico.
PUT /api/admin/orders/{id}/statuswrite_ordersMuda o status do pedido.
GET /api/admin/orders/{id}/shipmentsread_ordersLista as remessas do pedido.
POST /api/admin/orders/{id}/shipmentswrite_ordersCria uma remessa com rastreio.
GET /api/admin/orders/{id}/trackingread_ordersResumo plano do rastreio (primeira remessa): tracking_code, carrier, status, url. Responde 404 se o pedido não tem remessa.
GET /api/admin/users/{id}/ordersread_ordersLista os pedidos de um cliente (mesmo formato da lista de pedidos).

Não há rota de criação, cancelamento, reembolso ou edição por token de app: para isso use a API de administração com um usuário.

GET/api/admin/ordersAutenticada

Token de app: listar pedidos

Lista os pedidos da loja, do mais novo para o mais antigo. Escopo read_orders.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora desse intervalo volta ao padrão (20).
sort_bystringpadrão: created_at
created_attotalorder_numberstatuscustomer_namecustomer_email
Campo de ordenação.
sort_dirstringpadrão: desc
ascdesc
Direção da ordenação.
statusstring
Status do pedido, pelo código (processing) ou pela letra (P) do cadastro de status da loja.
payment_statusstring
pendingauthorizedcapturedpaidrefundedfailed
Situação do pagamento.
date_fromstring
Data inicial, YYYY-MM-DD ou RFC 3339.
date_tostring
Data final. Com YYYY-MM-DD o dia inteiro entra.
searchstring
Texto livre: número do pedido, e-mail ou nome do cliente.
GET/api/admin/orders/{id}Autenticada

Token de app: consultar um pedido

Devolve um envelope com o pedido (order), os itens (items), os endereços (addresses) e o histórico de status (status_history). Valores em centavos e datas RFC 3339. Escopo read_orders.

Parâmetros de caminho

iduuidobrigatório
Id do pedido.
PUT/api/admin/orders/{id}/statusAutenticada

Token de app: mudar o status de um pedido

Muda o status do pedido e devolve o pedido atualizado. Escopo write_orders. O histórico registra a mudança como feita por um sistema, sem usuário. Aqui o status vale pelas regras de transição da plataforma, diferente de PUT /api/v1.0/orders/{id}, que aceita qualquer letra em qualquer ordem.

Parâmetros de caminho

iduuidobrigatório
Id do pedido.

Corpo da requisição

statusstringobrigatório
Novo status, pelo código (shipped) ou pela letra (S) do cadastro da loja.
notesstring
Observação da mudança.
expected_updated_atstring
Controle de concorrência (RFC 3339).
GET/api/admin/orders/{id}/shipmentsAutenticada

Token de app: listar os envios de um pedido

Lista as remessas do pedido, com os itens de cada uma. Escopo read_orders.

Parâmetros de caminho

iduuidobrigatório
Id do pedido (ou do pedido filho de um seller).
POST/api/admin/orders/{id}/shipmentsAutenticada

Token de app: criar um envio

Cria uma remessa com os itens e as quantidades informadas. A plataforma confere que os itens são do pedido e que não se envia mais do que o pedido tem. Com tracking_code, a remessa nasce como enviada e o cliente recebe o e-mail de rastreio; sem o código, nasce pendente. Criar uma remessa não muda o status do pedido: faça isso com a rota de status. Escopo write_orders. Como não há usuário, o campo created_by da remessa fica vazio.

Parâmetros de caminho

iduuidobrigatório
Id do pedido (ou do pedido filho de um seller).

Corpo da requisição

itemsarrayobrigatório
Itens da remessa (order_item_id, quantity_shipped).
carrierstring
Transportadora.
tracking_codestring
Código de rastreio.
notesstring
Observação interna.

Exemplo de requisição

bash
curl "$BASE_URL/api/admin/orders?status=processing&per_page=50" \
  -H "Authorization: Bearer $APP_TOKEN"

curl -X PUT "$BASE_URL/api/admin/orders/$ORDER_ID/status" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"shipped","notes":"Coletado pela transportadora"}'

Resposta

Por exemplo, a lista de pedidos:

200Pedidos retornados (trecho)
json
{
  "orders": [
    {
      "id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "order_number": "PEDIDO-20261010-0004",
      "total": 22500,
      "status": "P",
      "status_text": "processing",
      "created_at": "2026-10-11T02:56:25.843882Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

ordersarray
Pedidos da página. Cada item traz id, order_number, total (centavos), status (letra), status_text (código do status), payment_status, customer_name, customer_email e created_at.
totalinteger
Total de pedidos que atendem ao filtro, em todas as páginas.
pageinteger
Página retornada.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Quantidade de páginas.
shipments[]array
(Remessas) Cada remessa traz id, order_id, tracking_code, carrier, status (letra), shipped_at e items (order_item_id, quantity_shipped, product_name, product_sku).

Erros

StatusQuandoCorpo
401Sem token, ou um JWT de usuário no lugar de um token de app{"error":"app_token_required"}
401Token de app inválido, revogado ou expirado{"error":"invalid or expired app access token"}
403O app não tem o escopo exigido pela rota{"error":"missing_scope","required":"write_orders"}
400Id 0 ou vazio no caminho{"error":"invalid id parameter"}
404Pedido inexistente{"error":"order not found"}
400Transição de status inválida{"error":"invalid_transition","detail":"..."}
Guarde o token de app como uma senha

O token vale por todo o escopo aprovado, e write_orders permite mudar o status de qualquer pedido da loja. Nunca o coloque em código de navegador ou em app instalado no aparelho do cliente; mantenha-o em um servidor seu e revogue-o no portal de desenvolvedores se vazar.

Veja também

  • Listar pedidos
  • Alterar o status
Anterior
Pedidos no app do seller
Próxima
Status de pedido
Nesta página
  • Rotas disponíveis com token de app
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também