Desenvolvedores

Guia de checkout

O checkout é retomável e roda em cima do carrinho: identificação → entrega → conclusão com pagamento. O estado vive no cookie httpOnly do carrinho; nos exemplos abaixo o curl faz o papel do seu BFF, guardando os cookies em cookies.txt.

1. Carrinho

terminal

# O cookie do carrinho vem no Set-Cookie da primeira chamada: guarde-o (-c/-b)
curl -c cookies.txt "https://SUA-LOJA.meweb.com.br/api/v1/storefront/cart"

# Adicionar uma variante
curl -b cookies.txt -c cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/cart/items" \
  -H "Content-Type: application/json" \
  -d '{ "variantId": "01J0...", "quantity": 1 }'

Toda rota de carrinho devolve o carrinho completo atualizado (itens, totais em centavos, etapas do checkout já preenchidas).

2. Cupom e cartão-presente (opcional)

terminal

curl -b cookies.txt -c cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/cart/discount-code" \
  -H "Content-Type: application/json" \
  -d '{ "code": "BEMVINDO10" }'
# Cupom inválido NÃO é erro HTTP: veja "discountError" no carrinho retornado

3. Identificação

terminal

curl -b cookies.txt -c cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/identification" \
  -H "Content-Type: application/json" \
  -d '{ "email": "cliente@example.com", "firstName": "Ana", "lastName": "Pereira" }'

4. Entrega

terminal

# 1) Métodos disponíveis para o CEP
curl -b cookies.txt "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/shipping-methods?cep=01310-100"

# 2) Endereço + método escolhido
curl -b cookies.txt -c cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/shipping" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "recipientName": "Ana Pereira", "cep": "01310-100",
      "street": "Av. Paulista", "number": "1000",
      "district": "Bela Vista", "city": "São Paulo", "state": "SP"
    },
    "shippingMethodId": "01J0..."
  }'

Carrinho só com cartões-presente (giftCardOnly) pula a etapa de entrega.

5. Pagamento

terminal

curl "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/payment-config"
# → métodos ativos (pix | credit_card | boleto), chave pública p/ tokenizar cartão e parcelamento

Pix

curl -b cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/complete" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "method": "pix" }'
# → { "data": { "orderId": "...", "orderNumber": 1042, "status": "pending_payment",
#     "payment": { "method": "pix", "pixQrCode": "000201...", ... } } }

Cartão de crédito

# Cartão: tokenize client-side com a publicKey do payment-config; dados crus nunca passam pelo seu servidor
curl -b cookies.txt -X POST "https://SUA-LOJA.meweb.com.br/api/v1/storefront/checkout/complete" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "method": "credit_card", "cardToken": "tok_...", "installments": 3 }'

O header Idempotency-Key é obrigatório: reenvio com a mesma chave devolve a resposta original (rede instável não duplica pedido); mesma chave com payload diferente → 409.
A conclusão revalida preço e estoque. Se algo mudou desde que o item entrou no carrinho, a API responde 422 com as divergências; mostre ao cliente e reenvie com acknowledgeChanges: true.
Esta rota tem limite de 10 req/min por IP.

6. Confirmação

terminal

# O cookie do carrinho é limpo no sucesso: a confirmação usa orderId + e-mail
curl "https://SUA-LOJA.meweb.com.br/api/v1/storefront/orders/01J0.../confirmation?email=cliente@example.com"

O pagamento é confirmado de forma assíncrona (o provedor notifica a plataforma). Sua tela de obrigado pode fazer polling desta rota até status sair de pending_payment. Cliente logado também enxerga o pedido em /storefront/account/orders.

Schemas e campos de cada rota na referência.