Pedidos (REST)

Os pedidos são o centro de qualquer plataforma de e-commerce. A API de pedidos permite gerenciar os pedidos de clientes da sua loja Venddor: você pode criar, consultar, atualizar e excluir pedidos. Um pedido é o registro de uma compra, com o cliente, os produtos, o pagamento e os dados de entrega.

Todas as chamadas desta página usam as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL). Por isso os endpoints abaixo aparecem como $BASE_URL/api/orders.

Como funciona

Os pedidos costumam seguir este fluxo dentro da Venddor.

1. O cliente monta o carrinho
   O cliente adiciona produtos ao carrinho e vai para o checkout.
2. O cliente envia o pedido
   O cliente envia o pedido com as informações de entrega e de pagamento.
3. O pedido é criado
   O pedido é criado no sistema com o status "Aberto".
4. O pagamento é processado
   Se houver pagamento, ele é processado e o status do pedido é atualizado de acordo com o resultado.
5. O pedido é atendido
   O pedido é atendido e enviado, e é marcado como concluído quando chega ao cliente.

Códigos de status do pedido

A visão geral de pedidos lista estes códigos de status.

Conceitos principais

O que a listagem aceita

A visão geral descreve o GET /orders com estes parâmetros de consulta. Todos são opcionais.

A referência completa de paginação, ordenação e filtros está em Paginação, ordenação e filtros.

O pedido que você recebe

O GET /orders/{order_id} retorna as informações detalhadas de um pedido. A visão geral mostra este exemplo, com os detalhes do pagamento, os produtos e o endereço de entrega:

{
  "order_id": "12345",
  "status": "P",
  "user_id": "42",
  "timestamp": "1618500452",
  "payment": {
    "payment_id": "PM12345",
    "payment_method": "credit_card",
    "status": "paid"
  },
  "products": [
    {
      "item_id": "456",
      "product_id": "101",
      "product_code": "TSH-BLK-L",
      "product_name": "Black T-shirt",
      "price": "19.99",
      "amount": "2"
    },
    {
      "item_id": "457",
      "product_id": "204",
      "product_code": "CAP-RED",
      "product_name": "Red Cap",
      "price": "12.50",
      "amount": "1"
    }
  ],
  "shipping_address": {
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "country": "US",
    "zipcode": "12345"
  },
  "shipping_method": "standard",
  "total": "52.48"
}

A referência campo a campo do objeto de pedido, com os formatos devolvidos pela consulta, está em Obter um pedido.

Criar, atualizar e excluir

Para criar um pedido (POST /orders), a visão geral pede estes parâmetros, todos obrigatórios: user_id (integer, o cliente que faz o pedido), products (array com os produtos pedidos), shipping_address (objeto com o endereço de entrega), shipping_method (string, a forma de envio escolhida) e payment_method (string, a forma de pagamento escolhida). A página Criar um pedido traz a referência completa dos parâmetros.

Para atualizar um pedido (PUT /orders/{order_id}) você pode alterar qualquer propriedade do pedido e inclui apenas os campos que quer mudar.

Para excluir um pedido (DELETE /orders/{order_id}) você envia o id do pedido no caminho.

Endpoints

Erros comuns

• Tentar definir o status ao criar um pedido. Um pedido novo é sempre O (Aberto); mude o status depois, com um PUT.
• Enviar num PUT apenas os produtos que você quer acrescentar. O objeto products precisa conter todos os produtos que devem continuar no pedido, e o mesmo vale para as variantes de opções dos produtos.
• Usar o id do produto como chave de products quando o mesmo produto aparece com opções diferentes. Use números aleatórios como chaves, como descreve Criar um pedido.
• Esperar um e-mail quando o status muda. Mudar o status pela API não envia notificação, a menos que você ative as flags notify_*, veja Atualizar um pedido.
• Excluir um pedido que você só queria encerrar. A exclusão não pode ser desfeita, então atualize o status.

Próximos passos