API atual/Guia rápido/Preço e estoque do produto

Recorrência do produto

Lê e grava a configuração de assinatura e de compra programada de um produto, com ciclos, descontos e a herança produto, categoria e vendedor.

A recorrência permite que o cliente compre o mesmo produto de novo sem refazer o pedido. Há dois jeitos, e um produto pode usar um só deles:

Assinatura: o cliente assina e recebe o produto a cada ciclo (semanal, mensal, anual...), com um desconto por ciclo e um termo de aceite.
Compra programada: o cliente agenda compras futuras do produto, também com desconto por periodicidade.

Esta página cobre a configuração de um produto: ligar ou desligar a assinatura, escolher os ciclos e descontos e definir como a compra programada é herdada ou personalizada. As assinaturas e compras programadas dos clientes são outro assunto.

Como a configuração é resolvida

A assinatura é uma configuração do próprio produto: ligada ou desligada, com um conjunto de ciclos.

A compra programada segue uma escada de herança. O que vale para o produto é o primeiro nível que decidir:

Produto: se o modo do produto é custom ou disabled, ele decide.
Categoria: se o produto está em modo inherit, vale a configuração da categoria (quando ela é custom ou disabled).
Vendedor (seller): por fim, a configuração do vendedor dono do produto. Sem configuração de vendedor, a compra programada fica desativada.

O resultado aparece no campo scheduled.effective, com a source (product, category, seller ou none).

Modos da compra programada (`scheduled.mode`)

Modo	Significado
`inherit`	O produto não decide: vale a categoria, depois o vendedor. É o padrão.
`custom`	O produto define os próprios descontos por periodicidade. Sem nenhum desconto informado, é gravado como `disabled`.
`disabled`	A compra programada fica desativada para este produto, mesmo que a categoria ou o vendedor a permitam.

Na entrada, os valores allows e mandatory (os modos do vendedor) são aceitos e tratados como inherit.

Ciclos da assinatura

Os ciclos são fixos. Cada um tem um número de dias:

`days`	Rótulo
7	Semanal
14	Quinzenal
30	Mensal
60	Bimestral
90	Trimestral
180	Semestral
365	Anual

A resposta sempre lista os sete, com enabled marcando os que o produto oferece.

Periodicidades da compra programada (`discounts`)

As chaves de discounts são os nomes: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral e anual. O valor é o desconto em porcentagem inteira (0 a 99); decimais são arredondados.

Consultar a configuração

GET/api/v1/admin/products/{id}/recurringAdmin

Consulta a configuração de recorrência de um produto

Devolve a configuração de assinatura, a de compra programada (própria e efetiva) e os conflitos. Exige o recurso de recorrência ligado e o privilégio view_content ou manage_content.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração do produto

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      { "days": 7, "label": "Semanal", "enabled": false, "discount_percent": 0 },
      { "days": 14, "label": "Quinzenal", "enabled": false, "discount_percent": 0 },
      { "days": 30, "label": "Mensal", "enabled": true, "discount_percent": 10 },
      { "days": 60, "label": "Bimestral", "enabled": true, "discount_percent": 12.5 },
      { "days": 90, "label": "Trimestral", "enabled": false, "discount_percent": 0 },
      { "days": 180, "label": "Semestral", "enabled": false, "discount_percent": 0 },
      { "days": 365, "label": "Anual", "enabled": false, "discount_percent": 0 }
    ],
    "term": { "id": "3f5e9a10-7b2c-4d8e-a6f1-0c9b8d7e6a54", "name": "Termo padrão", "version": 2 }
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "allows",
      "discounts": { "semanal": 5, "quinzenal": 7, "mensal": 10, "bimestral": 12, "trimestral": 15, "quadrimestral": 17, "semestral": 20, "anual": 25 }
    }
  },
  "conflicts": { "points_pricing_mode": null, "campaign_open": false },
  "base_price_cents": 4990
}

Response fields

subscriptionobject

A assinatura do produto.

enabledboolean

Se o produto é vendido por assinatura.

default_daysinteger

Ciclo padrão, em dias. Quando nunca foi configurado, 30.

frequenciesarray

Os sete ciclos, sempre completos e em ordem crescente de dias. Cada item tem days, label (em português), enabled e discount_percent (de 0 a 99, em passos de 0,5).

termobject

O termo de aceite que o cliente aprova ao assinar (id, name, version). Ausente (null) quando o produto não tem termo.

scheduledobject

A compra programada do produto.

modestring

inheritcustomdisabled

O modo definido no próprio produto.

discountsobject

Descontos do produto por periodicidade. Só tem conteúdo no modo custom.

