API atual/Referência completa/Pedidos do seller

Consultar pedidos

Lista os pedidos do seller com filtros, detalha um pedido e exporta os pedidos para CSV ou planilha.

Estas rotas respondem à pergunta "o que eu preciso despachar?". A lista traz o resumo dos pedidos do seller, o detalhe traz itens, endereços e histórico de um pedido, e a exportação gera um arquivo para planilha ou ERP. O seller enxerga só o sub-pedido dele (veja a visão geral); os campos de cada pedido são os mesmos do administrador, descritos em Listar pedidos e Consultar pedido.

Listar pedidos

GET/api/v1/vendor/ordersSeller

Lista os pedidos do seller

Do mais novo para o mais antigo, por padrão. Exige um privilégio de pedidos do seller (por exemplo vendor_view_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 da faixa volta a 20.

statusstring

Status do pedido, pelo código (processing, shipped...) ou pela letra (P, S...) do cadastro de status da loja. Um status que não existe no cadastro não dá erro: a lista volta vazia.

payment_statusstring

pendingauthorizedcapturedpaidrefundedfailed

Situação do pagamento. paid é aceito como sinônimo de captured.

payment_methodstring

Código da forma de pagamento (pix, credit_card, boleto...), sem diferenciar maiúsculas.

date_fromstring

Data inicial, AAAA-MM-DD ou RFC 3339. Inclusive.

date_tostring

Data final. Com AAAA-MM-DD o dia inteiro entra; com horário, o limite é inclusivo.

min_totalinteger

Total mínimo, em centavos. Valor que não é número é ignorado.

max_totalinteger

Total máximo, em centavos. Valor que não é número é ignorado.

searchstring

Texto livre: número do pedido, e-mail, nome do cliente, CPF/CNPJ (quando o texto parece um documento) e número da ordem de compra do cliente.

sort_bystringpadrão: created_at

created_attotalorder_numberstatuscustomer_name

Campo de ordenação. Outro valor cai em created_at.

sort_dirstringpadrão: desc

ascdesc

Direção da ordenação.

has_document_typestring

Pedidos que têm anexo deste tipo (por exemplo nota_fiscal). Exige o recurso de documentos do pedido.

missing_document_typestring

Pedidos que não têm anexo deste tipo: serve para achar os pedidos sem nota fiscal.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/orders?status=processing&date_from=2026-10-01&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Pedidos do seller

json

{
  "orders": [
    {
      "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001-V1",
      "parent_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "subtotal": 30000,
      "shipping_total": 1500,
      "tax_total": 0,
      "discount_total": 7500,
      "total": 24000,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_status": "captured",
      "sales_channel": "web",
      "shipping_method_name": "Sedex",
      "customer_email": "maria.souza@example.com",
      "customer_name": "Maria Souza",
      "created_at": "2026-10-11T02:56:25.843882Z",
      "updated_at": "2026-10-11T02:56:38.131475Z",
      "status": "P",
      "status_text": "processing"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

ordersarray

Pedidos da página. Os campos principais estão abaixo; a lista completa está em Listar pedidos.

orders[].iduuid

Id do sub-pedido do seller. É o id que as outras rotas desta seção recebem.

orders[].order_numberstring

Número mostrado ao cliente. Sub-pedidos terminam em -V1, -V2...

orders[].parent_iduuid

Id do pedido pai (a compra completa do cliente).

orders[].vendor_iduuid

Seller dono do pedido: sempre o seu.

orders[].subtotalinteger

Soma dos itens, em centavos.

orders[].shipping_totalinteger

Frete, em centavos.

orders[].discount_totalinteger

Descontos, em centavos.

orders[].totalinteger

Total cobrado, em centavos.

orders[].statusstring

Letra do status (O, P, S...).

orders[].status_textstring

Código do status por extenso (pending, processing...).

orders[].payment_statusstring

Situação do pagamento.

orders[].created_atstring (RFC 3339)

Criação, em UTC.

totalinteger

Total de pedidos que casam com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página aplicado.

total_pagesinteger

Número de páginas.

Detalhar um pedido

GET/api/v1/vendor/orders/{id}Seller

Detalha um pedido do seller

Parâmetros de caminho

iduuidobrigatório

Id do sub-pedido do seller.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/vendor/orders/e148b6aa-d495-4b89-92ab-f38b5979a43f" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Pedido encontrado (trecho)

json

{
  "order": {
    "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "order_number": "PEDIDO-20261011-0001-V1",
    "parent_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "total": 24000,
    "status": "P",
    "status_text": "processing",
    "payment_method": "pix",
    "payment_status": "captured",
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza"
  },
  "items": [
    {
      "id": "020ead81-da4e-4b70-b80b-88562ba9497a",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camiseta Algodão Azul",
      "product_sku": "CAM-AZ-M",
      "unit_price": 15000,
      "quantity": 2,
      "discount": 7500,
      "total": 22500
    }
  ],
  "addresses": [
    {
      "address_type": "shipping",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11999990000"
    }
  ],
  "status_history": [
    { "old_status": "pending", "new_status": "processing", "notes": "Pagamento aprovado", "created_at": "2026-10-11T02:56:38.131475Z" }
  ]
}

Campos da resposta

orderobject

O pedido, com os campos da lista mais os detalhes (tracking_number, shipped_at, delivered_at, customer_notes, coupon_code...). Veja Consultar pedido.

itemsarray

Linhas do pedido: id (use-o como order_item_id ao criar uma remessa), product_id, product_name, product_sku, unit_price, quantity, discount e total, tudo em centavos.

addressesarray

Endereços de cobrança e entrega (address_type).

status_historyarray

Histórico de status, do mais antigo ao mais novo.

sub_ordersarray | omitted

Outros sub-pedidos do mesmo pai que são do seller. Os de outros sellers são sempre retirados.

Exportar pedidos

GET/api/v1/vendor/orders/exportSeller

Exporta os pedidos do seller em arquivo

Devolve um arquivo (não JSON) com uma linha por pedido do seller, do mais antigo ao mais novo. Exige um privilégio de importação ou de catálogo do seller (vendor_import_products, vendor_manage_products ou vendor_catalog). A exportação não aceita os outros filtros da lista.

Parâmetros de consulta

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo. Outro valor vira csv.

date_fromstring

Pedidos criados a partir desta data/hora, ISO 8601.

date_tostring

Pedidos criados até esta data/hora, ISO 8601. Uma data sem hora vale 00:00 daquele dia, então o dia final não entra por inteiro.

Exemplo de requisição: exportar

bash

curl "$BASE_URL/api/v1/vendor/orders/export?format=csv&date_from=2026-10-01&date_to=2026-11-01" \
  -H "Authorization: Bearer $TOKEN" -o pedidos.csv

Resposta: exportar

200Arquivo CSV

text

order_number,created_at,status,customer_email,subtotal,shipping,discount,total,payment_method
PEDIDO-20261011-0001-V1,2026-10-10 23:56:25,P,maria.souza@example.com,300.00,15.00,75.00,240.00,pix

Colunas do arquivo

order_numberstring

Número do pedido.

created_atstring

Criação, no horário de Brasília (AAAA-MM-DD HH:MM:SS).

statusstring

Letra do status (P), não o nome.

customer_emailstring

E-mail do cliente.

subtotalstring

Soma dos itens, em reais com ponto decimal (300.00), não em centavos.

shippingstring

Frete, em reais.

discountstring

Descontos, em reais.

totalstring

Total, em reais.

payment_methodstring

Código da forma de pagamento.

O nome do arquivo vem em Content-Disposition: pedidos.csv, pedidos.xlsx ou pedidos.xls.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou ele não tem o privilégio exigido.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_view_orders", "..."]}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	No detalhe: o pedido é de outro seller, é o pai, ou está fora da carteira do representante.	`{"error":"you do not have access to this order"}`
404	No detalhe: o pedido não existe.	`{"error":"order not found"}`
500	Falha ao ler. Um `id` que não é UUID também chega como `500`.	`{"error":"failed to get order","detail":"..."}`

Veja também

API atual/Referência completa/Pedidos do seller

Consultar pedidos

Lista os pedidos do seller com filtros, detalha um pedido e exporta os pedidos para CSV ou planilha.

Listar pedidos

GET/api/v1/vendor/ordersSeller

Lista os pedidos do seller

Do mais novo para o mais antigo, por padrão. Exige um privilégio de pedidos do seller (por exemplo vendor_view_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 da faixa volta a 20.

statusstring

payment_statusstring

pendingauthorizedcapturedpaidrefundedfailed

Situação do pagamento. paid é aceito como sinônimo de captured.

payment_methodstring

Código da forma de pagamento (pix, credit_card, boleto...), sem diferenciar maiúsculas.

date_fromstring

Data inicial, AAAA-MM-DD ou RFC 3339. Inclusive.

date_tostring

Data final. Com AAAA-MM-DD o dia inteiro entra; com horário, o limite é inclusivo.

min_totalinteger

Total mínimo, em centavos. Valor que não é número é ignorado.

max_totalinteger

Total máximo, em centavos. Valor que não é número é ignorado.

searchstring

Texto livre: número do pedido, e-mail, nome do cliente, CPF/CNPJ (quando o texto parece um documento) e número da ordem de compra do cliente.

sort_bystringpadrão: created_at

created_attotalorder_numberstatuscustomer_name

Campo de ordenação. Outro valor cai em created_at.

sort_dirstringpadrão: desc

ascdesc

Direção da ordenação.

has_document_typestring

Pedidos que têm anexo deste tipo (por exemplo nota_fiscal). Exige o recurso de documentos do pedido.

missing_document_typestring

Pedidos que não têm anexo deste tipo: serve para achar os pedidos sem nota fiscal.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/orders?status=processing&date_from=2026-10-01&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Pedidos do seller

json

{
  "orders": [
    {
      "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001-V1",
      "parent_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "subtotal": 30000,
      "shipping_total": 1500,
      "tax_total": 0,
      "discount_total": 7500,
      "total": 24000,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_status": "captured",
      "sales_channel": "web",
      "shipping_method_name": "Sedex",
      "customer_email": "maria.souza@example.com",
      "customer_name": "Maria Souza",
      "created_at": "2026-10-11T02:56:25.843882Z",
      "updated_at": "2026-10-11T02:56:38.131475Z",
      "status": "P",
      "status_text": "processing"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

ordersarray

Pedidos da página. Os campos principais estão abaixo; a lista completa está em Listar pedidos.

orders[].iduuid

Id do sub-pedido do seller. É o id que as outras rotas desta seção recebem.

orders[].order_numberstring

Número mostrado ao cliente. Sub-pedidos terminam em -V1, -V2...

orders[].parent_iduuid

Id do pedido pai (a compra completa do cliente).

orders[].vendor_iduuid

Seller dono do pedido: sempre o seu.

orders[].subtotalinteger

Soma dos itens, em centavos.

orders[].shipping_totalinteger

Frete, em centavos.

orders[].discount_totalinteger

Descontos, em centavos.

orders[].totalinteger

Total cobrado, em centavos.

orders[].statusstring

Letra do status (O, P, S...).

orders[].status_textstring

Código do status por extenso (pending, processing...).

orders[].payment_statusstring

Situação do pagamento.

orders[].created_atstring (RFC 3339)

Criação, em UTC.

totalinteger

Total de pedidos que casam com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página aplicado.

total_pagesinteger

Número de páginas.

Detalhar um pedido

GET/api/v1/vendor/orders/{id}Seller

Detalha um pedido do seller

Parâmetros de caminho

iduuidobrigatório

Id do sub-pedido do seller.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/vendor/orders/e148b6aa-d495-4b89-92ab-f38b5979a43f" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Pedido encontrado (trecho)

json

{
  "order": {
    "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "order_number": "PEDIDO-20261011-0001-V1",
    "parent_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "total": 24000,
    "status": "P",
    "status_text": "processing",
    "payment_method": "pix",
    "payment_status": "captured",
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza"
  },
  "items": [
    {
      "id": "020ead81-da4e-4b70-b80b-88562ba9497a",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camiseta Algodão Azul",
      "product_sku": "CAM-AZ-M",
      "unit_price": 15000,
      "quantity": 2,
      "discount": 7500,
      "total": 22500
    }
  ],
  "addresses": [
    {
      "address_type": "shipping",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11999990000"
    }
  ],
  "status_history": [
    { "old_status": "pending", "new_status": "processing", "notes": "Pagamento aprovado", "created_at": "2026-10-11T02:56:38.131475Z" }
  ]
}

Campos da resposta

orderobject

O pedido, com os campos da lista mais os detalhes (tracking_number, shipped_at, delivered_at, customer_notes, coupon_code...). Veja Consultar pedido.

itemsarray

Linhas do pedido: id (use-o como order_item_id ao criar uma remessa), product_id, product_name, product_sku, unit_price, quantity, discount e total, tudo em centavos.

addressesarray

Endereços de cobrança e entrega (address_type).

status_historyarray

Histórico de status, do mais antigo ao mais novo.

sub_ordersarray | omitted

Outros sub-pedidos do mesmo pai que são do seller. Os de outros sellers são sempre retirados.

Exportar pedidos

GET/api/v1/vendor/orders/exportSeller

Exporta os pedidos do seller em arquivo

Parâmetros de consulta

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo. Outro valor vira csv.

date_fromstring

Pedidos criados a partir desta data/hora, ISO 8601.

date_tostring

Pedidos criados até esta data/hora, ISO 8601. Uma data sem hora vale 00:00 daquele dia, então o dia final não entra por inteiro.

Exemplo de requisição: exportar

bash

curl "$BASE_URL/api/v1/vendor/orders/export?format=csv&date_from=2026-10-01&date_to=2026-11-01" \
  -H "Authorization: Bearer $TOKEN" -o pedidos.csv

Resposta: exportar

200Arquivo CSV

text

order_number,created_at,status,customer_email,subtotal,shipping,discount,total,payment_method
PEDIDO-20261011-0001-V1,2026-10-10 23:56:25,P,maria.souza@example.com,300.00,15.00,75.00,240.00,pix

Colunas do arquivo

order_numberstring

Número do pedido.

created_atstring

Criação, no horário de Brasília (AAAA-MM-DD HH:MM:SS).

statusstring

Letra do status (P), não o nome.

customer_emailstring

E-mail do cliente.

subtotalstring

Soma dos itens, em reais com ponto decimal (300.00), não em centavos.

shippingstring

Frete, em reais.

discountstring

Descontos, em reais.

totalstring

Total, em reais.

payment_methodstring

Código da forma de pagamento.

O nome do arquivo vem em Content-Disposition: pedidos.csv, pedidos.xlsx ou pedidos.xls.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou ele não tem o privilégio exigido.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_view_orders", "..."]}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	No detalhe: o pedido é de outro seller, é o pai, ou está fora da carteira do representante.	`{"error":"you do not have access to this order"}`
404	No detalhe: o pedido não existe.	`{"error":"order not found"}`
500	Falha ao ler. Um `id` que não é UUID também chega como `500`.	`{"error":"failed to get order","detail":"..."}`