Criação de pedidos via API

A plataforma Olist Ecommerce permite que você crie e gerencie os pedidos da sua loja via API. Com os endpoints de carrinho você simula uma compra adicionando itens, endereço e pagamento em um carrinho de compras.

Confira a seguir os passos de como criar um pedido pela API:

1. Crie um carrinho de compras;
2. Adicione itens no carrinho de compras;
3. Adicione um endereço para envio no carrinho;
4. Confira as opções de envio disponíveis para o seu carrinho de compras;
5. Selecione uma opção de envio;
6. Finalize o pedido.

Após o fechamento da compra, você pode conferir o pedido criado.

1. Criar um carrinho de compras

Crie um carrinho de compras utilizando o método POST no endpoint de carrinhos:

curl --request POST \
     --url https://api.vnda.com.br/api/v2/carts \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Token' \
     --header 'content-type: application/json'

No response body, confira e copie o parâmetro id do carrinho:

{
  "agent": null,
  "billing_address_id": null,
  "channel": "ecommerce",
  "client_id": null,
  "code": "5B8A582BC3",
  "coupon_code": null,
  "discount": null,
  "discount_price": 0,
  "extra": {},
  "id": 182059,
  "installments": [
    0
  ],
  "items": [],
  "items_count": 0,
  "shipping_address_id": null,
  "shipping_method": null,
  "shipping_methods": [],
  "shipping_price": 0,
  "subtotal": 0,
  "subtotal_discount": 0,
  "token": "DAonvCCymFzuZyYZBN9CCi8GXYpzsdsdzdm7",
  "total": 0,
  "total_discount": 0,
  "total_for_deposit": 0,
  "total_for_slip": 0,
  "total_for_pix": 0,
  "updated_at": "2022-12-07T11:31:42.834-03:00",
  "rebate_token": null,
  "rebate_discount": 0,
  "user_id": null,
  "handling_days": 0
}

Note que no exemplo o id do carrinho é 182059.

2. Adicionar itens no carrinho

Com um carrinho criado, você precisa adicionar os itens do seu carrinho. Para isso, utilize o método POST no endpoint de itens no carrinho. Para requisição:

• O cart_id deve ser o id do carrinho criado no passo anterior;
• Os parâmetros sku e quantity são obrigatórios para adicionar o item no carrinho. Para adicionar um item no carrinho você precisa conferir se há disponibilidade do SKU em estoque e se o produto está ativo.

curl --request POST \
     --url https://api.vnda.com.br/api/v2/carts/182081/items \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Token' \
     --header 'content-type: application/json' \
     --data '
{
     "sku": "15976899-34x",
     "quantity": 3
}

📘

Para incluir itens em massa no carrinho, utilize o endpoint de itens em massa no carrinho.

3. Adicionar um endereço de entrega

Com os itens no carrinho você deve incluir um endereço de entrega. Para incluir um endereço no carrinho, utilize o método POST no endpoint de endereço de entrega no carrinho. Adicione os parâmetros no corpo com as informações para o envio:

curl --request POST \
     --url https://api.vnda.com.br/api/v2/carts/182081/shipping_address \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token \
     --header 'content-type: application/json' \
     --data
{
     "first_name": Jess,
     "last_name": Alves,
     "email": teste@test.com,
     "zip":24210520,
     "street_number": 111
}

Response body:

{
  "id": 183532,
  "first_name": Jess,
  "last_name": Alves,
  "company_name": null,
  "email": teste@test.com,
  "documents": {},
  "street_name": "Rua Fagundes Varela",
  "street_number": 111,
  "complement": null,
  "neighborhood": "Ingá",
  "first_phone_area": null,
  "first_phone": null,
  "second_phone_area": null,
  "second_phone": null,
  "reference": null,
  "zip": "24210520",
  "city": "Niterói",
  "state": "RJ"
}

🚧

Para criar um pedido, na etapa de pagamento os dados do endereço para envio precisam estar completos (nome, sobrenome, e-mail e número da residência).

4. Listar as opções de envio disponíveis

Confira as opções de envio disponíveis para o endereço pelo endpoint de cálculo de envio. Utilize o método GET no endpoint e utilize o código identificador do carrinho no cart_id.

curl --request GET \
     --url https://api.vnda.com.br/api/v2/carts/182059/shipping_methods \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Token'

response body:

{
  "": [
    {
      "name": "Normal",
      "value": "normal",
      "price": 0,
      "description": "Prazo de até 11 dias corridos para a entrega do pedido",
      "delivery_days": 11,
      "fulfillment_company": null,
      "value_needed_to_discount": null,
      "shipping_method_id": 188255,
      "notice": "",
      "countries": null
    },
    {
      "name": "Retirar na loja",
      "value": "retirar-na-loja",
      "price": 0,
      "description": "Disponível para retirada em 4 dias (19/12/2022)",
      "delivery_days": 4,
      "fulfillment_company": null,
      "value_needed_to_discount": null,
      "shipping_method_id": 196220,
      "notice": "",
      "countries": null
    },
    {
      "name": "Entrega agendada",
      "value": "local",
      "price": 10,
      "description": "Prazo de 1 dia corrido para a entrega do pedido",
      "delivery_days": 1,
      "fulfillment_company": null,
      "value_needed_to_discount": null,
      "shipping_method_id": 182305,
      "notice": "",
      "countries": null
    }
  ]
}

Escolha no response body qual método de envio você deseja. Você deverá utilizar o parâmetro value do método de envio escolhido no próximo passo.

5. Selecionar uma opção de entrega

Você deve selecionar uma opção de envio entre as opções disponíveis para o seu carrinho. Para isso, use o método PATCH no endpoint de métodos de envio:

• Utilize o parâmetro value o response body da requisição anterior no parâmetro value_method;
• Utilize o código identificador do carrinho no card_id

Seguindo nosso exemplo, escolhemos o método de envio Entrega agendada. Nesse método de envio o value é local:

curl --request PATCH \
     --url https://api.vnda.com.br/api/v2/carts/182059/shipping_methods/local \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Token' \
     --header 'content-type: application/json'

A resposta dessa requisição deve ser um retorno 204 com no content.

6. Finalizar um pedido

Para que um carrinho gere um pedido é preciso adicionar um pagamento ao carrinho. Um pedido é criado após selecionado a forma de pagamento do carrinho. Para adicionar um pagamento no carrinho, use o método POST no endpoint de pagamento de carrinho:

curl --request POST \
     --url https://api.vnda.com.br/api/v2/carts/182059/payment \
     --header 'X-Shop-Host: www.nomedaloja.com.br' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Token \
     --header 'content-type: application/json' \
     --data '
{
     "payment_method": "pix"
}

📘

O método de pagamento disponível no endpoint está relacionado aos métodos de pagamento suportados pela loja.

O resultado dessa requisição deve ser o retorno 301 com os dados do pedido criado.

Consultar pedidos

Após criação do pedido, consulte os detalhes do pedido usando o método GET no endpoint de pedidos.