API atual/Referência completa/Promoções do seller

Carrinhos abandonados

Lista, detalha e totaliza os carrinhos abandonados que continham produtos do seller.

Um carrinho abandonado é um carrinho em que o cliente colocou produtos e saiu sem comprar. A loja tenta recuperá-lo (por exemplo com e-mails), e o carrinho passa a recovered quando um pedido sai dele. Estas rotas são somente leitura: o seller vê o que ficou para trás nos produtos dele, mas não cria, edita, apaga nem dispara e-mails de recuperação (isso é operação da loja).

Um carrinho pode misturar itens de vários sellers, então não tem um dono único. A visão do seller é derivada: aparecem os carrinhos que contêm pelo menos um item dele, e cada carrinho é recortado para mostrar só as linhas dele. cart_total_cents e item_count já saem recalculados sobre essas linhas, e o token de recuperação (que abriria o carrinho inteiro) nunca é devolvido.

Listar carrinhos abandonados

GET/api/v1/vendor/abandoned-cartsSeller

Lista os carrinhos abandonados com itens do seller

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta a 20.

recoveredboolean

truefalse

Só recuperados (true) ou só não recuperados (false). Outro valor é ignorado.

emailstring

Parte do e-mail do cliente.

searchstring

Texto procurado no e-mail, no nome, no sobrenome, na razão social e no nome fantasia do cliente.

date_fromstring

Data de abandono mínima, ISO 8601 (2026-10-01 ou 2026-10-01T00:00:00-03:00).

date_tostring

Data de abandono máxima, ISO 8601. Uma data sem hora vale até a meia-noite do início desse dia.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/abandoned-carts?recovered=false&date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Carrinhos abandonados

json

