Carrinho

Visão Geral

O carrinho de compras é um dos principais componentes de um e-commerce.

Ele permite que o cliente adicione e gerencie múltiplos produtos em um único pedido, armazenando temporariamente os itens selecionados.

Além disso, o carrinho pode oferecer recursos como aplicação de cupons de desconto, promoções, cálculo de frete, atualização de quantidades e visualização do valor total da compra.

Autenticação

Os endpoints de carrinho não exigem autenticação na maioria dos casos.

A exceção ocorre em funcionalidades promocionais relacionadas ao sistema de pontos e à carteira do cliente, que exigem vínculo com o usuário para validação.

Token

O carrinho pode ser criado a partir de quase todos os endpoints, retornando um token no header da resposta, que deve ser armazenado e reutilizado nas requisições seguintes.

Esse token representa o carrinho atual e permite a utilização sem autenticação.

Caso ele seja perdido, ao realizar qualquer nova solicitação, um novo carrinho e token serão gerados automaticamente.

Embora o token seja retornado inicialmente via header, nas requisições subsequentes ele será enviado por meio de cookie.

Entidades relacionadas

Promocional Cupom

No contexto do carrinho, o cupom permite a aplicação de descontos por meio de um hash que representa um cupom específico.

Essa aplicação envolve regras e período de validade, sendo uma forma simples para o lojista oferecer descontos à loja ou a clientes específicos.

Em geral, apenas quem gera o cupom conhece seu hash e define para quem ele será distribuído.

Promocional Carteira

A carteira do cliente é uma entidade que armazena valores disponíveis, provenientes de cartões-presente, vouchers ou outras ações promocionais.

Em alguns casos, pode conter valores de estornos de compras que não foram concluídas corretamente.

Esse saldo pode ser utilizado no carrinho como forma de pagamento ou desconto.

Promocional Sistema de Pontos

O sistema de pontos premia o cliente após cada compra, permitindo o acúmulo de pontos que podem ser convertidos em descontos para compras futuras.

No carrinho, esses pontos podem ser aplicados para redução do valor total ou, caso o saldo seja suficiente, para pagamento integral de um produto ou serviço.

Produtos de Upsell

Os produtos de upsell são sugestões exibidas, geralmente, no checkout, oferecendo algum desconto adicional com base nos itens presentes no carrinho.

Cada item pode atender a regras específicas de segmentação, fazendo com que determinados produtos sejam exibidos como oferta.

Compre Junto

Produtos de compre junto são sugestões complementares ao produto principal.

Quando o item sugerido é adicionado ao carrinho, pode ser aplicado um desconto, conforme a configuração definida pelo lojista.

Notas e Considerações

O carrinho é recalculado constantemente e passa repetidamente pelos mesmos processos a cada endpoint acionado.

Por esse motivo, alguns erros podem se repetir em diferentes operações.

Nesta documentação, foram priorizados os erros mais relevantes dentro do contexto específico de cada endpoint.

Busca opções de pagamentos do carrinho

Descrição

Endpoint responsável por retornar ao cliente quais opções de pagamento a loja disponibiliza para a compra do carrinho atual 💳.

Essas informações permitem que o cliente visualize previamente os meios de pagamento disponíveis, garantindo clareza no processo de escolha antes da finalização do pedido.

