VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pedidos do seller

Oferta pós-compra

Cria, lista, altera e remove as regras de oferta pós-compra do seller, a oferta com desconto mostrada ao cliente logo depois que ele fecha um pedido.

A oferta pós-compra (upsell de um clique) é um produto extra, com desconto, que a vitrine mostra ao cliente na tela de confirmação, depois que o pedido foi feito. Se o cliente aceita dentro de 30 minutos, a plataforma cria um pedido filho só com esse produto (frete zero), sem mexer no pedido original já pago. Se ele ignora ou recusa, a oferta expira.

O seller controla isso por regras: "quando o cliente comprar X, ofereça Y com Z% de desconto". Para cada pedido novo, a plataforma percorre as regras ativas da maior para a menor priority e usa a primeira que combina e cujo produto ofertado esteja disponível e com estoque. Cada pedido recebe no máximo uma oferta.

Os produtos da regra (o ofertado e, no gatilho product, o gatilho) precisam ser do próprio seller.

Regras de todos os sellers disputam a mesma fila

Pelo que o código mostra, ao escolher a oferta de um pedido a plataforma lê as regras ativas da loja inteira, sem separar por seller. Uma regra com gatilho any pode, portanto, ser escolhida para o pedido de outro seller da mesma loja, e quem tiver a maior priority ganha. Use gatilhos product ou category quando quiser limitar a oferta ao que você vende, e dê uma priority que faça sentido na loja.

Campos de uma regra

CampoTipoObservação
trigger_typestringproduct, category ou any. Obrigatório na prática: sem ele a gravação é recusada.
trigger_refuuidProduto (para product) ou categoria (para category) que dispara a regra. Ignorado em any. Obrigatório em product.
offer_product_iduuidProduto ofertado. Obrigatório.
discount_percentintegerDesconto em porcentagem inteira, de 0 a 90.
priorityintegerQuanto maior, antes a regra é avaliada. Empate: a mais antiga primeiro.
statusstringactive ou paused. Padrão active.

Listar as regras

GET/api/v1/vendor/post-purchase-rulesSeller

Lista as regras de oferta pós-compra do seller

Devolve todas as regras do seller que não foram removidas, da maior priority para a menor. Não há paginação nem filtros.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/post-purchase-rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Regras do seller
json
{
  "rules": [
    {
      "id": "db8e6d00-7f7a-4a3a-b864-f184f7e630e1",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "trigger_type": "product",
      "trigger_ref": "7a3e1d62-5b0c-4d8a-9c47-2f9f1b6c0a10",
      "offer_product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "discount_percent": 15,
      "priority": 10,
      "status": "active",
      "created_at": "2026-10-11T23:47:58.297811Z"
    }
  ],
  "total": 1
}

Campos da resposta

rulesarray
Regras do seller. Lista vazia ([]) quando não há nenhuma.
totalinteger
Quantidade de regras devolvidas.
rules[].iduuid
Id da regra.
rules[].vendor_iduuid
Seller dono da regra, sempre o seu.
rules[].trigger_typestring
productcategoryany
Tipo de gatilho.
rules[].trigger_refuuid
Produto ou categoria do gatilho. Ausente em any.
rules[].offer_product_iduuid
Produto ofertado.
rules[].discount_percentinteger
Desconto em porcentagem (0 a 90).
rules[].priorityinteger
Prioridade.
rules[].statusstring
activepaused
Situação da regra.
rules[].created_atstring
Criação (RFC 3339, UTC).

Criar uma regra

POST/api/v1/vendor/post-purchase-rulesSeller

Cria uma regra de oferta pós-compra

Cria a regra para o seller autenticado. O vendor_id é sempre o seu: qualquer valor enviado no corpo é ignorado.

Uma regra active só é aceita se o produto ofertado puder ser comprado agora (visível na loja, com estoque maior que zero e seller ativo). Para cadastrar a regra antes de o produto estar à venda, crie com status igual a paused.

Corpo da requisição

trigger_typestringobrigatório
productcategoryany
Tipo de gatilho.
trigger_refuuid
Produto ou categoria que dispara a oferta. Obrigatório quando trigger_type é product (e o produto precisa ser seu). Em category, é o id da categoria; a categoria não é conferida contra o seller.
offer_product_iduuidobrigatório
Produto ofertado. Precisa ser do seller.
discount_percentintegerpadrão: 0
Desconto, de 0 a 90.
priorityintegerpadrão: 0
Prioridade. Maior vem antes.
statusstringpadrão: active
activepaused
Situação inicial.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/vendor/post-purchase-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "product",
    "trigger_ref": "7a3e1d62-5b0c-4d8a-9c47-2f9f1b6c0a10",
    "offer_product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
    "discount_percent": 15,
    "priority": 10
  }'

