VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Assinaturas e compras programadas

Regras de desconto da compra programada

Define o modo e os descontos por frequência da compra programada no seller, na categoria e no produto.

O desconto que o cliente ganha ao programar uma compra não é um número único: ele vem de uma cascata de regras. Para cada produto a plataforma procura, nesta ordem, e para na primeira que decidir:

  1. Produto: se o produto está custom (tem descontos próprios) ou disabled (proibido), vale ele.
  2. Categoria: o mesmo, olhando a categoria do produto.
  3. Seller: se o seller tem uma regra gravada e ela não está disabled, vale a regra dele; caso contrário a compra programada fica indisponível. Um seller que nunca gravou uma regra não entra na cascata: sem custom no produto ou na categoria, o produto dele não oferece compra programada.

Quando o produto ou a categoria estão inherit (a regra "herdar"), a decisão sobe para o nível de baixo. Os descontos são porcentagens inteiras de 0 a 99, por frequência:

ChaveCicloDesconto padrão do seller
semanal7 dias5
quinzenal14 dias7
mensal30 dias10
bimestral60 dias12
trimestral90 dias15
quadrimestral120 dias17
semestral180 dias20
anual365 dias25

Exigem o módulo recurring-payments; ler exige manage_content ou view_content e gravar exige manage_content. Os erros desta página seguem o formato {"error": "<código>", "message": "<texto em português>"}; os textos de message vêm do servidor em português.

Ler a regra de um seller

Devolve o modo e os descontos do seller. Seller sem regra gravada recebe os padrões acima, com modo allows, mas isso é só a leitura: enquanto nenhuma regra for gravada com o PUT, o seller não entra na cascata.

GET/api/v1/admin/recurring/sellers/{vendorId}Admin

Lê a regra de compra programada de um seller

Parâmetros de caminho

vendorIduuidobrigatório
Id do seller.

Exemplo de requisição

Resposta

200Regra devolvida

Campos da resposta

vendor_iduuid
Seller.
modestring
allowsmandatorydisabled
Modo do seller (veja a gravação).
discountsobject
Porcentagem inteira de desconto por chave de frequência.

Erros

StatusQuandoCorpo
500Id que não é UUID ou falha de consulta{"error":"recurring_failed","message":"Não foi possível concluir a operação. Tente novamente."}

Um UUID válido que não corresponde a nenhum seller devolve os padrões, sem erro.

Gravar a regra de um seller

PUT/api/v1/admin/recurring/sellers/{vendorId}Admin

Grava a regra de compra programada de um seller

Parâmetros de caminho

vendorIduuidobrigatório
Id do seller.

Corpo da requisição

modestringpadrão: allows
allowsmandatorydisabled
allows: o cliente pode programar. mandatory: o modo é repassado à vitrine como obrigatório. disabled: sem compra programada, a não ser que o produto ou a categoria ligue de novo com custom. Vazio vira allows.
discountsobject
Porcentagem inteira (0 a 99) por chave de frequência. Ausente, volta aos descontos padrão. Chave desconhecida ou valor fora de 0 a 99 é recusado.

Exemplo de requisição

Resposta

200Regra gravada

A resposta é a regra relida depois de gravar. Os descontos enviados substituem o mapa inteiro: as frequências que você não enviou deixam de ter desconto.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid_json","message":"Corpo da requisição inválido."}
422mode fora da lista{"error":"mode_invalid","message":"Modo inválido: use permite, obrigatório ou desativado."}
422Chave de frequência desconhecida ou desconto fora de 0 a 99{"error":"discount_invalid","message":"Desconto inválido para a compra programada (0 a 99%)."}

Gravar a regra de uma categoria

A categoria usa um conjunto de modos diferente do seller: decide se sobrepõe a regra de baixo.

PUT/api/v1/admin/recurring/categories/{id}Admin

Grava a regra de compra programada de uma categoria

Parâmetros de caminho

iduuidobrigatório
Id da categoria.

Corpo da requisição

modestringpadrão: inherit
inheritcustomdisabled
inherit: não decide, vale a regra do seller. custom: usa os descontos desta categoria. disabled: proíbe a compra programada nesta categoria. Os valores allows e mandatory são aceitos e tratados como inherit. Um custom sem nenhum desconto vira disabled.
discountsobject
Porcentagem (0 a 99) por chave de frequência. Só é guardado com custom; nos outros modos é descartado. Valores fracionados são arredondados para o inteiro mais próximo.

