API atual/Referência completa/Produtos do seller

Assinatura e compra programada

Lê e grava, por produto, a assinatura com desconto e a compra programada do seller.

Estas rotas dependem do módulo de pagamentos recorrentes. Os message de erro vêm em português. As rotas de gestão das assinaturas já contratadas (cobranças, cancelamentos) pertencem a outra área.

Ler recorrência

GET/api/v1/vendor/products/{id}/recurringSeller

Ler a recorrência do produto

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (ler)

bash

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

Resposta (ler)

200Configuração

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 7,
        "label": "Semanal",
        "enabled": false,
        "discount_percent": 0
      },
      {
        "days": 30,
        "label": "Mensal",
        "enabled": true,
        "discount_percent": 5
      },
      {
        "days": 90,
        "label": "Trimestral",
        "enabled": true,
        "discount_percent": 8
      }
    ],
    "term": null
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "disabled",
      "discounts": {}
    }
  },
  "conflicts": {
    "points_pricing_mode": null,
    "campaign_open": false
  },
  "base_price_cents": 4990
}

Campos da resposta

subscriptionobject

Assinatura.

enabledboolean

Se o produto pode ser assinado.

default_daysinteger

Ciclo sugerido, em dias.

frequenciesarray

Os 7 ciclos possíveis (7, 14, 30, 60, 90, 180, 365 dias), cada um com days, label, enabled, discount_percent.

termobject | null

Termo de assinatura aplicado: id, name, version.

scheduledobject

Compra programada.

modestring

inheritcustomdisabled

Modo do produto: inherit, custom ou disabled.

discountsobject

Desconto por frequência (só em custom), chave = frequência, valor = percentual inteiro.

effectiveobject

O que vale de fato depois de somar produto, categoria e seller: source, mode, discounts.

conflictsobject

Conflito com preço em pontos: points_pricing_mode e campaign_open.

base_price_centsinteger

Preço base do produto em centavos.

Erros (ler)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	Módulo de pagamentos recorrentes desligado, ou o produto não é seu.	`{"error":"not_owner","message":"Você não tem permissão para alterar a recorrência deste produto."}`
404	Produto não existe.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Liga ou desliga a assinatura (o cliente recebe o produto de tempos em tempos com desconto) e a compra programada (o cliente agenda reposições). Os dois blocos são independentes: o que não for enviado não muda. Um bloco enviado substitui o anterior inteiro.

PUT/api/v1/vendor/products/{id}/recurringSeller

Gravar a recorrência do produto

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

subscriptionobject

Bloco de assinatura.

enabledbooleanobrigatório

Liga a assinatura. Exige ao menos uma frequência habilitada.

default_daysinteger

Ciclo padrão; precisa estar habilitado. Se omitido, vale 30 (ou o primeiro habilitado).

frequenciesarray

Ciclos: days (7, 14, 30, 60, 90, 180 ou 365), enabled, discount_percent (0 a 99, passos de 0,5). Ciclo repetido ou fora da lista é recusado.

term_idstring (uuid)

Termo de assinatura a aplicar. Tem de ser da plataforma ou seu.

scheduledobject

Bloco de compra programada.

modestring

inheritcustomdisabled

inherit (herda categoria/seller), custom (descontos próprios) ou disabled. custom sem nenhum desconto vira disabled.

discountsobject

Só em custom. Chaves: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual. Valor 0 a 99.

Exemplo de requisição (gravar)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/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": 5
      },
      {
        "days": 90,
        "enabled": true,
        "discount_percent": 8
      }
    ]
  }
}'

Resposta (gravar)

200Configuração gravada

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 7,
        "label": "Semanal",
        "enabled": false,
        "discount_percent": 0
      },
      {
        "days": 30,
        "label": "Mensal",
        "enabled": true,
        "discount_percent": 5
      },
      {
        "days": 90,
        "label": "Trimestral",
        "enabled": true,
        "discount_percent": 8
      }
    ],
    "term": null
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "disabled",
      "discounts": {}
    }
  },
  "conflicts": {
    "points_pricing_mode": null,
    "campaign_open": false
  },
  "base_price_cents": 4990
}

Campos da resposta

subscriptionobject

Assinatura.

enabledboolean

Se o produto pode ser assinado.

default_daysinteger

Ciclo sugerido, em dias.

frequenciesarray

Os 7 ciclos possíveis (7, 14, 30, 60, 90, 180, 365 dias), cada um com days, label, enabled, discount_percent.

termobject | null

Termo de assinatura aplicado: id, name, version.

scheduledobject

Compra programada.

modestring

inheritcustomdisabled

Modo do produto: inherit, custom ou disabled.

discountsobject

Desconto por frequência (só em custom), chave = frequência, valor = percentual inteiro.

effectiveobject

O que vale de fato depois de somar produto, categoria e seller: source, mode, discounts.

conflictsobject

Conflito com preço em pontos: points_pricing_mode e campaign_open.

base_price_centsinteger

Preço base do produto em centavos.

