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

Termos de aceite

Gerencia os termos que o cliente aceita ao assinar, publica novas versões e consulta quem aceitou qual versão.

Quem assina um produto recorrente autoriza cobranças futuras, então a loja precisa de um termo (texto legal) e da prova de que o cliente o aceitou. Estas rotas gerenciam os termos e mostram os aceites: quem aceitou, qual versão, quando e de que IP. Cada termo pertence à plataforma (vale para todos) ou a um seller. Exigem o módulo recurring-payments; ler exige manage_content ou view_content e agir exige manage_content.

Os termos têm versões. Editar não altera o texto aceito no passado: cria a versão seguinte, e as assinaturas existentes passam a apontar para ela. O aceite guarda a versão e um resumo (SHA-256) do texto que o cliente de fato viu.

Listar termos

Devolve a versão corrente de cada termo (ou todas as versões, com include_history), por nome.

GET/api/v1/admin/recurring/termsAdmin

Lista os termos de aceite

Parâmetros de consulta

include_historystring

1

1 inclui também as versões antigas. Qualquer outro valor devolve só a corrente.

Exemplo de requisição

bash

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

Resposta

200Termos devolvidos

json

{
  "terms": [
    {
      "id": "b3a1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Termo de assinatura",
      "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado...",
      "version": 2,
      "is_current": true,
      "parent_term_id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
      "created_at": "2026-08-02T13:00:00Z"
    }
  ]
}

Campos da resposta

termsarray

Termos. Lista vazia quando não há nenhum.

iduuid

Id desta versão do termo.

vendor_iduuid

Seller dono do termo. Ausente em termos da plataforma.

namestring

Nome do termo.

contentstring

Texto completo.

versioninteger

Número da versão, começando em 1.

is_currentboolean

true na versão em vigor.

parent_term_iduuid

Versão que esta substituiu. Ausente na versão 1.

created_atstring