Resposta: criar

201Regra criada
json
{
  "id": "db8e6d00-7f7a-4a3a-b864-f184f7e630e1",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "trigger_type": "product",
  "trigger_ref": "7a3e1d62-5b0c-4d8a-9c47-2f9f1b6c0a10",
  "offer_product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "discount_percent": 15,
  "priority": 10,
  "status": "active",
  "created_at": "2026-10-11T23:47:58.297811Z"
}

Alterar uma regra

PUT/api/v1/vendor/post-purchase-rules/{id}Seller

Substitui os dados de uma regra do seller

Altera a regra inteira: todos os campos são regravados, e o que você não enviar volta ao padrão (discount_percent e priority viram 0, status vira active). Reenvie sempre o conjunto completo, o mesmo corpo do cadastro. As mesmas validações de posse e de produto à venda da criação valem aqui.

Parâmetros de caminho

iduuidobrigatório
Id da regra.

Corpo da requisição

trigger_typestringobrigatório
productcategoryany
Tipo de gatilho.
trigger_refuuid
Produto ou categoria do gatilho. Obrigatório em product.
offer_product_iduuidobrigatório
Produto ofertado. Precisa ser do seller.
discount_percentintegerpadrão: 0
Desconto, de 0 a 90.
priorityintegerpadrão: 0
Prioridade.
statusstringpadrão: active
activepaused
Situação. Use paused para desligar a regra sem apagá-la.
200Regra alterada
json
{ "status": "ok" }

A resposta não devolve a regra: consulte a lista para ver o resultado.

Remover uma regra

DELETE/api/v1/vendor/post-purchase-rules/{id}Seller

Remove uma regra do seller

Remove a regra (ela deixa de aparecer na lista e de gerar ofertas). Ofertas que já foram mostradas a clientes continuam valendo até expirar.

Parâmetros de caminho

iduuidobrigatório
Id da regra.
200Regra removida
json
{ "status": "deleted" }

Exemplo de requisição: alterar e remover

bash
# alterar (corpo completo)
curl -X PUT "$BASE_URL/api/v1/vendor/post-purchase-rules/db8e6d00-7f7a-4a3a-b864-f184f7e630e1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger_type":"any","offer_product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","discount_percent":10,"priority":1,"status":"paused"}'

# remover
curl -X DELETE "$BASE_URL/api/v1/vendor/post-purchase-rules/db8e6d00-7f7a-4a3a-b864-f184f7e630e1" \
  -H "Authorization: Bearer $TOKEN"

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"invalid request body","detail":"..."}
400Criação sem offer_product_id.{"error":"invalid rule","detail":"offer_product_id is required"}
400trigger_type ausente ou fora dos três valores, ou discount_percent fora de 0 a 90, na criação.{"error":"invalid rule","detail":"o valor enviado está fora da faixa permitida (campo relacionado a \"purchase_rules_trigger_type\"). Corrija o valor e reenvie."}
400Criação de regra active com produto ofertado sem estoque ou fora da loja.{"error":"invalid rule","detail":"post-purchase: offer product is not currently buyable (draft/out of stock/vendor inactive)"}
400Alteração com produto ofertado sem estoque ou fora da loja.{"error":"offer_product_not_buyable","detail":"..."}
401Sem token.{"error":"authentication required"}
403Produto ofertado ou de gatilho não é do seller.{"error":"product does not belong to this vendor","detail":"product does not belong to this vendor"}
404Alteração: regra inexistente ou de outro seller; também qualquer outra falha de validação (veja abaixo). Remoção: regra inexistente.{"error":"update failed","detail":"sql: no rows in result set"}
A alteração responde 404 para erros de validação

Na alteração, só a posse do produto (403) e o produto sem estoque (400) têm status próprio. Qualquer outra falha, como trigger_ref ausente num gatilho product, discount_percent acima de 90 ou trigger_type inválido, também volta como 404 update failed, com a causa em detail. Leia o detail antes de concluir que a regra não existe.

Pausar em vez de apagar

Para testar uma campanha ou desligá-la na baixa temporada, altere status para paused. A regra pausada deixa de concorrer e não exige que o produto ofertado esteja à venda.

Veja também

  • Pedidos do seller
  • Visão geral dos pedidos do seller
  • Promoções do seller
Anterior
Enviar fatura por e-mail
Próxima
Pedidos do cliente
Nesta página
  • Campos de uma regra
  • Listar as regras
  • Exemplo de requisição: listar
  • Resposta: listar
  • Criar uma regra
  • Exemplo de requisição: criar
  • Resposta: criar
  • Alterar uma regra
  • Remover uma regra
  • Exemplo de requisição: alterar e remover
  • Erros
  • Veja também