Recuperar carrinho abandonado

Consulta e restaura o carrinho de quem saiu sem comprar, a partir do link enviado por e-mail pela campanha de recuperação.

Um carrinho abandonado é um carrinho com itens cujo dono saiu sem fechar o pedido. A plataforma detecta esses carrinhos e, se a loja tem uma campanha de recuperação ligada, envia ao comprador um e-mail com um link que carrega um token de recuperação. Estas duas rotas são o que a página desse link usa: uma mostra o que havia no carrinho e a outra o reconstrói no carrinho atual do comprador.

O token é a única prova de acesso: quem tem o link vê os itens, sem login. O token tem prazo de validade; depois dele a API o recusa.

O comprador abre o link do e-mail
A página da loja recebe o token e chama GET /recover-cart/{token} para mostrar "você deixou estes itens".
Restaura o carrinho
Se o comprador confirma, a página chama POST /cart/restore-from-recovery com o mesmo token. Os itens voltam ao carrinho do visitante (ou da conta, se logado), já com os preços e o estoque de hoje.
Segue para o checkout
O restante é o fluxo normal: calcular e iniciar o checkout. O carrinho abandonado só é marcado como recuperado quando um pedido é criado.

Consultar um carrinho abandonado

GET/api/v1/storefront/recover-cart/{token}Pública

Consulta um carrinho abandonado pelo token de recuperação

Devolve o conteúdo do carrinho abandonado como ele estava. Não altera nada: nem cria carrinho, nem marca o abandono como recuperado.

Parâmetros de caminho

tokenstringobrigatório

O token de recuperação do link do e-mail.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recover-cart/$RECOVERY_TOKEN"

Resposta

200Carrinho abandonado

json

{
  "message": "cart recovered",
  "cart_id": "9c2d1f1e-3b4a-4c5d-8e6f-7a8b9c0d1e2f",
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "image_url": "/uploads/.../notebook.png",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "cart_total_cents": 23000,
  "item_count": 2
}

Campos da resposta

messagestring

Sempre cart recovered. Texto fixo em inglês.

cart_iduuid

Id do registro de abandono (não é o id de um carrinho ativo).

itemsarray

Itens como estavam quando o carrinho foi abandonado: product_id, variation_id, vendor_id, name, sku, image_url, unit_price (centavos), quantity e total (centavos).

cart_total_centsinteger

Valor do carrinho na época, em centavos. Pode estar diferente do preço de hoje.

item_countinteger

Quantidade de itens.

Restaurar o carrinho

POST/api/v1/storefront/cart/restore-from-recoveryAutenticada

Reconstrói o carrinho atual a partir de um carrinho abandonado

Reconstrói o carrinho do comprador a partir do abandono, em uma única chamada. Cada item passa pelas mesmas regras de POST /cart/bulk: o preço é o do catálogo de hoje e itens sem estoque ou fora de linha não entram, mas vão para failed sem derrubar os demais. A configuração de variações e opções de cada item é preservada.

Se o token veio de um e-mail de campanha que prometia um cupom de desconto, esse cupom é gravado no carrinho automaticamente quando pelo menos um item voltou, e o código é devolvido em discount_code.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado, para restaurar na conta.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

tokenstringobrigatório

O token de recuperação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/restore-from-recovery" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "9f2b7c1e4d8a4b6f"
}'

Resposta

200Carrinho restaurado

json

{
  "restored": true,
  "added": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "failed": [],
  "cart": { "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23", "subtotal": 23000, "total": 23000 },
  "discount_code": "VOLTE10"
}

Campos da resposta

restoredboolean

Sempre true numa resposta 200, mesmo que added esteja vazio. Confira added e failed.

addedarray

Linhas que voltaram ao carrinho.

failedarray

Linhas que não voltaram, cada uma com product_id e reason.

cartobject

O carrinho depois da restauração, como em Ler o carrinho.

discount_codestring

Cupom da campanha, quando existe. Ausente caso contrário.

Erros

