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

Sub-pedidos

Como um pedido com produtos de vários sellers se divide em pedido pai e sub-pedidos, e como consultar cada lado.

A Venddor pode funcionar como marketplace: a mesma compra leva produtos de sellers (lojistas) diferentes, ou de um seller e da própria loja. Cada seller cuida do seu pedaço (separar, enviar, emitir nota), então a plataforma divide a compra em:

  • um pedido pai: o que o cliente vê e paga, com o total da compra;
  • um sub-pedido por seller: com os itens, o frete rateado e o status daquele seller.

O cliente faz uma compra e recebe um número só (PEDIDO-20261011-0001); os sub-pedidos ganham o mesmo número com sufixo (-V1, -V2...). Compras com itens de um único seller (ou só da loja) não são divididas: nesse caso há um pedido só.

Esta página mostra como navegar entre pai e filhos. A divisão em si acontece sozinha na criação do pedido (Criar pedido).

Pontos-chave
  • Pai e sub-pedidos aparecem juntos em Listar pedidos. Filhos têm parent_id.
  • O frete do pai é rateado entre os filhos, e a soma dos totais dos filhos é igual ao total do pai.
  • Cada sub-pedido tem status, remessas, rastreio e nota próprios. Quem envia mexe no sub-pedido, não no pai.
  • O status do pai é calculado a partir dos filhos (regra abaixo). Você não precisa (e normalmente não deve) mudá-lo à mão.
GET/api/v1/admin/orders/{id}/sub-ordersAdmin

Subpedidos de um pedido pai

Devolve os sub-pedidos de um pedido pai, cada um com os itens. Para um pedido que não foi dividido, count é 0. Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do pedido pai.
GET/api/v1/admin/orders/{id}/parentAdmin

Pedido pai de um subpedido

Dado o id de um sub-pedido, devolve o pedido pai (com itens e endereços). Para um pedido que não é sub-pedido, devolve parent_order: null. Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do sub-pedido.

Exemplo de requisição

bash
# Sub-pedidos de um pedido pai
curl "$BASE_URL/api/v1/admin/orders/$PARENT_ID/sub-orders" \
  -H "Authorization: Bearer $TOKEN"

# Pai de um sub-pedido
curl "$BASE_URL/api/v1/admin/orders/$SUB_ID/parent" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sub-pedidos
json
{
  "parent_order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "count": 2,
  "sub_orders": [
    {
      "id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
      "order_number": "PEDIDO-20261011-0001-V1",
      "parent_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "subtotal": 167895,
      "shipping_total": 1759,
      "discount_total": 0,
      "total": 169654,
      "payment_status": "pending",
      "status": "O",
      "status_text": "pending",
      "items": [
        { "id": "9787424c-0fca-44a9-9c96-9bba0c1f4704", "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "quantity": 1, "unit_price": 167895, "total": 167895 }
      ]
    },
    {
      "id": "0932405c-a8c1-49b3-a7db-61aab4c4d666",
      "order_number": "PEDIDO-20261011-0001-V2",
      "parent_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "subtotal": 23000,
      "shipping_total": 241,
      "total": 23241,
      "payment_status": "pending",
      "status": "O",
      "status_text": "pending",
      "items": [
        { "id": "ab1beb7c-f955-408a-a251-32c6ade93a95", "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "quantity": 2, "unit_price": 11500, "total": 23000 }
      ]
    }
  ]
}
200Pai de um sub-pedido (trecho)
json
{
  "parent_order": {
    "order": {
      "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001",
      "total": 192895,
      "status": "O"
    },
    "items": [],
    "addresses": []
  }
}
200Pedido que não é sub-pedido
json
{
  "parent_order": null,
  "message": "this order has no parent (it is a parent or single-vendor order)"
}

Campos da resposta

parent_order_iduuid
(sub-orders) Id do pedido pai consultado.
countinteger
(sub-orders) Quantidade de sub-pedidos.
sub_ordersarray
Sub-pedidos. Cada item tem os campos de pedido de Listar pedidos, mais items (as linhas daquele seller).
sub_orders[].vendor_iduuid
Seller dono do sub-pedido. Ausente no sub-pedido da própria loja.
sub_orders[].vendor_namestring
Nome do seller.
parent_orderobject
(parent) O pedido pai no formato de Consultar pedido (order, items, addresses), ou null.

Como o status do pai é calculado

Cada vez que o status de um sub-pedido muda, o status do pai é recalculado, nesta ordem de prioridade. Sub-pedidos cancelados ou reembolsados são ignorados nas regras 2 a 6, para um pai não ficar "preso" por um filho que saiu da compra.

  1. Todos os sub-pedidos estão cancelados ou reembolsados: o pai fica refunded (se algum foi reembolsado) ou cancelled.
  2. Todos os ativos estão completed: o pai fica completed.
  3. Todos os ativos estão delivered ou completed (e pelo menos um delivered): o pai fica delivered.
  4. Algum ativo está shipped: o pai fica shipped.
  5. Algum está paid: o pai fica paid.
  6. Algum está processing: o pai fica processing.
  7. Caso contrário, o pai não muda.

Exemplo: um sub-pedido entregue e outro ainda em processamento deixam o pai em processing; quando o segundo for entregue, o pai passa a delivered. Para forçar o recálculo de um pai, use POST /api/v1/admin/orders/{id}/sync-status (Alterar o status).

Erros

StatusQuandoCorpo
400Id 0 ou vazio{"error":"invalid id parameter"}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem view_orders/manage_orders{"error":"insufficient privileges","privilege_required_any":["manage_orders","view_orders"]}
404(parent) O pedido não existe{"error":"order not found"}
500Falha interna{"error":"failed to get sub-orders","detail":"..."}
Mexa no sub-pedido, não no pai

Remessa, rastreio, nota fiscal e mudança de status são do sub-pedido do seller. Os itens de cada remessa referenciam as linhas do sub-pedido (order_item_id), não as do pai. Ao integrar um ERP de seller, trabalhe sempre com o id do sub-pedido; o pai serve para o atendimento e para relatórios da compra inteira.

Veja também

  • Criar pedido
  • Alterar o status
  • Remessas e rastreio
Anterior
Ações em lote
Próxima
Remessas e rastreio
Nesta página
  • Exemplo de requisição
  • Resposta
  • Como o status do pai é calculado
  • Erros
  • Veja também