Criar um pedido

Este endpoint cria pedidos por programa na sua loja Venddor. O pedido pode ser criado em nome de um usuário existente ou como uma compra de visitante (guest checkout). Use-o para trazer pedidos de outro sistema ou para registrar um pedido feito por telefone.

O pedido é criado com o status O (Aberto). Você só consegue mudar o status ao atualizar um pedido existente, veja Atualizar um pedido. Os preços dos produtos vêm do cadastro dos produtos, não do JSON que você envia.

Envie os parâmetros no corpo da requisição HTTP, de acordo com o Content-Type que você informar.

Produtos: duas formas de estruturar

Os preços dos produtos vêm do cadastro dos produtos, não do JSON. Um desconto num produto não pode ser informado no POST, apenas num PUT posterior.

Forma 1: ids de produto como chaves

"products": {
  "241": {
    "amount": "1",
    "product_options": {
      "12": "44",
      "13": "48"
    }
  }
}

Forma 2: números aleatórios como chaves

"products": {
  "1": {
    "product_id": "12",
    "amount": "1",
    "product_options": {
      "3": "12",
      "4": "17"
    }
  },
  "2": {
    "product_id": "12",
    "amount": "2",
    "product_options": {
      "3": "15",
      "4": "19"
    }
  }
}

Exemplos de requisição

Criar um pedido para um usuário existente

Esta requisição cria um pedido feito pelo cliente com user_id=3, usando a forma de envio shipping_id=1 e a forma de pagamento payment_id=2. O pedido contém um produto com product_id=12 e dois produtos com product_id=13.

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/orders/" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "3",
  "shipping_id": "1",
  "payment_id": "2",
  "products": {
    "1": {
      "product_id": "12",
      "amount": "1"
    },
    "2": {
      "product_id": "13",
      "amount": "2"
    }
  }
}'

Criar um pedido para um visitante

O visitante precisa informar o endereço e os dados de contato no checkout. Por isso você deve incluir o objeto user_data ao criar um pedido para um visitante.

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/orders/" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "0",
  "payment_id": "2",
  "shipping_id": "1",
  "products": {
    "1": {
      "product_id": "12",
      "amount": "1"
    },
    "2": {
      "product_id": "13",
      "amount": "2"
    }
  },
  "user_data": {
    "email": "guest@example.com",
    "firstname": "Guest",
    "lastname": "Guest",
    "s_firstname": "Guest",
    "s_lastname": "Guest",
    "s_country": "US",
    "s_city": "Boston",
    "s_state": "MA",
    "s_zipcode": "02125",
    "s_address": "44 Main street",
    "b_firstname": "Guest",
    "b_lastname": "Guest",
    "b_country": "US",
    "b_city": "Boston",
    "b_state": "MA",
    "b_zipcode": "02125",
    "b_address": "44 Main street"
  }
}'

Formato da resposta

Resposta de sucesso (201 Created)

{
  "order_id": "98"
}

Resposta de erro (400 Bad Request)

Retornada quando o pedido não pôde ser criado por causa de parâmetros inválidos ou de outros problemas.

Notas de implementação

Ao criar pedidos, considere estas boas práticas.

• Valide a disponibilidade dos produtos antes de criar um pedido, para evitar problemas de estoque.
• Confira se as formas de envio e de pagamento informadas estão ativas e disponíveis.
• Em pedidos de visitantes, informe dados de usuário completos e válidos para que o pedido seja processado com sucesso.
• Ao trabalhar com opções, use os ids de opção e de variante corretos para os produtos.
• Teste a sua implementação com pedidos pequenos antes de processar pedidos grandes ou complexos.