VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Pedidos: rotas sem versão e app do seller

Coleção de pedidos sem versão

Lista e cria pedidos em /api/orders, a forma da API 1.0 sem o prefixo de versão, com ids decimais; inclui as rotas que só respondem 405.

/api/orders é o mesmo recurso de /api/v1.0/orders, escrito como a Venddor 1.0 o expunha. Quem a usa recebe e envia ids decimais em string ("1794666195") no lugar dos UUID. Os parâmetros, os campos e as regras são os das páginas Listar pedidos e Criar pedido; esta página repete o essencial e descreve o que muda nesta forma.

Todas as rotas exigem um administrador (HTTP Basic e-mail:chave_de_api ou Bearer <JWT>).

Para integrações novas

Use GET e POST /api/v1.0/orders, que devolvem UUID. Esta forma sem versão é mantida para conectores já escritos.

GET/api/ordersAdmin

Listar pedidos, forma sem versão (ids decimais)

Lista paginada, sempre do pedido mais novo para o mais antigo. Mesmo tratamento de GET /api/v1.0/orders.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1. Valor inválido é ignorado.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 100. Acima de 100 volta ao padrão da plataforma (20).
statusstring
Filtra por status. Mande a letra (O, P, S, C, I, R...). Nomes longos passam por uma tabela antiga e podem filtrar outro status.
user_idstring
Somente pedidos deste cliente, id decimal (ou UUID).
company_idstring
Somente pedidos deste seller, id decimal (ou UUID).
order_idstring
Busca por texto no número do pedido, no e-mail e no nome do cliente. Não é igualdade de id.
periodstring
todaythis_weekthis_monthlast_monththis_yearlast_year
Atalho de período, no fuso do servidor.
time_frominteger
Início do período, Unix timestamp em segundos. Só o dia conta. Sobrescreve period.
time_tointeger
Fim do período, Unix timestamp em segundos. O dia entra por inteiro.
POST/api/ordersAdmin

Criar um pedido, forma sem versão (ids decimais)

Cria um pedido em nome de um cliente. Mesmo tratamento de POST /api/v1.0/orders: o preço vem do catálogo, o estoque é baixado e o frete é recalculado a partir do CEP de entrega. user_id e product_id podem ser decimais.

Corpo da requisição

user_idstringobrigatório
Cliente que faz o pedido, id decimal (ou UUID). O cliente precisa existir.
payment_idstringobrigatório
Código (slug) da forma de pagamento, por exemplo pix ou pagamento-na-entrega. Não é traduzido: continua sendo o código.
productsarrayobrigatório

Itens do pedido, pelo menos um.

product_idstringobrigatório
Id do produto, decimal (ou UUID).
amountintegerpadrão: 1
Quantidade, inteiro maior ou igual a 1.
pricestring
Aceito e ignorado: o preço vem do catálogo.
statusstring
Status inicial, em letra de uma tabela antiga: O, P, C, D, F, I, B. Outro valor vira pendente.
user_dataobject
Dados do cliente e endereços (firstname, lastname, email, b_* de cobrança e s_* de entrega). Envie sempre o CEP de entrega (s_zipcode): o frete é calculado a partir dele.
customer_emailstring
E-mail do pedido. Tem prioridade sobre user_data.email.
customer_namestring
Nome do pedido.
shipping_idsarray
Só informativo: não escolhe o frete.
coupon_codesarray
Só informativo: não recalcula o preço.
PUT/api/ordersAdmin

Não executa nada: responde 405 (falta o id)

Existe só para dar uma resposta clara a quem tenta alterar sem informar o pedido. A resposta é 405 Method Not Allowed, cabeçalho Allow: GET, POST e corpo vazio. Para alterar um pedido use PUT /api/orders/{id}.

PUT/api/v1.0/ordersAdmin

Não executa nada: responde 405 (falta o id), forma com versão

Igual a PUT /api/orders: 405, Allow: GET, POST, corpo vazio. Para alterar use PUT /api/v1.0/orders/{id}.

Exemplo de requisição

bash
curl "$BASE_URL/api/orders?items_per_page=10&status=O" -u "$EMAIL:$API_KEY"