effectiveobject

O que realmente vale para o produto depois da herança.

sourcestring

productcategorysellernone

De onde veio a configuração efetiva.

modestring

Modo efetivo (custom, disabled, ou o modo do vendedor: allows ou mandatory).

discountsobject

Descontos efetivos por periodicidade. Quando o vendedor não definiu os dele, vale a tabela padrão da plataforma, mostrada acima.

conflictsobject

Estado da precificação em pontos do produto, quando a loja usa o recurso de pontos. Sem ele, points_pricing_mode é null e campaign_open é false.

points_pricing_modestring

Modo de precificação em pontos do produto (A, B ou C).

campaign_openboolean

true quando há uma campanha de pontos aberta para o produto.

base_price_centsinteger

Preço atual do produto em centavos, para você calcular o valor com desconto.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	O recurso de recorrência está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	Sem `view_content` nem `manage_content`.	`{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}`
404	Produto inexistente, na lixeira, ou id que não é UUID.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Gravar a configuração

PUT/api/v1/admin/products/{id}/recurringAdmin

Salva a configuração de recorrência de um produto

Grava a assinatura e/ou a compra programada do produto e devolve a configuração completa já gravada (o mesmo formato da consulta). Exige o recurso de recorrência ligado e o privilégio manage_content. Cada bloco enviado substitui o bloco correspondente; o bloco ausente fica como está.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

subscriptionobject

Assinatura. Quando presente, substitui toda a configuração de assinatura.

enabledbooleanobrigatório

true vende o produto por assinatura. Exige ao menos um ciclo habilitado.

default_daysintegerpadrão: 30

Ciclo padrão, em dias. Precisa ser um dos ciclos habilitados. Se omitido (ou 0) e o 30 não estiver habilitado, a plataforma usa o primeiro ciclo habilitado.

frequenciesarray

Os ciclos oferecidos. Pode mandar só os que importam: os ausentes ficam desabilitados.

daysintegerobrigatório

714306090180365

Número de dias do ciclo. Não pode se repetir.

enabledboolean

Se o ciclo é oferecido.

discount_percentnumber

Desconto do ciclo, de 0 a 99, em passos de 0,5.

term_iduuid

Termo de aceite da assinatura. Precisa ser um termo da plataforma ou do vendedor dono do produto. Omitido, o produto fica sem termo.

scheduledobject

Compra programada do produto. Quando presente, substitui a configuração de compra programada.

modestringpadrão: inherit

inheritcustomdisabled

Modo. allows e mandatory são aceitos e tratados como inherit.

discountsobject

Descontos por periodicidade (semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual), em porcentagem de 0 a 99. Só são guardados no modo custom.

Exemplo de requisição (ligar a assinatura)

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 30,
        "enabled": true,
        "discount_percent": 10
      },
      {
        "days": 60,
        "enabled": true,
        "discount_percent": 12.5
      }
    ],
    "term_id": "3f5e9a10-7b2c-4d8e-a6f1-0c9b8d7e6a54"
  }
}'

Para uma compra programada personalizada:

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled": {
    "mode": "custom",
    "discounts": {
      "mensal": 10,
      "trimestral": 15
    }
  }
}'

Resposta

A resposta é a mesma da consulta, com 200, refletindo o que foi gravado.

Erros

Os erros desta rota usam o formato {"error": "<código>", "message": "<texto em português>"}; o message é devolvido em português pelo servidor.

Status	Código (`error`)	Quando
400	`invalid_json`	Corpo que não é um JSON válido.
403	`module_disabled`	O recurso de recorrência está desligado na loja.
403	`insufficient privileges`	Sem `manage_content`.
404	`product_not_found`	Produto inexistente, na lixeira, ou id que não é UUID.
409	`subscription_conflicts_with_points_pricing`	Ligar a assinatura num produto com precificação em pontos `B` ou `C`, ou com campanha de pontos aberta. O corpo inclui `pricing` (`mode`, `campaign_open`).
422	`frequency_invalid`	`days` fora de 7, 14, 30, 60, 90, 180, 365, ciclo repetido, ou `default_days` que não está habilitado.
422	`frequency_required`	`enabled: true` sem nenhum ciclo habilitado.
422	`discount_invalid`	Desconto de assinatura fora de 0 a 99 ou fora de passos de 0,5; periodicidade desconhecida ou desconto fora de 0 a 99 na compra programada.
422	`mode_invalid`	`scheduled.mode` diferente de `inherit`, `custom`, `disabled` (e de `allows`, `mandatory`).
422	`term_invalid`	`term_id` que não é UUID, não existe ou é de outro vendedor.
422	`mutually_exclusive`	O produto ficaria assinatura e compra programada `custom` ao mesmo tempo.
500	`recurring_failed`	Falha inesperada.