Parâmetros de Query

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/cart/payments \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "paymentOption": {
3    "id": 1,
4    "paymentId": 1,
5    "paymentCode": "abc-123",
6    "paymentStoreCredentialId": 2,
7    "paymentAntiFraudCredentialId": null,
8    "paymentType": {
9      "id": 1,
10      "code": "credit-card"
11    },
12    "active": true,
13    "label": "Cartão de Crédito",
14    "description": "",
15    "instruction": "",
16    "order": 0,
17    "options": [],
18    "configurations": [
19      {
20        "code": "max-number-installment",
21        "title": "Número máximo de Parcelas",
22        "value": 2
23      },
24      {
25        "code": "min-value-installment",
26        "title": "Valor mínimo de cada parcela",
27        "value": 1.24
28      },
29      {
30        "code": "installment-map",
31        "title": "Mapa de configuração por parcela",
32        "value": [
33          {
34            "fee": 11.11,
35            "showFee": false,
36            "active": true
37          },
38          {
39            "fee": 0,
40            "showFee": true,
41            "active": true
42          },
43        ]
44      },
45      {
46        "code": "cash-discount",
47        "title": "Desconto à vista",
48        "value": 1.23
49      },
50      {
51        "code": "automatic-capture",
52        "title": "Captura automática",
53        "value": true
54      },
55      {
56        "code": "payment-min-value",
57        "title": "Valor mínimo do pagamento",
58        "value": 12.31
59      }
60    ],
61    "publicCredentials": {
62      "public-key": "pkabc1234643231"
63    }
64  },
65  "cashDiscount": {
66    "discountPercentage": 0,
67    "discountValue": 0,
68    "valueWithDiscount": 300
69  },
70  "installments": [
71    {
72      "installment": 1,
73      "installmentValue": 300,
74      "totalValue": 300,
75      "fee": null,
76      "feeTotalValue": 0
77    },
78    {
79      "installment": 2,
80      "installmentValue": 150,
81      "totalValue": 300,
82      "fee": 0,
83      "feeTotalValue": 0
84    }
85  ],
86  "error": null
87}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

⚠️ Erros genéricos de carrinho:

Gerar token de pagamento

Descrição

Endpoint responsável por gerar um token de pagamento assinado que autentica a sessão do iframe de checkout 🔐.

O token encapsula o contexto do carrinho atual — identificador do carrinho, cliente, loja, política comercial, canal de venda, moeda e opção de pagamento selecionada.

O token gerado possui validade de 15 minutos a partir do momento da geração. Após esse período, o iframe rejeitará o token e uma nova requisição será necessária.

Como utilizar

O token retornado deve ser enviado ao iframe de pagamento como parâmetro de inicialização. O iframe utiliza este token para validar a sessão e renderizar o formulário de pagamento correspondente à opção selecionada.

Pagamento via Link de Pagamento

Quando o pagamento se refere a um pedido criado previamente através de um link de pagamento, envie o código do link em orderGroupPaymentCode.

Nesse caso, o token é resolvido a partir do pedido vinculado ao link (não do carrinho ativo da sessão), e o campo orderGroupId é incluído no payload do token. As mesmas validações do link se aplicam: expiração, status do pedido (deve estar aguardando pagamento) e a opção de pagamento escolhida precisa estar na allowlist definida na geração do link.

Parâmetros de Query

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição (carrinho)

1curl --request POST \
2  --url {{MAIN_URL}}/cart/payment-token \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "paymentOptionId": 1
7  }'

Exemplo de Requisição (link de pagamento)

1curl --request POST \
2  --url {{MAIN_URL}}/cart/payment-token \
3  --header "Content-Type: application/json" \
4  --data '{
5    "paymentOptionId": 1,
6    "orderGroupPaymentCode": "a1b2c3d4e5f6"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "token": "eyJjYXJ0SWQiOiJhYzY2Y2ExZDYxNTc3YjIxNjk3OTE2OSIsImN1c3RvbWVySWQiOjAsInN0b3JlSWQiOjEsInRyYWRlUG9saWN5SWQiOjEsInNhbGVzQ2hhbm5lbElkIjoxLCJzYWxlc0NoYW5uZWxEb21haW4iOiJzdWEtbG9qYS5jb20uYnIiLCJjdXJyZW5jeUlkIjoiQlJMIiwicGF5bWVudE9wdGlvbklkIjoxLCJleHBpcmVzQXQiOjE3NDM0Mzc0MDZ9.IiwicGF5bWVudE9wdGlvb"
5  }
6}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

⚠️ Erros de token:

⚠️ Erros genéricos de carrinho:

⚠️ Erros específicos de link de pagamento (quando orderGroupPaymentCode é enviado):