curl -X POST "$BASE_URL/api/orders" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "642412737",
    "payment_id": "pagamento-na-entrega",
    "products": [{ "product_id": "592384622", "amount": 2 }],
    "user_data": {
      "firstname": "Maria", "lastname": "Souza", "email": "maria.souza@example.com",
      "s_address": "Avenida Paulista, 1000", "s_city": "São Paulo", "s_state": "SP",
      "s_zipcode": "01310-100", "s_country": "BR"
    }
  }'

Resposta

200Lista de pedidos
json
{
  "orders": [
    {
      "order_id": "1794666195",
      "order_number": "PEDIDO-20261011-0009",
      "is_parent_order": "N",
      "parent_order_id": "",
      "suborder_ids": [],
      "user_id": "642412737",
      "company_id": "496868694",
      "email": "maria.souza@example.com",
      "status": "C",
      "timestamp": 1791752125,
      "currency": "BRL",
      "lang_code": "pt-BR",
      "subtotal": "49.90",
      "discount": "7.24",
      "shipping_cost": "10.00",
      "shipping_id": "1342177280",
      "shipping_method_name": "Entrega Padrão",
      "shipping_tax": "0.00",
      "tax_subtotal": "0.00",
      "payment_tax": "0.00",
      "total": "52.66",
      "payment_method": { "payment": "pix", "payment_id": "pix" },
      "payment_method_name": "pix",
      "coupon_codes": [],
      "promotion_ids": [],
      "notes": "",
      "ip_address": "127.0.0.1"
    }
  ],
  "params": { "items_per_page": 10, "page": 1, "total_items": 44001 }
}
201Pedido criado
json
{
  "order_id": "1794700001",
  "order_data": {
    "order_id": "1794700001",
    "order_number": "PEDIDO-20261011-0010",
    "status": "O",
    "total": "240.00",
    "subtotal": "230.00",
    "shipping_cost": "10.00",
    "user_id": "642412737",
    "products": [
      { "item_id": "607887120", "product_id": "592384622", "product": "Doc Bulk Caneca", "price": "115.00", "amount": 2, "subtotal": "230.00", "total": "230.00" }
    ],
    "suborder_ids": []
  }
}

Campos da resposta

orders[].order_idstring
Id do pedido, decimal em string. Use-o nas demais rotas de /api/orders/{id}.
orders[].order_numberstring
Número legível do pedido (não é um id; não serve como {id}).
orders[].is_parent_orderstring
YN
Y quando é o pedido pai de uma compra de vários sellers (veja Sub-pedidos).
orders[].statusstring
Letra do status no cadastro da loja.
orders[].timestampinteger
Criação do pedido, Unix timestamp em segundos.
orders[].subtotalstring
Soma dos itens, string decimal.
orders[].discountstring
Desconto total, string decimal.
orders[].shipping_coststring
Frete, string decimal.
orders[].totalstring
Total a pagar, string decimal.
orders[].payment_methodobject
payment (nome) e payment_id (código da forma de pagamento; não é decimal).
paramsobject
Paginação: page, items_per_page e total_items (total em todas as páginas).
order_idstring
(Criação) Id do pedido criado.
order_dataobject
(Criação) O pedido completo, no formato de Consultar pedido.

Erros

StatusQuandoCorpo
400user_id ou company_id na consulta em formato de id inválido{"message":"Invalid id","status":400}
400Campo obrigatório faltando na criação{"message":"user_id is required","status":400}, {"message":"products is required","status":400} ou {"message":"payment_id is required","status":400}
400amount inválido{"message":"invalid_quantity: products.amount must be a positive whole number","status":400}
400Produto inexistente ou sem frete calculável{"message":"shipping_service_unavailable: a shipping method is required for physical products","status":400}
401Sem credenciais, chave inválida ou token expirado{"message":"Invalid credentials","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
404user_id ou company_id decimal que não corresponde a nenhum registro{"message":"Not found","status":404}
405PUT /api/orders ou PUT /api/v1.0/orderscorpo vazio, cabeçalho Allow: GET, POST
Sem o CEP de entrega o pedido não nasce

O frete é recalculado a partir de s_zipcode. Sem ele, ou com um user_id ou payment_id que não existe, a criação responde 400 shipping_service_unavailable, sem dizer qual dos três está errado. O pedido criado também não aceita shipping_ids: o frete é o calculado.

Veja também

  • Um pedido
  • Listar pedidos
  • Criar pedido
Anterior
Pedidos: rotas sem versão e app do seller
Próxima
Um pedido sem versão
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também