API atual/Referência completa/Assinaturas e compras programadas

Oferta de recorrência

Descobre se um produto aceita assinatura ou compra programada, com descontos, e lê os termos.

Antes de oferecer "Assinar", consulte o que a loja permite para o produto. As duas rotas são públicas, mas dependem do módulo recurring-payments: sem ele respondem 403 module_disabled.

O que o produto oferece

Resolve o que a loja oferece para um produto: assinatura, compra programada ou nada. A regra é em cascata (produto, depois categoria, depois seller) e a primeira camada que define algo vale. Use para decidir se a página do produto mostra "Assinar" ou "Receber todo mês" e com que desconto por frequência.

GET/api/v1/storefront/recurring/configPública

Se o produto aceita assinatura ou compra programada, e com quais descontos

Parâmetros de consulta

product_iduuidobrigatório

Produto a consultar.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recurring/config?product_id=c3f92551-9dda-4fc7-b518-353d1c4e4035"

Resposta

200Produto com recorrência

json

{
  "enabled": true,
  "config": {
    "source": "seller",
    "mode": "allows",
    "discounts": {
      "semanal": 5,
      "quinzenal": 7,
      "mensal": 10,
      "bimestral": 12,
      "trimestral": 15,
      "quadrimestral": 17,
      "semestral": 20,
      "anual": 25
    }
  }
}

200Produto sem recorrência

json

{
  "enabled": false
}

Campos da resposta

enabledboolean

false quando o produto não oferece nenhuma recorrência (ou o product_id não é um UUID válido).

configobject

Só quando enabled é true.

sourcestring

productcategoryseller

De onde veio a regra.

modestring

subscriptioncustomallowsmandatory

subscription: o produto é de assinatura. custom: regra própria do produto ou da categoria. allows/mandatory: regra do seller, recorrência opcional ou obrigatória.

discountsobject

Desconto em porcentagem inteira por frequência: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual. Em produto de assinatura, só aparecem os ciclos habilitados. Padrão da loja quando o seller não definiu: 5, 7, 10, 12, 15, 17, 20 e 25%.

Erros

Status	Quando	Corpo de exemplo
400	`product_id` ausente.	`{"error":"product_id required"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`

Termos da assinatura

Devolve o texto dos termos que o cliente aceita ao assinar. Mostre-o antes do botão de confirmar. Ao criar a assinatura, a plataforma registra o aceite dos termos vigentes junto com o IP e o navegador do cliente.

GET/api/v1/storefront/recurring/terms/{productId}Pública

Texto dos termos vigentes de assinatura de um produto

Parâmetros de caminho

productIduuidobrigatório

Produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recurring/terms/c3f92551-9dda-4fc7-b518-353d1c4e4035"

Resposta

200Termos

json

{
  "id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "version": 2,
  "content": "A assinatura é renovada automaticamente a cada ciclo até ser cancelada...",
  "is_current": true
}

Campos da resposta

iduuid

Id da versão dos termos.

product_iduuid

Produto.

versioninteger

Número da versão.

contentstring

Texto dos termos, em português.

is_currentboolean

true para a versão vigente.

Erros

Status	Quando	Corpo de exemplo
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	O produto não tem termos publicados.	`{"error":"no terms"}`

Veja também

API atual/Referência completa/Assinaturas e compras programadas

Oferta de recorrência

Descobre se um produto aceita assinatura ou compra programada, com descontos, e lê os termos.

Antes de oferecer "Assinar", consulte o que a loja permite para o produto. As duas rotas são públicas, mas dependem do módulo recurring-payments: sem ele respondem 403 module_disabled.

O que o produto oferece

GET/api/v1/storefront/recurring/configPública

Se o produto aceita assinatura ou compra programada, e com quais descontos

Parâmetros de consulta

product_iduuidobrigatório

Produto a consultar.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recurring/config?product_id=c3f92551-9dda-4fc7-b518-353d1c4e4035"

Resposta

200Produto com recorrência

json

{
  "enabled": true,
  "config": {
    "source": "seller",
    "mode": "allows",
    "discounts": {
      "semanal": 5,
      "quinzenal": 7,
      "mensal": 10,
      "bimestral": 12,
      "trimestral": 15,
      "quadrimestral": 17,
      "semestral": 20,
      "anual": 25
    }
  }
}

200Produto sem recorrência

json

{
  "enabled": false
}

Campos da resposta

enabledboolean

false quando o produto não oferece nenhuma recorrência (ou o product_id não é um UUID válido).

configobject

Só quando enabled é true.

sourcestring

productcategoryseller

De onde veio a regra.

modestring

subscriptioncustomallowsmandatory

subscription: o produto é de assinatura. custom: regra própria do produto ou da categoria. allows/mandatory: regra do seller, recorrência opcional ou obrigatória.

discountsobject

Erros

Status	Quando	Corpo de exemplo
400	`product_id` ausente.	`{"error":"product_id required"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`

Termos da assinatura

GET/api/v1/storefront/recurring/terms/{productId}Pública

Texto dos termos vigentes de assinatura de um produto

Parâmetros de caminho

productIduuidobrigatório

Produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/recurring/terms/c3f92551-9dda-4fc7-b518-353d1c4e4035"

Resposta

200Termos

json

{
  "id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "version": 2,
  "content": "A assinatura é renovada automaticamente a cada ciclo até ser cancelada...",
  "is_current": true
}

Campos da resposta

iduuid

Id da versão dos termos.

product_iduuid

Produto.

versioninteger

Número da versão.

contentstring

Texto dos termos, em português.

is_currentboolean

true para a versão vigente.

Erros

Status	Quando	Corpo de exemplo
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	O produto não tem termos publicados.	`{"error":"no terms"}`