{
  "carts": [
    {
      "id": "b2d4f1a0-6c3e-4a57-9b88-1f0e5d7a9c11",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "email": "maria.souza@example.com",
      "user_email": "maria.souza@example.com",
      "cart_data": [
        {
          "product_id": "0e6c2f44-5d1a-4c8b-8f33-2a9b7c1d5e60",
          "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
          "name": "Camiseta Algodão Azul",
          "sku": "CAM-AZ-M",
          "image_url": "https://cdn.example.com/cam-az.jpg",
          "unit_price": 8990,
          "quantity": 2,
          "total": 17980
        }
      ],
      "cart_total_cents": 17980,
      "item_count": 2,
      "recovery_emails_sent": 1,
      "last_email_sent_at": "2026-10-10T13:00:00Z",
      "last_campaign_step": 1,
      "recovered": false,
      "abandoned_at": "2026-10-09T21:15:00Z",
      "created_at": "2026-10-09T21:15:00Z",
      "updated_at": "2026-10-10T13:00:00Z",
      "customer_document": "12345678909"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

cartsarray

Carrinhos da página, do abandono mais recente para o mais antigo.

iduuid

Identificador do carrinho abandonado.

user_idstring | omitted

Id do cliente. Ausente em visitante.

emailstring | omitted

E-mail informado no carrinho (cliente ou visitante).

user_emailstring

E-mail da conta do cliente, ou o do carrinho quando não há conta.

cart_dataarray

Linhas do carrinho só do seller. Cada linha traz product_id, vendor_id, name, sku, image_url, unit_price e total em centavos e quantity.

cart_total_centsinteger

Soma das linhas do seller, em centavos.

item_countinteger

Soma das quantidades das linhas do seller (unidades, não linhas).

recovery_emails_sentinteger

Quantos e-mails de recuperação já saíram.

last_email_sent_atstring (RFC 3339) | omitted

Envio do último e-mail.

matched_rule_idinteger | omitted

Regra de recuperação da loja que casou com o carrinho.

last_campaign_stepinteger

Maior passo da campanha já enviado: 0 nenhum, 1, 2 ou 3.

recoveredboolean

true quando um pedido do seller saiu desse carrinho. Se a recuperação foi só em itens de outro seller, aparece false.

recovered_atstring (RFC 3339) | omitted

Quando foi recuperado.

recovered_order_iduuid | omitted

Id do pedido do seller que recuperou o carrinho.

recovered_order_numberstring | omitted

Número do pedido, para achar a venda em Listar pedidos do seller.

abandoned_atstring (RFC 3339)

Quando o carrinho foi dado como abandonado.

created_atstring (RFC 3339)

Criação do registro.

updated_atstring (RFC 3339)

Última alteração do registro.

customer_documentstring | omitted

CNPJ do cliente (14 dígitos) ou, sem CNPJ, CPF (11 dígitos), só números. Ausente em visitante.

totalinteger

Total de carrinhos que casam com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página.

total_pagesinteger

Total de páginas.

Totais e taxa de recuperação

GET/api/v1/vendor/abandoned-carts/statsSeller

Totais dos carrinhos abandonados do seller

Parâmetros de consulta

date_fromstring

Data de abandono mínima, ISO 8601.

date_tostring

Data de abandono máxima, ISO 8601.

Resposta: totais

200Totais

json

{
  "total_abandoned": 42,
  "emails_sent": 57,
  "recovered": 6,
  "recovery_rate": 14.285714285714285,
  "total_value": 612300,
  "avg_cart_value": 14579
}

Campos da resposta

total_abandonedinteger

Carrinhos abandonados com itens do seller no período.

emails_sentinteger

Soma dos e-mails de recuperação enviados nesses carrinhos.

recoveredinteger

Carrinhos recuperados por um pedido do seller.

recovery_ratenumber

recovered sobre total_abandoned, em porcentagem de 0 a 100. 0 sem carrinhos.

total_valueinteger

Soma, em centavos, dos itens do seller nos carrinhos.

avg_cart_valueinteger

total_value dividido por total_abandoned, arredondado, em centavos.

Detalhar um carrinho

GET/api/v1/vendor/abandoned-carts/{id}Seller

Detalha um carrinho abandonado do seller

Parâmetros de caminho

iduuidobrigatório

Id do carrinho abandonado.

Resposta: detalhar

A resposta é um item igual aos de carts na listagem. Um carrinho que existe mas não tem itens do seller responde 404.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou ele não tem privilégio de pedidos.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_manage_orders", "..."]}`
400	No detalhe: `id` que não é UUID.	`{"error":"invalid cart id"}`
404	No detalhe: o carrinho não existe ou não tem itens do seller.	`{"error":"abandoned cart not found"}`
500	Falha ao ler, ou um carrinho cuja gravação está corrompida.	`{"error":"failed to list abandoned carts","detail":"..."}`

Veja também

Carrinhos abandonados

Lista, detalha e totaliza os carrinhos abandonados que continham produtos do seller.

Listar carrinhos abandonados

GET/api/v1/vendor/abandoned-cartsSeller

Lista os carrinhos abandonados com itens do seller

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta a 20.

recoveredboolean

truefalse

Só recuperados (true) ou só não recuperados (false). Outro valor é ignorado.

emailstring

Parte do e-mail do cliente.

searchstring

Texto procurado no e-mail, no nome, no sobrenome, na razão social e no nome fantasia do cliente.

date_fromstring

Data de abandono mínima, ISO 8601 (2026-10-01 ou 2026-10-01T00:00:00-03:00).

date_tostring

Data de abandono máxima, ISO 8601. Uma data sem hora vale até a meia-noite do início desse dia.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/abandoned-carts?recovered=false&date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Carrinhos abandonados

json

{
  "carts": [
    {
      "id": "b2d4f1a0-6c3e-4a57-9b88-1f0e5d7a9c11",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "email": "maria.souza@example.com",
      "user_email": "maria.souza@example.com",
      "cart_data": [
        {
          "product_id": "0e6c2f44-5d1a-4c8b-8f33-2a9b7c1d5e60",
          "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
          "name": "Camiseta Algodão Azul",
          "sku": "CAM-AZ-M",
          "image_url": "https://cdn.example.com/cam-az.jpg",
          "unit_price": 8990,
          "quantity": 2,
          "total": 17980
        }
      ],
      "cart_total_cents": 17980,
      "item_count": 2,
      "recovery_emails_sent": 1,
      "last_email_sent_at": "2026-10-10T13:00:00Z",
      "last_campaign_step": 1,
      "recovered": false,
      "abandoned_at": "2026-10-09T21:15:00Z",
      "created_at": "2026-10-09T21:15:00Z",
      "updated_at": "2026-10-10T13:00:00Z",
      "customer_document": "12345678909"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

cartsarray

Carrinhos da página, do abandono mais recente para o mais antigo.

iduuid

Identificador do carrinho abandonado.

user_idstring | omitted

Id do cliente. Ausente em visitante.

emailstring | omitted

E-mail informado no carrinho (cliente ou visitante).

user_emailstring

E-mail da conta do cliente, ou o do carrinho quando não há conta.

cart_dataarray

Linhas do carrinho só do seller. Cada linha traz product_id, vendor_id, name, sku, image_url, unit_price e total em centavos e quantity.

cart_total_centsinteger

Soma das linhas do seller, em centavos.

item_countinteger

Soma das quantidades das linhas do seller (unidades, não linhas).

recovery_emails_sentinteger

Quantos e-mails de recuperação já saíram.

last_email_sent_atstring (RFC 3339) | omitted

Envio do último e-mail.

matched_rule_idinteger | omitted

Regra de recuperação da loja que casou com o carrinho.

last_campaign_stepinteger

Maior passo da campanha já enviado: 0 nenhum, 1, 2 ou 3.

recoveredboolean

true quando um pedido do seller saiu desse carrinho. Se a recuperação foi só em itens de outro seller, aparece false.

recovered_atstring (RFC 3339) | omitted

Quando foi recuperado.

recovered_order_iduuid | omitted

Id do pedido do seller que recuperou o carrinho.

recovered_order_numberstring | omitted

Número do pedido, para achar a venda em Listar pedidos do seller.

abandoned_atstring (RFC 3339)

Quando o carrinho foi dado como abandonado.

created_atstring (RFC 3339)

Criação do registro.

updated_atstring (RFC 3339)

Última alteração do registro.

customer_documentstring | omitted

CNPJ do cliente (14 dígitos) ou, sem CNPJ, CPF (11 dígitos), só números. Ausente em visitante.

totalinteger

Total de carrinhos que casam com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página.

total_pagesinteger

Total de páginas.

Totais e taxa de recuperação

GET/api/v1/vendor/abandoned-carts/statsSeller

Totais dos carrinhos abandonados do seller

Parâmetros de consulta

date_fromstring

Data de abandono mínima, ISO 8601.

date_tostring

Data de abandono máxima, ISO 8601.

Resposta: totais

200Totais

json

{
  "total_abandoned": 42,
  "emails_sent": 57,
  "recovered": 6,
  "recovery_rate": 14.285714285714285,
  "total_value": 612300,
  "avg_cart_value": 14579
}

Campos da resposta

total_abandonedinteger

Carrinhos abandonados com itens do seller no período.

emails_sentinteger

Soma dos e-mails de recuperação enviados nesses carrinhos.

recoveredinteger

Carrinhos recuperados por um pedido do seller.

recovery_ratenumber

recovered sobre total_abandoned, em porcentagem de 0 a 100. 0 sem carrinhos.

total_valueinteger

Soma, em centavos, dos itens do seller nos carrinhos.

avg_cart_valueinteger

total_value dividido por total_abandoned, arredondado, em centavos.

Detalhar um carrinho

GET/api/v1/vendor/abandoned-carts/{id}Seller

Detalha um carrinho abandonado do seller

Parâmetros de caminho

iduuidobrigatório

Id do carrinho abandonado.

Resposta: detalhar

A resposta é um item igual aos de carts na listagem. Um carrinho que existe mas não tem itens do seller responde 404.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou ele não tem privilégio de pedidos.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_manage_orders", "..."]}`
400	No detalhe: `id` que não é UUID.	`{"error":"invalid cart id"}`
404	No detalhe: o carrinho não existe ou não tem itens do seller.	`{"error":"abandoned cart not found"}`
500	Falha ao ler, ou um carrinho cuja gravação está corrompida.	`{"error":"failed to list abandoned carts","detail":"..."}`