Exemplo de requisição

Resposta

200Regra gravada

A resposta não devolve a regra gravada, só a confirmação. Não há rota de leitura da regra de categoria neste grupo.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid_json","message":"Corpo da requisição inválido."}
422mode fora da lista{"error":"mode_invalid","message":"Modo inválido: use herdar, personalizado ou desativado."}
422Chave de frequência desconhecida{"error":"discount_invalid","message":"Frequência desconhecida na compra programada."}
422Desconto fora de 0 a 99{"error":"discount_invalid","message":"O desconto deve estar entre 0 e 99%."}
500Id que não é UUID ou falha ao gravar{"error":"recurring_failed","message":"Não foi possível concluir a operação. Tente novamente."}

Gravar a regra de um produto

A regra do produto é a de maior precedência. Usa os mesmos modos e descontos da categoria.

PUT/api/v1/admin/recurring/products/{id}Admin

Grava a regra de compra programada de um produto

Parâmetros de caminho

iduuidobrigatório
Id do produto.

Corpo da requisição

modestringpadrão: inherit
inheritcustomdisabled
inherit: vale a categoria e depois o seller. custom: usa os descontos do produto. disabled: proíbe a compra programada neste produto. allows e mandatory são tratados como inherit; custom sem descontos vira disabled.
discountsobject
Porcentagem (0 a 99) por chave de frequência. Só é guardado com custom.

Exemplo de requisição

Resposta

200Regra gravada

Campos da resposta

okboolean
true quando gravou.
iduuid
Produto.
modestring
inheritcustomdisabled
Modo realmente gravado. Pode diferir do enviado: custom sem descontos volta como disabled.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid_json","message":"Corpo da requisição inválido."}
404Produto inexistente ou id que não é UUID{"error":"product_not_found","message":"Produto não encontrado."}
422mode fora da lista, frequência desconhecida ou desconto fora de 0 a 99{"error":"mode_invalid","message":"Modo inválido: use herdar, personalizado ou desativado."}
422O produto já é uma assinatura e você tentou custom{"error":"mutually_exclusive","message":"Um produto não pode ser assinatura e compra programada ao mesmo tempo."}
Assinatura e compra programada não convivem no mesmo produto

Um produto configurado como assinatura não aceita desconto custom de compra programada, e o contrário também vale. Escolha o modelo do produto antes de configurar os descontos. A configuração de assinatura do produto fica fora desta seção.

Como testar a cascata

Depois de gravar, confira o que o cliente vê pela consulta pública de configuração do produto na vitrine, não só pelo que você gravou: um disabled na categoria pode estar escondendo o custom do seller, e é a cascata que decide.

Veja também

  • Compras programadas
  • Termos de aceite
Anterior
Termos de aceite
Próxima
Moedas
Nesta página
  • Ler a regra de um seller
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a regra de um seller
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a regra de uma categoria
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a regra de um produto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/recurring/sellers/ec5e10b3-8cb1-43e9-9aa8-964b64eda8de" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/admin/recurring/sellers/ec5e10b3-8cb1-43e9-9aa8-964b64eda8de" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "allows", "discounts": { "semanal": 5, "mensal": 10, "trimestral": 15 } }'
bash
curl -X PUT "$BASE_URL/api/v1/admin/recurring/categories/0e7a4b91-2c35-4d68-9f10-8a3b5c6d7e21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "custom", "discounts": { "mensal": 12, "trimestral": 18 } }'
bash
curl -X PUT "$BASE_URL/api/v1/admin/recurring/products/e3a71800-294f-4167-a755-cabedcf094b4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "custom", "discounts": { "mensal": 15 } }'
json
{
  "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "mode": "allows",
  "discounts": {
    "semanal": 5, "quinzenal": 7, "mensal": 10, "bimestral": 12,
    "trimestral": 15, "quadrimestral": 17, "semestral": 20, "anual": 25
  }
}
json
{
  "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "mode": "allows",
  "discounts": { "semanal": 5, "mensal": 10, "trimestral": 15 }
}
json
{ "ok": true, "id": "0e7a4b91-2c35-4d68-9f10-8a3b5c6d7e21" }
json
{ "ok": true, "id": "e3a71800-294f-4167-a755-cabedcf094b4", "mode": "custom" }