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:

Produto: se o produto está custom (tem descontos próprios) ou disabled (proibido), vale ele.
Categoria: o mesmo, olhando a categoria do produto.
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:

Chave	Ciclo	Desconto padrão do seller
`semanal`	7 dias	5
`quinzenal`	14 dias	7
`mensal`	30 dias	10
`bimestral`	60 dias	12
`trimestral`	90 dias	15
`quadrimestral`	120 dias	17
`semestral`	180 dias	20
`anual`	365 dias	25

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

bash

curl "$BASE_URL/api/v1/admin/recurring/sellers/ec5e10b3-8cb1-43e9-9aa8-964b64eda8de" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra devolvida

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
  }
}

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

Status	Quando	Corpo
500	Id 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

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 } }'

Resposta

200Regra gravada

json

{
  "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "mode": "allows",
  "discounts": { "semanal": 5, "mensal": 10, "trimestral": 15 }
}

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`mode` fora da lista	`{"error":"mode_invalid","message":"Modo inválido: use permite, obrigatório ou desativado."}`
422	Chave 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

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 } }'

Resposta

200Regra gravada

json

{ "ok": true, "id": "0e7a4b91-2c35-4d68-9f10-8a3b5c6d7e21" }

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`mode` fora da lista	`{"error":"mode_invalid","message":"Modo inválido: use herdar, personalizado ou desativado."}`
422	Chave de frequência desconhecida	`{"error":"discount_invalid","message":"Frequência desconhecida na compra programada."}`
422	Desconto fora de 0 a 99	`{"error":"discount_invalid","message":"O desconto deve estar entre 0 e 99%."}`
500	Id 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

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 } }'

Resposta

200Regra gravada

json

{ "ok": true, "id": "e3a71800-294f-4167-a755-cabedcf094b4", "mode": "custom" }

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
404	Produto inexistente ou id que não é UUID	`{"error":"product_not_found","message":"Produto não encontrado."}`
422	`mode` 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."}`
422	O 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."}`

Veja também

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.

Produto: se o produto está custom (tem descontos próprios) ou disabled (proibido), vale ele.
Categoria: o mesmo, olhando a categoria do produto.
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:

Chave	Ciclo	Desconto padrão do seller
`semanal`	7 dias	5
`quinzenal`	14 dias	7
`mensal`	30 dias	10
`bimestral`	60 dias	12
`trimestral`	90 dias	15
`quadrimestral`	120 dias	17
`semestral`	180 dias	20
`anual`	365 dias	25

Ler a regra de um seller

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

bash

curl "$BASE_URL/api/v1/admin/recurring/sellers/ec5e10b3-8cb1-43e9-9aa8-964b64eda8de" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra devolvida

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
  }
}

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

Status	Quando	Corpo
500	Id 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

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

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 } }'

Resposta

200Regra gravada

json

{
  "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "mode": "allows",
  "discounts": { "semanal": 5, "mensal": 10, "trimestral": 15 }
}

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`mode` fora da lista	`{"error":"mode_invalid","message":"Modo inválido: use permite, obrigatório ou desativado."}`
422	Chave 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

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

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 } }'

Resposta

200Regra gravada

json

{ "ok": true, "id": "0e7a4b91-2c35-4d68-9f10-8a3b5c6d7e21" }

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`mode` fora da lista	`{"error":"mode_invalid","message":"Modo inválido: use herdar, personalizado ou desativado."}`
422	Chave de frequência desconhecida	`{"error":"discount_invalid","message":"Frequência desconhecida na compra programada."}`
422	Desconto fora de 0 a 99	`{"error":"discount_invalid","message":"O desconto deve estar entre 0 e 99%."}`
500	Id 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

discountsobject

Porcentagem (0 a 99) por chave de frequência. Só é guardado com custom.

Exemplo de requisição

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 } }'

Resposta

200Regra gravada

json

{ "ok": true, "id": "e3a71800-294f-4167-a755-cabedcf094b4", "mode": "custom" }

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
404	Produto inexistente ou id que não é UUID	`{"error":"product_not_found","message":"Produto não encontrado."}`
422	`mode` 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."}`
422	O 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."}`