Veja também

Preço e estoque do produto: visão geral e o mapa das rotas.
Embalagem de envio
Consultar produto
Atualizar produto

API atual/Guia rápido/Preço e estoque do produto

Recorrência do produto

Lê e grava a configuração de assinatura e de compra programada de um produto, com ciclos, descontos e a herança produto, categoria e vendedor.

A recorrência permite que o cliente compre o mesmo produto de novo sem refazer o pedido. Há dois jeitos, e um produto pode usar um só deles:

Assinatura: o cliente assina e recebe o produto a cada ciclo (semanal, mensal, anual...), com um desconto por ciclo e um termo de aceite.
Compra programada: o cliente agenda compras futuras do produto, também com desconto por periodicidade.

Como a configuração é resolvida

A assinatura é uma configuração do próprio produto: ligada ou desligada, com um conjunto de ciclos.

A compra programada segue uma escada de herança. O que vale para o produto é o primeiro nível que decidir:

Produto: se o modo do produto é custom ou disabled, ele decide.
Categoria: se o produto está em modo inherit, vale a configuração da categoria (quando ela é custom ou disabled).
Vendedor (seller): por fim, a configuração do vendedor dono do produto. Sem configuração de vendedor, a compra programada fica desativada.

O resultado aparece no campo scheduled.effective, com a source (product, category, seller ou none).

Modos da compra programada (`scheduled.mode`)

Modo	Significado
`inherit`	O produto não decide: vale a categoria, depois o vendedor. É o padrão.
`custom`	O produto define os próprios descontos por periodicidade. Sem nenhum desconto informado, é gravado como `disabled`.
`disabled`	A compra programada fica desativada para este produto, mesmo que a categoria ou o vendedor a permitam.

Na entrada, os valores allows e mandatory (os modos do vendedor) são aceitos e tratados como inherit.

Ciclos da assinatura

Os ciclos são fixos. Cada um tem um número de dias:

`days`	Rótulo
7	Semanal
14	Quinzenal
30	Mensal
60	Bimestral
90	Trimestral
180	Semestral
365	Anual

A resposta sempre lista os sete, com enabled marcando os que o produto oferece.

Periodicidades da compra programada (`discounts`)

Consultar a configuração

GET/api/v1/admin/products/{id}/recurringAdmin

Consulta a configuração de recorrência de um produto

Devolve a configuração de assinatura, a de compra programada (própria e efetiva) e os conflitos. Exige o recurso de recorrência ligado e o privilégio view_content ou manage_content.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração do produto

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      { "days": 7, "label": "Semanal", "enabled": false, "discount_percent": 0 },
      { "days": 14, "label": "Quinzenal", "enabled": false, "discount_percent": 0 },
      { "days": 30, "label": "Mensal", "enabled": true, "discount_percent": 10 },
      { "days": 60, "label": "Bimestral", "enabled": true, "discount_percent": 12.5 },
      { "days": 90, "label": "Trimestral", "enabled": false, "discount_percent": 0 },
      { "days": 180, "label": "Semestral", "enabled": false, "discount_percent": 0 },
      { "days": 365, "label": "Anual", "enabled": false, "discount_percent": 0 }
    ],
    "term": { "id": "3f5e9a10-7b2c-4d8e-a6f1-0c9b8d7e6a54", "name": "Termo padrão", "version": 2 }
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "allows",
      "discounts": { "semanal": 5, "quinzenal": 7, "mensal": 10, "bimestral": 12, "trimestral": 15, "quadrimestral": 17, "semestral": 20, "anual": 25 }
    }
  },
  "conflicts": { "points_pricing_mode": null, "campaign_open": false },
  "base_price_cents": 4990
}

Response fields

subscriptionobject

A assinatura do produto.

enabledboolean

Se o produto é vendido por assinatura.

default_daysinteger

Ciclo padrão, em dias. Quando nunca foi configurado, 30.

frequenciesarray

Os sete ciclos, sempre completos e em ordem crescente de dias. Cada item tem days, label (em português), enabled e discount_percent (de 0 a 99, em passos de 0,5).

termobject

O termo de aceite que o cliente aprova ao assinar (id, name, version). Ausente (null) quando o produto não tem termo.

scheduledobject

A compra programada do produto.

modestring

inheritcustomdisabled

O modo definido no próprio produto.

discountsobject

Descontos do produto por periodicidade. Só tem conteúdo no modo custom.

effectiveobject

O que realmente vale para o produto depois da herança.