Erros (gravar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
400	O corpo não é um JSON válido.	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	Regra de negócio: `frequency_invalid`, `frequency_required`, `discount_invalid`, `mode_invalid`, `term_invalid`, `mutually_exclusive` (assinatura e compra programada `custom` juntas).	`{"error":"frequency_required","message":"Habilite ao menos uma frequência para ativar a assinatura."}`
409	Assinatura conflita com preço em pontos do produto.	`{"error":"subscription_conflicts_with_points_pricing","message":"...","pricing":{"mode":"B","campaign_open":false}}`
403	O produto não é seu.	`{"error":"not_owner","message":"..."}`
404	Produto não existe.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Veja também

Produtos do seller: visão geral

API atual/Referência completa/Produtos do seller

Assinatura e compra programada

Lê e grava, por produto, a assinatura com desconto e a compra programada do seller.

Ler recorrência

GET/api/v1/vendor/products/{id}/recurringSeller

Ler a recorrência do produto

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (ler)

bash

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

Resposta (ler)

200Configuração

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 7,
        "label": "Semanal",
        "enabled": false,
        "discount_percent": 0
      },
      {
        "days": 30,
        "label": "Mensal",
        "enabled": true,
        "discount_percent": 5
      },
      {
        "days": 90,
        "label": "Trimestral",
        "enabled": true,
        "discount_percent": 8
      }
    ],
    "term": null
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "disabled",
      "discounts": {}
    }
  },
  "conflicts": {
    "points_pricing_mode": null,
    "campaign_open": false
  },
  "base_price_cents": 4990
}

Campos da resposta

subscriptionobject

Assinatura.

enabledboolean

Se o produto pode ser assinado.

default_daysinteger

Ciclo sugerido, em dias.

frequenciesarray

Os 7 ciclos possíveis (7, 14, 30, 60, 90, 180, 365 dias), cada um com days, label, enabled, discount_percent.

termobject | null

Termo de assinatura aplicado: id, name, version.

scheduledobject

Compra programada.

modestring

inheritcustomdisabled

Modo do produto: inherit, custom ou disabled.

discountsobject

Desconto por frequência (só em custom), chave = frequência, valor = percentual inteiro.

effectiveobject

O que vale de fato depois de somar produto, categoria e seller: source, mode, discounts.

conflictsobject

Conflito com preço em pontos: points_pricing_mode e campaign_open.

base_price_centsinteger

Preço base do produto em centavos.

Erros (ler)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	Módulo de pagamentos recorrentes desligado, ou o produto não é seu.	`{"error":"not_owner","message":"Você não tem permissão para alterar a recorrência deste produto."}`
404	Produto não existe.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Gravar recorrência

PUT/api/v1/vendor/products/{id}/recurringSeller

Gravar a recorrência do produto

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

subscriptionobject

Bloco de assinatura.

enabledbooleanobrigatório

Liga a assinatura. Exige ao menos uma frequência habilitada.

default_daysinteger

Ciclo padrão; precisa estar habilitado. Se omitido, vale 30 (ou o primeiro habilitado).

frequenciesarray

Ciclos: days (7, 14, 30, 60, 90, 180 ou 365), enabled, discount_percent (0 a 99, passos de 0,5). Ciclo repetido ou fora da lista é recusado.

term_idstring (uuid)

Termo de assinatura a aplicar. Tem de ser da plataforma ou seu.

scheduledobject

Bloco de compra programada.

modestring

inheritcustomdisabled

inherit (herda categoria/seller), custom (descontos próprios) ou disabled. custom sem nenhum desconto vira disabled.

discountsobject

Só em custom. Chaves: semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral, anual. Valor 0 a 99.

Exemplo de requisição (gravar)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/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": 5
      },
      {
        "days": 90,
        "enabled": true,
        "discount_percent": 8
      }
    ]
  }
}'

Resposta (gravar)

200Configuração gravada

json

{
  "subscription": {
    "enabled": true,
    "default_days": 30,
    "frequencies": [
      {
        "days": 7,
        "label": "Semanal",
        "enabled": false,
        "discount_percent": 0
      },
      {
        "days": 30,
        "label": "Mensal",
        "enabled": true,
        "discount_percent": 5
      },
      {
        "days": 90,
        "label": "Trimestral",
        "enabled": true,
        "discount_percent": 8
      }
    ],
    "term": null
  },
  "scheduled": {
    "mode": "inherit",
    "discounts": {},
    "effective": {
      "source": "seller",
      "mode": "disabled",
      "discounts": {}
    }
  },
  "conflicts": {
    "points_pricing_mode": null,
    "campaign_open": false
  },
  "base_price_cents": 4990
}

Campos da resposta

subscriptionobject

Assinatura.

enabledboolean

Se o produto pode ser assinado.

default_daysinteger

Ciclo sugerido, em dias.

frequenciesarray

Os 7 ciclos possíveis (7, 14, 30, 60, 90, 180, 365 dias), cada um com days, label, enabled, discount_percent.

termobject | null

Termo de assinatura aplicado: id, name, version.

scheduledobject

Compra programada.

modestring

inheritcustomdisabled

Modo do produto: inherit, custom ou disabled.

discountsobject

Desconto por frequência (só em custom), chave = frequência, valor = percentual inteiro.

effectiveobject

O que vale de fato depois de somar produto, categoria e seller: source, mode, discounts.

conflictsobject

Conflito com preço em pontos: points_pricing_mode e campaign_open.

base_price_centsinteger

Preço base do produto em centavos.

Erros (gravar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
400	O corpo não é um JSON válido.	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	Regra de negócio: `frequency_invalid`, `frequency_required`, `discount_invalid`, `mode_invalid`, `term_invalid`, `mutually_exclusive` (assinatura e compra programada `custom` juntas).	`{"error":"frequency_required","message":"Habilite ao menos uma frequência para ativar a assinatura."}`
409	Assinatura conflita com preço em pontos do produto.	`{"error":"subscription_conflicts_with_points_pricing","message":"...","pricing":{"mode":"B","campaign_open":false}}`
403	O produto não é seu.	`{"error":"not_owner","message":"..."}`
404	Produto não existe.	`{"error":"product_not_found","message":"Produto não encontrado."}`

Veja também

Produtos do seller: visão geral