Criar pedido

Cria um pedido em nome de um cliente, com itens, endereços e forma de pagamento, como um ERP, um PDV ou o atendimento fazem.

Use esta operação quando o pedido não nasce no checkout da loja: um representante digitou a venda por telefone, o ERP gera o pedido a partir de uma proposta, ou um sistema externo precisa registrar uma compra. O cliente final continua comprando pelo checkout da loja; essa rota é para integrações e para a equipe da loja.

Ao criar, a plataforma recalcula os preços a partir do catálogo, baixa o estoque, grava o histórico de status e dispara o evento de pedido criado (e-mails e demais reações configuradas na loja). Se os itens são de sellers diferentes, o pedido é dividido em um pedido pai e um sub-pedido por seller (o pai vem com is_parent_order e os ids dos filhos em suborder_ids).

POST/api/v1.0/ordersAdmin

Criar um pedido

Autenticação: HTTP Basic (e-mail:chave_de_api) de um administrador, ou Authorization: Bearer <JWT>. Também responde em /api/orders; nessa forma, user_id e product_id podem ser enviados como ids decimais.

Corpo da requisição

user_idstringobrigatório

Id do cliente que faz o pedido. O cliente precisa existir.

payment_idstringobrigatório

Código (slug) da forma de pagamento, por exemplo pix, boleto ou pagamento-na-entrega. Veja as formas cadastradas na loja.

productsarrayobrigatório

Itens do pedido. Pelo menos um.

product_idstringobrigatório

Id do produto (UUID, ou decimal em /api/orders).

amountintegerpadrão: 1

Quantidade, inteiro maior ou igual a 1. Se omitido vale 1. 0, negativo, decimal ou null são recusados.

pricestring

Aceito por compatibilidade, mas ignorado: o preço vem sempre do catálogo.

statusstring

Status inicial, em letra. Só uma tabela antiga é entendida aqui: O pending, P processing, C completed, D refunded, F failed, I cancelled, B on_hold. Qualquer outro valor vira pending. O padrão (pendente) é o que você quer na maioria dos casos.

user_dataobject

Dados do cliente e endereços. Envie sempre, principalmente o CEP de entrega.

firstnamestring

Nome.

lastnamestring

Sobrenome.

emailstring

E-mail do pedido. Se faltar (e customer_email também), o pedido é gravado com api@venddor.com.br.

b_addressstring

Endereço de cobrança (logradouro e número).

b_citystring

Cidade de cobrança.

b_statestring

UF de cobrança.

b_zipcodestring

CEP de cobrança.

b_countrystring

País de cobrança (BR).

s_addressstring

Endereço de entrega (logradouro e número).

s_citystring

Cidade de entrega.

s_statestring

UF de entrega.

s_zipcodestring

CEP de entrega. É a partir dele que o frete é calculado.

s_countrystring

País de entrega (BR).

customer_emailstring

E-mail do pedido. Tem prioridade sobre user_data.email.

customer_namestring

Nome do pedido. Se faltar, usa user_data.firstname e lastname; sem eles, grava API Customer.

shipping_idsarray

Ids de formas de envio. Ficam apenas registrados como informação no pedido: não escolhem o frete.

coupon_codesarray

Códigos de cupom. Ficam registrados no pedido (aparecem em coupon_codes), mas não recalculam o preço.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/orders" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "payment_id": "pagamento-na-entrega",
    "products": [
      { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "amount": 2 }
    ],
    "user_data": {
      "firstname": "Maria", "lastname": "Souza", "email": "maria.souza@example.com",
      "b_address": "Avenida Paulista, 1000", "b_city": "São Paulo", "b_state": "SP",
      "b_zipcode": "01310-100", "b_country": "BR",
      "s_address": "Avenida Paulista, 1000", "s_city": "São Paulo", "s_state": "SP",
      "s_zipcode": "01310-100", "s_country": "BR"
    }
  }'

Resposta

201Pedido criado

json

{
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "order_data": {
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "is_parent_order": "N",
    "parent_order_id": "",
    "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "total": "240.00",
    "subtotal": "230.00",
    "discount": "0.00",
    "shipping_cost": "10.00",
    "tax_subtotal": "0.00",
    "payment_tax": "0.00",
    "shipping_tax": "0.00",
    "status": "O",
    "timestamp": 1791749845,
    "order_number": "PEDIDO-20261011-0002",
    "email": "maria.souza@example.com",
    "currency": "BRL",
    "lang_code": "pt-BR",
    "payment_method": { "payment": "pagamento-na-entrega", "payment_id": "pagamento-na-entrega" },
    "products": [
      {
        "item_id": "dd60b2a2-291e-4d06-b392-f5626075f919",
        "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
        "product_code": "SD-002373",
        "product": "Notebook Slim Rosa",
        "price": "115.00",
        "amount": 2,
        "discount": "0.00",
        "subtotal": "230.00",
        "total": "230.00"
      }
    ],
    "payment_info": { "payment_method": "pagamento-na-entrega", "payment_status": "pending" },
    "coupon_codes": [],
    "promotion_ids": [],
    "suborder_ids": []
  }
}

Campos da resposta

order_idstring

Id do pedido criado (UUID; decimal em /api/orders). Guarde-o: é a chave para todas as outras operações.

order_dataobject

O pedido no formato de Consultar pedido.

suborder_idsarray

Só aparece quando o pedido foi dividido por seller: ids dos sub-pedidos.

suborders_dataarray

Só aparece junto com suborder_ids: o resumo de cada sub-pedido.

Erros

Status	Quando	Corpo
400	Campo obrigatório faltando	`{"message":"user_id is required","status":400}`, `{"message":"products is required","status":400}`, `{"message":"payment_id is required","status":400}`
400	`amount` inválido	`{"message":"invalid_quantity: products.amount must be a positive whole number","status":400}`
400	Produto inexistente ou sem frete calculável	`{"message":"shipping_data_incomplete: product ... is unavailable ...","status":400}` ou `{"message":"shipping_service_unavailable: a shipping method is required for physical products","status":400}`
401	Sem credenciais ou chave de API inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também