sourcestring

productcategorysellernone

De onde veio a configuração efetiva.

modestring

Modo efetivo (custom, disabled, ou o modo do vendedor: allows ou mandatory).

discountsobject

Descontos efetivos por periodicidade. Quando o vendedor não definiu os dele, vale a tabela padrão da plataforma, mostrada acima.

conflictsobject

Estado da precificação em pontos do produto, quando a loja usa o recurso de pontos. Sem ele, points_pricing_mode é null e campaign_open é false.

points_pricing_modestring

Modo de precificação em pontos do produto (A, B ou C).

campaign_openboolean

true quando há uma campanha de pontos aberta para o produto.

base_price_centsinteger

Preço atual do produto em centavos, para você calcular o valor com desconto.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	O recurso de recorrência está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	Sem `view_content` nem `manage_content`.	`{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}`
404	Produto inexistente, na lixeira, ou id que não é UUID.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Gravar a configuração

PUT/api/v1/admin/products/{id}/recurringAdmin

Salva a configuração de recorrência de um produto

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

subscriptionobject

Assinatura. Quando presente, substitui toda a configuração de assinatura.

enabledbooleanobrigatório

true vende o produto por assinatura. Exige ao menos um ciclo habilitado.

default_daysintegerpadrão: 30

Ciclo padrão, em dias. Precisa ser um dos ciclos habilitados. Se omitido (ou 0) e o 30 não estiver habilitado, a plataforma usa o primeiro ciclo habilitado.

frequenciesarray

Os ciclos oferecidos. Pode mandar só os que importam: os ausentes ficam desabilitados.

daysintegerobrigatório

714306090180365

Número de dias do ciclo. Não pode se repetir.

enabledboolean

Se o ciclo é oferecido.

discount_percentnumber

Desconto do ciclo, de 0 a 99, em passos de 0,5.

term_iduuid

Termo de aceite da assinatura. Precisa ser um termo da plataforma ou do vendedor dono do produto. Omitido, o produto fica sem termo.

scheduledobject

Compra programada do produto. Quando presente, substitui a configuração de compra programada.

modestringpadrão: inherit

inheritcustomdisabled

Modo. allows e mandatory são aceitos e tratados como inherit.

discountsobject

Descontos por periodicidade (semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual), em porcentagem de 0 a 99. Só são guardados no modo custom.

Exemplo de requisição (ligar a assinatura)

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 30,
        "enabled": true,
        "discount_percent": 10
      },
      {
        "days": 60,
        "enabled": true,
        "discount_percent": 12.5
      }
    ],
    "term_id": "3f5e9a10-7b2c-4d8e-a6f1-0c9b8d7e6a54"
  }
}'

Para uma compra programada personalizada:

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/recurring" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled": {
    "mode": "custom",
    "discounts": {
      "mensal": 10,
      "trimestral": 15
    }
  }
}'

Resposta

A resposta é a mesma da consulta, com 200, refletindo o que foi gravado.

Erros

Os erros desta rota usam o formato {"error": "<código>", "message": "<texto em português>"}; o message é devolvido em português pelo servidor.

Status	Código (`error`)	Quando
400	`invalid_json`	Corpo que não é um JSON válido.
403	`module_disabled`	O recurso de recorrência está desligado na loja.
403	`insufficient privileges`	Sem `manage_content`.
404	`product_not_found`	Produto inexistente, na lixeira, ou id que não é UUID.
409	`subscription_conflicts_with_points_pricing`	Ligar a assinatura num produto com precificação em pontos `B` ou `C`, ou com campanha de pontos aberta. O corpo inclui `pricing` (`mode`, `campaign_open`).
422	`frequency_invalid`	`days` fora de 7, 14, 30, 60, 90, 180, 365, ciclo repetido, ou `default_days` que não está habilitado.
422	`frequency_required`	`enabled: true` sem nenhum ciclo habilitado.
422	`discount_invalid`	Desconto de assinatura fora de 0 a 99 ou fora de passos de 0,5; periodicidade desconhecida ou desconto fora de 0 a 99 na compra programada.
422	`mode_invalid`	`scheduled.mode` diferente de `inherit`, `custom`, `disabled` (e de `allows`, `mandatory`).
422	`term_invalid`	`term_id` que não é UUID, não existe ou é de outro vendedor.
422	`mutually_exclusive`	O produto ficaria assinatura e compra programada `custom` ao mesmo tempo.
500	`recurring_failed`	Falha inesperada.

Veja também

Preço e estoque do produto: visão geral e o mapa das rotas.
Embalagem de envio
Consultar produto
Atualizar produto