VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Assinaturas e compras programadas

Termos de assinatura

Cria, versiona e consulta os termos que o cliente aceita ao assinar, e lista os aceites registrados.

Cobrar um cartão todo mês exige consentimento claro. O termo de assinatura é o texto desse consentimento, e cada aceite grava IP, navegador e a impressão digital do texto. As rotas desta página são do seller; a loja tem termos próprios da plataforma, que o seller enxerga mas não edita.

Ordem das rotas

/terms/acceptances é uma rota fixa: não é o id de um termo. Chame-a com o caminho exato.

Respostas embrulhadas

GET e PUT por id e POST devolvem o termo dentro de {"term": ...}; a listagem devolve {"terms": [...]}.

Listar termos

O termo de assinatura é o texto que o cliente aceita ao assinar. Ele é versionado: editar cria uma versão nova e a antiga continua existindo, porque o aceite já registrado aponta para o texto exato que o cliente viu. Lista os termos próprios do seller e os da plataforma.

GET/api/v1/vendor/recurring/termsSeller

Termos de assinatura que o seller pode usar

Cabeçalhos

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

Parâmetros de consulta

include_historystring
1
1 inclui também as versões antigas. Sem isso só as vigentes.

Exemplo de requisição

Resposta

200Termos

Campos da resposta

termsobject[]

Termos, por nome e versão decrescente.

iduuid
Id desta versão do termo.
vendor_iduuid
Seller dono do termo. Omitido nos termos da plataforma.
namestring
Nome do termo.
contentstring
Texto completo.
versioninteger
Número da versão, a partir de 1.
is_currentboolean
Se é a versão vigente.
parent_term_iduuid
Versão anterior. Omitido na primeira.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Criar termo

Cria a versão 1 de um termo do seller. Para usar o termo em um produto, a ligação é feita na configuração do produto.

POST/api/v1/vendor/recurring/termsSeller

Criar um termo de assinatura

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

namestringobrigatório
Nome do termo.
contentstringobrigatório
Texto completo. Até 1 MB de corpo.

Exemplo de requisição

Resposta

201Termo criado

Campos da resposta

termobject

O termo criado.

