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

Configuração de compra programada

Define o modo e os descontos de compra programada do seller e de seus produtos.

A configuração decide se e com que desconto o cliente pode programar a recompra de um produto. Funciona em camadas: o produto vence a categoria, que vence o seller. As rotas desta página cuidam do nível do seller e do nível do produto.

Ver configuração do seller

Devolve a regra geral do seller para compra programada (veja a visão geral): o modo e o desconto de cada frequência. Quando o seller nunca salvou nada, a rota devolve os valores padrão (allows e a tabela de descontos padrão), mas nesse caso a regra do seller ainda não está em vigor (veja o aviso desta página).

GET/api/v1/vendor/recurring/configSeller

Modo e descontos de compra programada do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/recurring/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "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 do token.

modestring

allowsmandatorydisabled

Modo geral.

discountsobject

Desconto em % inteiro para cada frequência: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Salvar configuração do seller

Salva a regra geral do seller. Vale para todos os produtos dele, exceto onde a categoria ou o produto tiver regra própria. Devolve a configuração salva.

PUT/api/v1/vendor/recurring/configSeller

Definir modo e descontos de compra programada

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

modestringpadrão: allows

allowsmandatorydisabled

Modo geral. Vazio vale allows.

discountsobject

Desconto inteiro de 0 a 99 (%) por frequência. Só as 8 frequências conhecidas. Omitido = tabela padrão (5, 7, 10, 12, 15, 17, 20, 25).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/recurring/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "allows",
  "discounts": {
    "semanal": 5,
    "quinzenal": 7,
    "mensal": 10,
    "bimestral": 12,
    "trimestral": 15,
    "quadrimestral": 17,
    "semestral": 20,
    "anual": 25
  }
}'

Resposta

200Configuração salva

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "mode": "allows",
  "discounts": {
    "semanal": 5,
    "quinzenal": 7,
    "mensal": 10,
    "bimestral": 12,
    "trimestral": 15,
    "quadrimestral": 17,
    "semestral": 20,
    "anual": 25
  }
}

Campos da resposta

(corpo)object

Mesmos campos do GET.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid json","detail":"..."}`
422	Modo fora da lista. A mensagem vem em português.	`{"error":"mode_invalid","message":"Modo inválido: use permite, obrigatório ou desativado."}`
422	Frequência desconhecida ou desconto fora de 0 a 99.	`{"error":"discount_invalid","message":"Desconto inválido para a compra programada (0 a 99%)."}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Regra de um produto

Define, para um produto seu, se herda a regra geral, usa descontos próprios ou desliga a compra programada. É uma rota antiga mantida por compatibilidade; só mexe na parte de compra programada do produto.

PUT/api/v1/vendor/recurring/products/{id}Seller

Regra de compra programada de um produto do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Produto do seller.

Corpo da requisição

modestring

inheritcustomdisabled

inherit (herda; também aceita allows/mandatory), custom (descontos próprios) ou disabled. custom sem nenhum desconto vira disabled.

discountsobject

Desconto (0 a 99) por frequência, só com custom. Aceita decimais (arredondados para inteiro).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/recurring/products/c7bc3778-2c79-4561-b9d7-979768f364c8" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "custom",
  "discounts": {
    "mensal": 12,
    "trimestral": 18
  }
}'

Resposta

200Regra salva

json

{
  "ok": true,
  "id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
  "mode": "custom"
}

Campos da resposta

okboolean

Sempre true quando salvou.

iduuid

Produto.

modestring

Modo efetivamente gravado (pode diferir do enviado: custom vazio vira disabled).

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
403	O produto não é do seller.	`{"error":"not_owner","message":"Você não tem permissão para alterar a recorrência deste produto."}`
404	Produto inexistente ou `id` malformado.	`{"error":"product_not_found","message":"Produto não encontrado."}`
422	Modo ou desconto inválido, ou o produto já é uma assinatura (`mutually_exclusive`: um produto não é assinatura e compra programada ao mesmo tempo).	`{"error":"mutually_exclusive","message":"Um produto não pode ser assinatura e compra programada ao mesmo tempo."}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Veja também

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

Configuração de compra programada

Define o modo e os descontos de compra programada do seller e de seus produtos.

Ver configuração do seller

GET/api/v1/vendor/recurring/configSeller

Modo e descontos de compra programada do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/recurring/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "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 do token.

modestring

allowsmandatorydisabled

Modo geral.

discountsobject

Desconto em % inteiro para cada frequência: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Salvar configuração do seller

Salva a regra geral do seller. Vale para todos os produtos dele, exceto onde a categoria ou o produto tiver regra própria. Devolve a configuração salva.

PUT/api/v1/vendor/recurring/configSeller

Definir modo e descontos de compra programada

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

modestringpadrão: allows

allowsmandatorydisabled

Modo geral. Vazio vale allows.

discountsobject

Desconto inteiro de 0 a 99 (%) por frequência. Só as 8 frequências conhecidas. Omitido = tabela padrão (5, 7, 10, 12, 15, 17, 20, 25).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/recurring/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "allows",
  "discounts": {
    "semanal": 5,
    "quinzenal": 7,
    "mensal": 10,
    "bimestral": 12,
    "trimestral": 15,
    "quadrimestral": 17,
    "semestral": 20,
    "anual": 25
  }
}'

Resposta

200Configuração salva

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "mode": "allows",
  "discounts": {
    "semanal": 5,
    "quinzenal": 7,
    "mensal": 10,
    "bimestral": 12,
    "trimestral": 15,
    "quadrimestral": 17,
    "semestral": 20,
    "anual": 25
  }
}

Campos da resposta

(corpo)object

Mesmos campos do GET.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid json","detail":"..."}`
422	Modo fora da lista. A mensagem vem em português.	`{"error":"mode_invalid","message":"Modo inválido: use permite, obrigatório ou desativado."}`
422	Frequência desconhecida ou desconto fora de 0 a 99.	`{"error":"discount_invalid","message":"Desconto inválido para a compra programada (0 a 99%)."}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Regra de um produto

PUT/api/v1/vendor/recurring/products/{id}Seller

Regra de compra programada de um produto do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Produto do seller.

Corpo da requisição

modestring

inheritcustomdisabled

inherit (herda; também aceita allows/mandatory), custom (descontos próprios) ou disabled. custom sem nenhum desconto vira disabled.

discountsobject

Desconto (0 a 99) por frequência, só com custom. Aceita decimais (arredondados para inteiro).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/recurring/products/c7bc3778-2c79-4561-b9d7-979768f364c8" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "custom",
  "discounts": {
    "mensal": 12,
    "trimestral": 18
  }
}'

Resposta

200Regra salva

json

{
  "ok": true,
  "id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
  "mode": "custom"
}

Campos da resposta

okboolean

Sempre true quando salvou.

iduuid

Produto.

modestring

Modo efetivamente gravado (pode diferir do enviado: custom vazio vira disabled).

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
403	O produto não é do seller.	`{"error":"not_owner","message":"Você não tem permissão para alterar a recorrência deste produto."}`
404	Produto inexistente ou `id` malformado.	`{"error":"product_not_found","message":"Produto não encontrado."}`
422	Modo ou desconto inválido, ou o produto já é uma assinatura (`mutually_exclusive`: um produto não é assinatura e compra programada ao mesmo tempo).	`{"error":"mutually_exclusive","message":"Um produto não pode ser assinatura e compra programada ao mesmo tempo."}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`