Pedidos

Gerencie os pedidos da loja. Crie pedidos diretamente via API (para integrações com ERPs) ou consulte/atualize pedidos existentes.

Listar pedidos

GET /api/v1/orders

Query parameters

Parâmetro	Tipo	Descrição
status	string	Filtrar por status do pedido
payment_status	string	Filtrar por status de pagamento
customer_id	integer	Filtrar por cliente
order_number	string	Filtrar por número do pedido
date_from	date	Pedidos a partir desta data (YYYY-MM-DD)
date_to	date	Pedidos até esta data (YYYY-MM-DD)
sort	string	Campo de ordenação (padrão: created_at)
direction	string	asc ou desc (padrão: desc)
per_page	integer	Itens por página (máx: 100, padrão: 25)

Exemplo

curl -X GET "https://sualoja.com.br/api/v1/orders?status=processing&date_from=2026-03-01" \
  -H "X-API-Key: SUA_CHAVE"

Resposta

{
  "data": [
    {
      "id": 42,
      "order_number": "2026-00042",
      "customer": {
        "id": 5,
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "guest_name": null,
      "guest_email": null,
      "status": "processing",
      "payment_status": "paid",
      "payment_method": "pix",
      "items": [
        {
          "id": 100,
          "product_id": 1,
          "variant_id": 10,
          "product_name": "Camiseta Preta",
          "variant_label": "P / Preto",
          "sku": "CAM-001-P",
          "quantity": 2,
          "unit_price": 59.90,
          "total": 119.80
        }
      ],
      "shipping": {
        "method": "PAC",
        "cost": 14.90,
        "days": 8,
        "tracking_code": "BR123456789BR",
        "tracking_url": "https://rastreamento.correios.com.br/...",
        "address": {
          "name": "João Silva",
          "phone": "(11) 98765-4321",
          "zip": "01001-000",
          "street": "Rua A",
          "number": "100",
          "complement": null,
          "district": "Centro",
          "city": "São Paulo",
          "state": "SP"
        }
      },
      "subtotal": 119.80,
      "discount": 10.00,
      "pix_discount": 0,
      "shipping_cost": 14.90,
      "total": 124.70,
      "coupon_code": "DESCONTO10",
      "notes": null,
      "paid_at": "2026-03-15T10:30:00Z",
      "shipped_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "created_at": "2026-03-15T10:25:00Z",
      "updated_at": "2026-03-15T10:30:00Z"
    }
  ]
}

Buscar pedido

GET /api/v1/orders/{id}

Retorna o pedido completo com cliente, itens e eventos.

Criar pedido

POST /api/v1/orders

Cria um pedido diretamente, sem passar pelo carrinho. Ideal para integrações com ERPs que precisam registrar pedidos de outros canais.

Pedido de cliente cadastrado ou visitante

Envie customer_id para vincular a um cliente cadastrado, ou envie guest_name e guest_email para um pedido de visitante.

Campos

Campo	Tipo	Obrigatório	Descrição
customer_id	integer		ID do cliente (obrigatório se não enviar guest_*)
guest_name	string		Nome do visitante
guest_email	string		E-mail do visitante
guest_phone	string		Telefone do visitante
payment_method	string	✅	pix, credit_card ou boleto
items	array	✅	Lista de itens (mínimo 1)
items[].product_id	integer	✅	ID do produto
items[].variant_id	integer		ID da variante
items[].quantity	integer	✅	Quantidade (mínimo: 1)
items[].unit_price	number	✅	Preço unitário
shipping_name	string	✅	Nome do destinatário
shipping_zip	string	✅	CEP
shipping_street	string	✅	Rua
shipping_number	string	✅	Número
shipping_complement	string		Complemento
shipping_district	string	✅	Bairro
shipping_city	string	✅	Cidade
shipping_state	string	✅	Estado (UF)
shipping_phone	string		Telefone para entrega
shipping_method	string	✅	Método de envio (ex: "PAC", "SEDEX")
shipping_cost	number	✅	Custo do frete
shipping_days	integer		Prazo em dias
subtotal	number	✅	Subtotal dos itens
discount	number		Desconto aplicado
total	number	✅	Valor total do pedido
notes	string		Observações do pedido

Exemplo

curl -X POST https://sualoja.com.br/api/v1/orders \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 5,
    "payment_method": "pix",
    "items": [
      {
        "product_id": 1,
        "variant_id": 10,
        "quantity": 2,
        "unit_price": 59.90
      }
    ],
    "shipping_name": "João Silva",
    "shipping_zip": "01001-000",
    "shipping_street": "Rua A",
    "shipping_number": "100",
    "shipping_district": "Centro",
    "shipping_city": "São Paulo",
    "shipping_state": "SP",
    "shipping_method": "PAC",
    "shipping_cost": 14.90,
    "shipping_days": 8,
    "subtotal": 119.80,
    "discount": 10.00,
    "total": 124.70
  }'

Resposta 201 Created

O pedido é criado com status: pending e payment_status: pending. O evento order.created é disparado automaticamente (webhooks).

Atualizar pedido

PUT /api/v1/orders/{id}

Atualiza status, rastreamento e observações de um pedido. Não permite alterar itens.

Campos

Campo	Tipo	Descrição
status	string	Novo status do pedido
payment_status	string	Novo status de pagamento
tracking_code	string	Código de rastreamento
tracking_url	string	URL de rastreamento
notes	string	Observações
shipped_at	datetime	Data de envio
delivered_at	datetime	Data de entrega

Timestamps automáticos

• Ao alterar status para shipped, o campo shipped_at é preenchido automaticamente (se não enviado).
• Ao alterar status para delivered, o campo delivered_at é preenchido automaticamente (se não enviado).

Exemplo — marcar como enviado

curl -X PUT https://sualoja.com.br/api/v1/orders/42 \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "tracking_code": "BR123456789BR",
    "tracking_url": "https://rastreamento.correios.com.br/..."
  }'

Status do pedido

Status	Descrição
pending	Aguardando pagamento
processing	Pagamento confirmado, preparando
paid	Pago
shipped	Enviado
delivered	Entregue
cancelled	Cancelado
refunded	Reembolsado

Status de pagamento

Status	Descrição
pending	Aguardando
paid	Pago
failed	Falhou
refunded	Reembolsado

Métodos de pagamento

Método	Descrição
pix	PIX
credit_card	Cartão de crédito
boleto	Boleto bancário