iduuid
Id desta versão do termo.
vendor_iduuid
Seller dono do termo. Omitido nos termos da plataforma.
namestring
Nome do termo.
contentstring
Texto completo.
versioninteger
Número da versão, a partir de 1.
is_currentboolean
Se é a versão vigente.
parent_term_iduuid
Versão anterior. Omitido na primeira.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid_json","message":"Corpo da requisição inválido."}
422Nome ou texto vazios.{"error":"term_name_required","message":"Informe o nome do termo."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Aceites de termos

Lista os aceites registrados nos termos e assinaturas do seller: cliente, versão, IP, navegador e o SHA-256 do texto exato aceito. É a prova de consentimento.

GET/api/v1/vendor/recurring/terms/acceptancesSeller

Quem aceitou quais termos

Cabeçalhos

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

Parâmetros de consulta

product_iduuid
Só os aceites deste produto.
date_fromstring
A partir de, YYYY-MM-DD ou RFC 3339.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 100. Fora disso vale 50.

Exemplo de requisição

Resposta

200Aceites

Campos da resposta

acceptancesobject[]

Aceites da página.

idstring
Id do aceite.
term_namestring
Termo.
term_versioninteger
Versão aceita.
user_namestring
Cliente.
user_emailstring
E-mail do cliente.
product_iduuid
Produto assinado. Omitido se desconhecido.
product_namestring
Nome do produto.
ipstring
IP do aceite.
user_agentstring
Navegador.
content_sha256string
Impressão digital do texto aceito.
accepted_atstring
Quando aceitou, RFC 3339.
totalinteger
Total de aceites.
pageinteger
Página devolvida.

Erros

StatusQuandoCorpo de exemplo
422date_from com formato inválido.{"error":"date_invalid","message":"Data inicial inválida (use AAAA-MM-DD)."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Ver termo

Devolve uma versão específica de um termo visível ao seller (próprio ou da plataforma).

GET/api/v1/vendor/recurring/terms/{id}Seller

Uma versão de um termo, com o texto

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id do termo (UUID).

Exemplo de requisição

Resposta

200Termo

Campos da resposta

termobject

O termo.

iduuid
Id desta versão do termo.
vendor_iduuid
Seller dono do termo. Omitido nos termos da plataforma.
namestring
Nome do termo.
contentstring
Texto completo.
versioninteger
Número da versão, a partir de 1.
is_currentboolean
Se é a versão vigente.
parent_term_iduuid
Versão anterior. Omitido na primeira.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
404Termo inexistente, de outro seller ou id que não é UUID.{"error":"term_not_found","message":"Termo não encontrado."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Publicar nova versão do termo

Publica uma nova versão (version + 1) de um termo do seller; a versão antiga deixa de ser vigente, mas continua guardada. Os produtos ligados ao termo passam a usar a nova versão. Se nome e texto forem iguais ao atual, nada muda. Só a versão vigente pode ser editada. Termos da plataforma não são editáveis pelo seller.

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

Editar um termo gera uma nova versão

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
Id do termo (UUID).

Corpo da requisição

namestringobrigatório
Nome do termo.
contentstringobrigatório
Texto completo da nova versão. Se nome e texto forem idênticos aos da versão vigente, nada é criado e ela é devolvida como está.

Exemplo de requisição

Resposta

200Nova versão

Campos da resposta

termobject

A versão vigente depois da operação.

iduuid
Id desta versão do termo.
vendor_iduuid
Seller dono do termo. Omitido nos termos da plataforma.
namestring
Nome do termo.
contentstring
Texto completo.
versioninteger
Número da versão, a partir de 1.
is_currentboolean
Se é a versão vigente.
parent_term_iduuid
Versão anterior. Omitido na primeira.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
404Termo inexistente, de outro seller ou id que não é UUID.{"error":"term_not_found","message":"Termo não encontrado."}
403O termo é da plataforma, não do seller.{"error":"not_owner","message":"Você não tem permissão para editar este termo."}
409A versão enviada já foi substituída por uma mais nova.{"error":"term_not_current","message":"Este termo já foi substituído por uma versão mais nova."}
422Nome ou texto vazios.{"error":"term_content_required","message":"Informe o texto do termo."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Veja também

  • Configuração
  • Assinaturas
  • Visão geral
Anterior
Painel e cobranças
Próxima
Assinaturas (painel antigo)
Nesta página
  • Listar termos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar termo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Aceites de termos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver termo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Publicar nova versão do termo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/recurring/terms?include_history=1" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/recurring/terms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Termos de assinatura",
  "content": "Ao assinar você autoriza a cobrança recorrente no cartão informado..."
}'
bash
curl "$BASE_URL/api/v1/vendor/recurring/terms/acceptances?date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/recurring/terms/2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/vendor/recurring/terms/2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Termos de assinatura",
  "content": "Texto revisado..."
}'
json
{
  "terms": [
    {
      "id": "2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Termos de assinatura",
      "content": "Ao assinar você autoriza a cobrança recorrente...",
      "version": 2,
      "is_current": true,
      "parent_term_id": "1a5a3e0d-9e5b-4b47-8a4d-8c8f0e6d6f22",
      "created_at": "2026-10-01T12:00:00Z"
    }
  ]
}
json
{
  "term": {
    "id": "2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "name": "Termos de assinatura",
    "content": "Ao assinar você autoriza a cobrança recorrente...",
    "version": 1,
    "is_current": true,
    "parent_term_id": null,
    "created_at": "2026-10-01T12:00:00Z"
  }
}
json
{
  "acceptances": [
    {
      "id": "e1d5",
      "term_name": "Termos de assinatura",
      "term_version": 2,
      "user_name": "Maria Souza",
      "user_email": "maria.souza@example.com",
      "product_id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
      "product_name": "Café em grãos 1 kg",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "accepted_at": "2026-08-05T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}
json
{
  "term": {
    "id": "2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "name": "Termos de assinatura",
    "content": "Ao assinar você autoriza a cobrança recorrente...",
    "version": 2,
    "is_current": true,
    "parent_term_id": "1a5a3e0d-9e5b-4b47-8a4d-8c8f0e6d6f22",
    "created_at": "2026-10-01T12:00:00Z"
  }
}
json
{
  "term": {
    "id": "2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "name": "Termos de assinatura",
    "content": "Ao assinar você autoriza a cobrança recorrente...",
    "version": 3,
    "is_current": true,
    "parent_term_id": "2b6b4f1e-0f6c-4c58-9b5e-9d9a1f0e7a33",
    "created_at": "2026-10-01T12:00:00Z"
  }
}