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

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 (veja Sub-pedidos).

POST/api/v1/admin/ordersAdmin

Cria um pedido

Exige o privilégio manage_orders. O corpo usa UUIDs e centavos. Se customer_id for omitido, o pedido é de visitante e customer_email passa a ser obrigatório.

Corpo da requisição

customer_iduuid
Cliente cadastrado. Omita para criar pedido de visitante.
customer_emailstring
E-mail do comprador. Obrigatório quando não há customer_id.
customer_namestring
Nome do comprador.
itemsarrayobrigatório

Itens. Pelo menos um.

product_iduuidobrigatório
Produto do catálogo. Precisa estar ativo.
variation_iduuid
Variação do produto, quando ele tem.
quantitynumberobrigatório
Quantidade, maior que zero. Produto físico exige quantidade inteira.
optionsobject
Opções escolhidas (cor, tamanho), quando o produto tem.
notestring
Observação do cliente para a linha.
billing_addressobject

Endereço de cobrança. Se omitido, a plataforma usa o endereço de entrega também como cobrança.

first_namestringobrigatório
Nome.
last_namestring
Sobrenome.
address_line1stringobrigatório
Logradouro e número.
address_line2string
Complemento.
districtstring
Bairro.
citystringobrigatório
Cidade.
statestringobrigatório
UF (SP).
postal_codestringobrigatório
CEP, com ou sem hífen.
countrystringobrigatório
País (BR).
phonestring
Telefone.
cpfstring
CPF do comprador.
shipping_addressobjectobrigatório
Endereço de entrega, com os mesmos campos de billing_address. Obrigatório para pedido com produto físico: é dele que o frete é calculado.
payment_methodstringobrigatório
Código (slug) da forma de pagamento (pix, credit_card, boleto, pagamento-na-entrega...).
shipping_method_iduuid
Forma de envio escolhida. Produto físico exige uma forma de envio.
shipping_methodstring
Nome da forma de envio. Informativo; use shipping_method_id.
shipping_selectionsarray

Escolha de frete por seller, para pedidos com mais de um seller.

vendor_iduuid
Seller.
shipping_method_iduuid
Forma de envio daquele seller.
service_codestring
Código do serviço da transportadora, quando houver.
shipping_totalinteger
Ignorado: o frete é sempre recalculado pela plataforma a partir da forma de envio e do endereço.
discount_totalinteger
Desconto em centavos, gravado como enviado. Nesta rota o desconto vem de você; a plataforma não o recalcula.
tax_totalinteger
Imposto em centavos, gravado como enviado e somado ao total.
coupon_codestring
Cupom aplicado, para registro e contagem de uso.
customer_notesstring
Observação do cliente. HTML é removido.
admin_notesstring
Observação interna do pedido.
idempotency_keystring
Chave de idempotência. Reenviar a mesma chave para o mesmo cliente devolve o pedido já criado em vez de criar outro. Use sempre em integrações que podem repetir a chamada (timeout, retry).
installmentsinteger
Parcelas, para cartão de crédito. Os juros são recalculados pela plataforma.
invoiced_plan_idstring
Plano de parcelas, obrigatório quando a forma de pagamento é Boleto Faturado.

Exemplo de requisição

Resposta

201Pedido criado (trecho, com divisão por seller)

Campos da resposta

orderobject
O pedido criado (mesmos campos de Consultar pedido). Para pedido com mais de um seller é o pedido pai.
itemsarray
Linhas, com preços do catálogo em centavos.
addressesarray
Os endereços gravados no pedido.
status_historyarray
Começa com a linha order_created.
sub_ordersarray
Só aparece quando os itens são de mais de um seller (ou de um seller e da loja): um sub-pedido por seller, com o frete rateado entre eles.

Erros

StatusQuandoCorpo
400Campo obrigatório faltando{"error":"customer_id or customer_email is required"}, {"error":"at least one item is required"}, {"error":"payment_method is required"}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem o privilégio manage_orders{"error":"insufficient privileges","required":"manage_orders"}
422Forma de pagamento bloqueada para este cliente, ou recusa por regra da loja{"error":"Esta forma de pagamento não está disponível para a sua conta. Escolha outra forma de pagamento.","detail":"payment_method_not_allowed"}
500Qualquer outra recusa de negócio: produto inexistente ou inativo, quantidade inválida, estoque insuficiente, forma de envio ou CEP ausentes, forma de pagamento desconhecida{"error":"Não foi possível finalizar o pedido. Tente novamente ou entre em contato com o suporte."}
O endpoint responde 500 genérico para vários erros de dados

Quando o corpo é aceito mas o pedido não pode ser criado (produto que não existe, quantidade zero, sem forma de envio, sem CEP de entrega, forma de pagamento inexistente), POST /api/v1/admin/orders devolve 500 com uma mensagem genérica; o motivo fica apenas nos logs do servidor. Antes de enviar, confira: produto ativo e com estoque, quantity inteira, shipping_method_id válido, shipping_address completo com CEP e payment_method existente.

Idempotência evita pedido duplicado

Se a sua chamada expirar sem resposta, você não sabe se o pedido foi criado. Mande sempre um idempotency_key estável (por exemplo, o número do pedido no seu ERP): repetir a chamada devolve o mesmo pedido, com HTTP 201, em vez de criar um segundo. Sem a chave, antes de repetir a chamada procure o pedido com Listar pedidos.

Veja também

  • Consultar pedido
  • Sub-pedidos
  • Alterar o status
  • Remessas e rastreio
Anterior
Consultar pedido
Próxima
Alterar pedido
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza",
    "payment_method": "pagamento-na-entrega",
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "idempotency_key": "erp-pedido-10492",
    "items": [
      { "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "quantity": 1 },
      { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "quantity": 2 }
    ],
    "billing_address": {
      "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"
    },
    "shipping_address": {
      "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"
    },
    "admin_notes": "Venda por telefone"
  }'
json
{
  "order": {
    "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "order_number": "PEDIDO-20261011-0001",
    "customer_id": "",
    "subtotal": 190895,
    "shipping_total": 2000,
    "tax_total": 0,
    "discount_total": 0,
    "total": 192895,
    "currency": "BRL",
    "payment_method": "pagamento-na-entrega",
    "payment_method_name": "Pagamento na Entrega (COD)",
    "payment_status": "pending",
    "shipping_method": "Entrega Padrão",
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza",
    "is_guest": true,
    "guest_email": "maria.souza@example.com",
    "created_at": "2026-10-11T20:14:40.706632Z",
    "status": "O",
    "status_text": "pending"
  },
  "items": [
    {
      "id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_name": "Notebook Vintage Vermelho",
      "unit_price": 167895,
      "quantity": 1,
      "total": 167895
    },
    {
      "id": "bc30e5de-b012-4bb8-a46c-628a932e6fd4",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "addresses": [
    { "address_type": "billing", "first_name": "Maria", "city": "São Paulo", "postal_code": "01310-100" },
    { "address_type": "shipping", "first_name": "Maria", "city": "São Paulo", "postal_code": "01310-100" }
  ],
  "status_history": [
    { "old_status": "pending", "new_status": "pending", "notes": "order_created", "reason": "order_created" }
  ],
  "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,
      "total": 169654
    },
    {
      "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",
      "subtotal": 23000,
      "shipping_total": 241,
      "total": 23241
    }
  ]
}