Criação desta versão, RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio ou módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"recurring_failed","message":"Não foi possível concluir a operação. Tente novamente."}`

Criar um termo

Cria a versão 1 de um termo novo. Sem vendor_id o termo é da plataforma; com vendor_id, é daquele seller.

POST/api/v1/admin/recurring/termsAdmin

Cria um termo de aceite

Corpo da requisição

namestringobrigatório

Nome do termo. Espaços nas pontas são removidos.

contentstringobrigatório

Texto completo do termo, até 1 MB de corpo.

vendor_iduuid

Seller dono. Vazio cria um termo da plataforma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/terms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado."
  }'

Resposta

201Termo criado

json

{
  "term": {
    "id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado.",
    "version": 1,
    "is_current": true,
    "created_at": "2026-10-11T23:40:00Z"
  }
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`name` vazio	`{"error":"term_name_required","message":"Informe o nome do termo."}`
422	`content` vazio	`{"error":"term_content_required","message":"Informe o texto do termo."}`
422	`vendor_id` que não é UUID	`{"error":"vendor_invalid","message":"Vendedor inválido."}`

Consultar um termo

GET/api/v1/admin/recurring/terms/{id}Admin

Consulta um termo de aceite

Parâmetros de caminho

iduuidobrigatório

Id da versão do termo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/terms/9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Termo devolvido

json

{
  "term": {
    "id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado.",
    "version": 1,
    "is_current": false,
    "created_at": "2026-10-11T23:40:00Z"
  }
}

Funciona para qualquer versão, inclusive as antigas (is_current: false).

Erros

Status	Quando	Corpo
404	Id que não é UUID ou termo que não existe	`{"error":"term_not_found","message":"Termo não encontrado."}`

Publicar uma nova versão

Edita um termo criando a próxima versão. A versão antiga deixa de ser a corrente (e continua legível), e todo produto que apontava para ela passa a apontar para a nova. Aceites já registrados continuam ligados à versão que o cliente viu. Se name e content forem idênticos aos atuais, nada é criado e o termo atual é devolvido.

PUT/api/v1/admin/recurring/terms/{id}Admin

Publica uma nova versão de um termo

Parâmetros de caminho

iduuidobrigatório

Id da versão corrente do termo.

Corpo da requisição

namestringobrigatório

Nome do termo (reenvie o atual se não mudou).

contentstringobrigatório

Texto completo da nova versão.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/recurring/terms/9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes e pode cancelar quando quiser."
  }'

Resposta

200Nova versão publicada

json

{
  "term": {
    "id": "b3a1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes e pode cancelar quando quiser.",
    "version": 2,
    "is_current": true,
    "parent_term_id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "created_at": "2026-10-11T23:55:00Z"
  }
}

Atenção: o id devolvido é o da nova versão. Guarde-o: o id anterior agora é histórico.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
404	Id inválido ou termo inexistente	`{"error":"term_not_found","message":"Termo não encontrado."}`
409	O id é de uma versão antiga	`{"error":"term_not_current","message":"Este termo já foi substituído por uma versão mais nova."}`
422	`name` ou `content` vazio	`{"error":"term_name_required","message":"Informe o nome do termo."}`

Os textos de message vêm do servidor em português.

Listar aceites

Mostra quem aceitou o quê, com a prova do aceite, do mais recente para o mais antigo.

GET/api/v1/admin/recurring/terms/acceptancesAdmin

Lista os aceites de termos

Parâmetros de consulta

product_iduuid

Só os aceites de assinaturas deste produto.

date_fromstring

Aceites a partir desta data (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 volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/terms/acceptances?date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aceites devolvidos

json

{
  "acceptances": [
    {
      "id": "d4c3b2a1-0f9e-4d8c-7b6a-5e4d3c2b1a09",
      "term_name": "Termo de assinatura",
      "term_version": 2,
      "user_name": "Maria Souza",
      "user_email": "maria.souza@example.com",
      "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "product_name": "Café Especial 500g",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "content_sha256": "3f2c1e0d9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
      "accepted_at": "2026-10-05T14:20:31Z"
    }
  ],
  "total": 1,
  "page": 1
}

Campos da resposta

acceptancesarray

Aceites da página.

totalinteger

Total que casa com os filtros.

pageinteger

Página devolvida.

iduuid

Id do aceite.

term_namestring

Nome do termo aceito.

term_versioninteger

Versão aceita.

user_namestring

Nome de quem aceitou.

user_emailstring

E-mail de quem aceitou.

product_iduuid

Produto da assinatura. Ausente em aceites sem assinatura.

product_namestring

Nome do produto.

ipstring

IP de onde o cliente aceitou.

user_agentstring

Navegador ou app usado.

content_sha256string

Resumo SHA-256 do texto exato aceito. Serve de prova de integridade.

accepted_atstring

Quando foi aceito, RFC 3339.

Erros

Status	Quando	Corpo
422	`date_from` em formato inválido	`{"error":"date_invalid","message":"Data inicial inválida (use AAAA-MM-DD)."}`
401 / 403	Sem token, sem privilégio, módulo desligado	veja as demais páginas

Veja também

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

Termos de aceite

Gerencia os termos que o cliente aceita ao assinar, publica novas versões e consulta quem aceitou qual versão.

Listar termos

Devolve a versão corrente de cada termo (ou todas as versões, com include_history), por nome.

GET/api/v1/admin/recurring/termsAdmin

Lista os termos de aceite

Parâmetros de consulta

include_historystring

1

1 inclui também as versões antigas. Qualquer outro valor devolve só a corrente.

Exemplo de requisição

bash

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

Resposta

200Termos devolvidos

json

{
  "terms": [
    {
      "id": "b3a1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Termo de assinatura",
      "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado...",
      "version": 2,
      "is_current": true,
      "parent_term_id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
      "created_at": "2026-08-02T13:00:00Z"
    }
  ]
}

Campos da resposta

termsarray

Termos. Lista vazia quando não há nenhum.

iduuid

Id desta versão do termo.

vendor_iduuid

Seller dono do termo. Ausente em termos da plataforma.

namestring

Nome do termo.

contentstring

Texto completo.

versioninteger

Número da versão, começando em 1.

is_currentboolean

true na versão em vigor.

parent_term_iduuid

Versão que esta substituiu. Ausente na versão 1.

created_atstring

Criação desta versão, RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio ou módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"recurring_failed","message":"Não foi possível concluir a operação. Tente novamente."}`

Criar um termo

Cria a versão 1 de um termo novo. Sem vendor_id o termo é da plataforma; com vendor_id, é daquele seller.

POST/api/v1/admin/recurring/termsAdmin

Cria um termo de aceite

Corpo da requisição

namestringobrigatório

Nome do termo. Espaços nas pontas são removidos.

contentstringobrigatório

Texto completo do termo, até 1 MB de corpo.

vendor_iduuid

Seller dono. Vazio cria um termo da plataforma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/terms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado."
  }'