Status	Quando	Corpo
400	Token inválido, expirado ou carrinho já recuperado (`GET`)	`{"error":"invalid or expired recovery token","detail":"invalid or expired recovery token"}`
400	Sem token de login e sem `X-Session-ID` (`POST`)	`{"error":"session_id or authentication required"}`
400	`token` vazio no corpo (`POST`)	`{"error":"token is required"}`
400	O abandono não tem itens (`POST`)	`{"error":"recovery snapshot has no items"}`
404	Token que não existe ou expirou (`POST`)	`{"error":"invalid or expired recovery token"}`
503	A loja não tem a recuperação de carrinho disponível	`{"error":"cart recovery not available"}`

Repare que o mesmo token inválido gera 400 na consulta (GET) e 404 na restauração (POST).

Veja também

Recuperar carrinho abandonado

Consulta e restaura o carrinho de quem saiu sem comprar, a partir do link enviado por e-mail pela campanha de recuperação.

O token é a única prova de acesso: quem tem o link vê os itens, sem login. O token tem prazo de validade; depois dele a API o recusa.

O comprador abre o link do e-mail
A página da loja recebe o token e chama GET /recover-cart/{token} para mostrar "você deixou estes itens".
Restaura o carrinho
Se o comprador confirma, a página chama POST /cart/restore-from-recovery com o mesmo token. Os itens voltam ao carrinho do visitante (ou da conta, se logado), já com os preços e o estoque de hoje.
Segue para o checkout
O restante é o fluxo normal: calcular e iniciar o checkout. O carrinho abandonado só é marcado como recuperado quando um pedido é criado.

Consultar um carrinho abandonado

GET/api/v1/storefront/recover-cart/{token}Pública

Consulta um carrinho abandonado pelo token de recuperação

Devolve o conteúdo do carrinho abandonado como ele estava. Não altera nada: nem cria carrinho, nem marca o abandono como recuperado.

Parâmetros de caminho

tokenstringobrigatório

O token de recuperação do link do e-mail.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recover-cart/$RECOVERY_TOKEN"

Resposta

200Carrinho abandonado

json

{
  "message": "cart recovered",
  "cart_id": "9c2d1f1e-3b4a-4c5d-8e6f-7a8b9c0d1e2f",
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "image_url": "/uploads/.../notebook.png",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "cart_total_cents": 23000,
  "item_count": 2
}

Campos da resposta

messagestring

Sempre cart recovered. Texto fixo em inglês.

cart_iduuid

Id do registro de abandono (não é o id de um carrinho ativo).

itemsarray

Itens como estavam quando o carrinho foi abandonado: product_id, variation_id, vendor_id, name, sku, image_url, unit_price (centavos), quantity e total (centavos).

cart_total_centsinteger

Valor do carrinho na época, em centavos. Pode estar diferente do preço de hoje.

item_countinteger

Quantidade de itens.

Restaurar o carrinho

POST/api/v1/storefront/cart/restore-from-recoveryAutenticada

Reconstrói o carrinho atual a partir de um carrinho abandonado

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado, para restaurar na conta.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

tokenstringobrigatório

O token de recuperação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/restore-from-recovery" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "9f2b7c1e4d8a4b6f"
}'

Resposta

200Carrinho restaurado

json

{
  "restored": true,
  "added": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "failed": [],
  "cart": { "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23", "subtotal": 23000, "total": 23000 },
  "discount_code": "VOLTE10"
}

Campos da resposta

restoredboolean

Sempre true numa resposta 200, mesmo que added esteja vazio. Confira added e failed.

addedarray

Linhas que voltaram ao carrinho.

failedarray

Linhas que não voltaram, cada uma com product_id e reason.

cartobject

O carrinho depois da restauração, como em Ler o carrinho.

discount_codestring

Cupom da campanha, quando existe. Ausente caso contrário.

Erros

Status	Quando	Corpo
400	Token inválido, expirado ou carrinho já recuperado (`GET`)	`{"error":"invalid or expired recovery token","detail":"invalid or expired recovery token"}`
400	Sem token de login e sem `X-Session-ID` (`POST`)	`{"error":"session_id or authentication required"}`
400	`token` vazio no corpo (`POST`)	`{"error":"token is required"}`
400	O abandono não tem itens (`POST`)	`{"error":"recovery snapshot has no items"}`
404	Token que não existe ou expirou (`POST`)	`{"error":"invalid or expired recovery token"}`
503	A loja não tem a recuperação de carrinho disponível	`{"error":"cart recovery not available"}`

Repare que o mesmo token inválido gera 400 na consulta (GET) e 404 na restauração (POST).