Docs
EntrarCriar conta
Ambiente
Base URLhttps://api.sancopay.com/api/v1
Arquivo para IA
RecorrênciaRequer liberação

Planos

O plano define o valor e a periodicidade das cobranças. Um plano atende várias assinaturas.

POST/recurring/plans

Cria um plano.

Corpo da requisição

CampoTipoDescrição
nameobrigatóriostringNome do plano, até 120 caracteres.
amountobrigatórionumberValor de cada cobrança: mínimo 1.00, máximo 999999.99.
periodicityobrigatóriostringweekly, biweekly, monthly, bimonthly, quarterly, semiannual ou annual.
descriptionopcionalstringDescrição do plano, até 255 caracteres.
default_max_cyclesopcionalintegerCiclos padrão das assinaturas deste plano (1 a 600). Sem valor: sem limite.
referenceopcionalstringIdentificador do seu sistema (até 100); garante a idempotência.
Requisição
curl -X POST "https://api.sancopay.com/api/v1/recurring/plans" \  -H "Authorization: Bearer <TOKEN>" \  -H "Content-Type: application/json" \  -d '{    "name": "Plano Mensal",    "amount": 99.9,    "periodicity": "monthly",    "description": "Acesso mensal à plataforma",    "default_max_cycles": 12,    "reference": "PLANO-MENSAL"  }'
Resposta
{  "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",  "name": "Plano Mensal",  "description": "Acesso mensal à plataforma",  "amount": 99.9,  "periodicity": "monthly",  "periodicity_label": "Mensal",  "default_max_cycles": 12,  "is_active": true,  "reference": "PLANO-MENSAL",  "created_at": "2026-09-18T13:12:40.000000Z",  "updated_at": "2026-09-18T13:12:40.000000Z"}

Demais operações

  • GET/recurring/plansFiltros: is_active (true/false), q (nome), reference, page, per_page. Cada item traz também subscriptions_count e active_subscriptions_count.
  • GET/recurring/plans/{id}Consulta um plano, com os mesmos contadores.
  • PATCH/recurring/plans/{id}Alteração parcial: name, amount, description, default_max_cycles, is_active. Enviar periodicity ou reference responde 422. O novo amount vale para as próximas cobranças das assinaturas que seguem o valor do plano.
  • DEL/recurring/plans/{id}Exclui um plano que nunca teve assinatura (204, sem corpo). Com assinaturas responde 409: desative o plano.

Desativar um plano

Requisição
curl -X PATCH "https://api.sancopay.com/api/v1/recurring/plans/9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40" \  -H "Authorization: Bearer <TOKEN>" \  -H "Content-Type: application/json" \  -d '{    "is_active": false  }'

Um plano desativado continua atendendo as assinaturas existentes, mas não pode ser usado em assinaturas novas.