Resposta

201Termo criado

json

{
  "term": {
    "id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado.",
    "version": 1,
    "is_current": true,
    "created_at": "2026-10-11T23:40:00Z"
  }
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
422	`name` vazio	`{"error":"term_name_required","message":"Informe o nome do termo."}`
422	`content` vazio	`{"error":"term_content_required","message":"Informe o texto do termo."}`
422	`vendor_id` que não é UUID	`{"error":"vendor_invalid","message":"Vendedor inválido."}`

Consultar um termo

GET/api/v1/admin/recurring/terms/{id}Admin

Consulta um termo de aceite

Parâmetros de caminho

iduuidobrigatório

Id da versão do termo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/terms/9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Termo devolvido

json

{
  "term": {
    "id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes no cartão informado.",
    "version": 1,
    "is_current": false,
    "created_at": "2026-10-11T23:40:00Z"
  }
}

Funciona para qualquer versão, inclusive as antigas (is_current: false).

Erros

Status	Quando	Corpo
404	Id que não é UUID ou termo que não existe	`{"error":"term_not_found","message":"Termo não encontrado."}`

Publicar uma nova versão

PUT/api/v1/admin/recurring/terms/{id}Admin

Publica uma nova versão de um termo

Parâmetros de caminho

iduuidobrigatório

Id da versão corrente do termo.

Corpo da requisição

namestringobrigatório

Nome do termo (reenvie o atual se não mudou).

contentstringobrigatório

Texto completo da nova versão.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/recurring/terms/9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes e pode cancelar quando quiser."
  }'

Resposta

200Nova versão publicada

json

{
  "term": {
    "id": "b3a1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Termo de assinatura",
    "content": "Ao assinar, você autoriza cobranças recorrentes e pode cancelar quando quiser.",
    "version": 2,
    "is_current": true,
    "parent_term_id": "9a8b7c6d-5e4f-4321-8765-0a9b8c7d6e5f",
    "created_at": "2026-10-11T23:55:00Z"
  }
}

Atenção: o id devolvido é o da nova versão. Guarde-o: o id anterior agora é histórico.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid_json","message":"Corpo da requisição inválido."}`
404	Id inválido ou termo inexistente	`{"error":"term_not_found","message":"Termo não encontrado."}`
409	O id é de uma versão antiga	`{"error":"term_not_current","message":"Este termo já foi substituído por uma versão mais nova."}`
422	`name` ou `content` vazio	`{"error":"term_name_required","message":"Informe o nome do termo."}`

Os textos de message vêm do servidor em português.

Listar aceites

Mostra quem aceitou o quê, com a prova do aceite, do mais recente para o mais antigo.

GET/api/v1/admin/recurring/terms/acceptancesAdmin

Lista os aceites de termos

Parâmetros de consulta

product_iduuid

Só os aceites de assinaturas deste produto.

date_fromstring

Aceites a partir desta data (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 volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/terms/acceptances?date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aceites devolvidos

json

{
  "acceptances": [
    {
      "id": "d4c3b2a1-0f9e-4d8c-7b6a-5e4d3c2b1a09",
      "term_name": "Termo de assinatura",
      "term_version": 2,
      "user_name": "Maria Souza",
      "user_email": "maria.souza@example.com",
      "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "product_name": "Café Especial 500g",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "content_sha256": "3f2c1e0d9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
      "accepted_at": "2026-10-05T14:20:31Z"
    }
  ],
  "total": 1,
  "page": 1
}

Campos da resposta

acceptancesarray

Aceites da página.

totalinteger

Total que casa com os filtros.

pageinteger

Página devolvida.

iduuid

Id do aceite.

term_namestring

Nome do termo aceito.

term_versioninteger

Versão aceita.

user_namestring

Nome de quem aceitou.

user_emailstring

E-mail de quem aceitou.

product_iduuid

Produto da assinatura. Ausente em aceites sem assinatura.

product_namestring

Nome do produto.

ipstring

IP de onde o cliente aceitou.

user_agentstring

Navegador ou app usado.

content_sha256string

Resumo SHA-256 do texto exato aceito. Serve de prova de integridade.

accepted_atstring

Quando foi aceito, RFC 3339.

Erros

Status	Quando	Corpo
422	`date_from` em formato inválido	`{"error":"date_invalid","message":"Data inicial inválida (use AAAA-MM-DD)."}`
401 / 403	Sem token, sem privilégio, módulo desligado	veja as demais páginas