Criar Plano
POST/v2/recurrences/plans
Cria um novo plano de cobrança recorrente no catálogo da loja.
Cabeçalhos (Headers)
| Cabeçalho | Valor | Obrigatório | Descrição |
|---|---|---|---|
Authorization | Bearer <token> | Sim | Token JWT Bearer autenticado |
Content-Type | application/json | Sim | Tipo de mídia |
Idempotency-Key | <guid_ou_string> | Sim | Chave para prevenção de duplicidade |
Parâmetros
Exemplo de requisição
{
"externalId": "PLANO-GOLD-01",
"name": "Plano Premium Mensal",
"description": "Acesso a todos os recursos",
"amount": 49.9,
"currency": "BRL",
"intervalUnit": "MONTH",
"intervalCount": 1,
"billingType": "PREPAID",
"trialDays": 0,
"gracePeriodDays": 3,
"maxRetryAttempts": 3,
"retryIntervalDays": 1,
"isPublic": true
}Resposta (201 Created)
Exemplo de resposta
{
"id": "f5e4d3c2-1b0a-9f8e-7d6c-5b4a3f2e1d0c",
"externalId": "PLANO-GOLD-01",
"name": "Plano Premium Mensal",
"description": "Acesso a todos os recursos",
"amount": 49.9,
"currency": "BRL",
"intervalUnit": "MONTH",
"intervalCount": 1,
"billingType": "PREPAID",
"trialDays": 0,
"gracePeriodDays": 3,
"maxRetryAttempts": 3,
"retryIntervalDays": 1,
"isPublic": true,
"version": 1,
"status": "ACTIVE",
"createdOn": "2026-09-09T10:00:00Z",
"lastModifiedOn": "2026-09-09T10:00:00Z"
}Próximos Passos
Após cadastrar o plano, utilize o id retornado para:
- Vincular a Assinaturas Diretas: Utilize este identificador no campo
RecurrencePlanIdao Criar Assinatura. - Criar Sessões de Checkout Público: Gere links de pagamento compartilháveis informando este plano no campo
planIdao Criar Sessão de Checkout. - Gerenciar o Catálogo: Consulte todos os planos ativos em Listar Planos ou edite as regras em Atualizar Plano.
Erros
As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.
Ver validações observadas em homologação
Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Idempotency-Key": [
"The idempotencyKey field is required."
]
},
"traceId": "00-e21ec07f0a61b9a22aa27e8b3ddb42ff-c121aba64c46fae9-00"
}Observado em homologação
Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.
[
{
"tag": "Name",
"description": "Name é obrigatório."
},
{
"tag": "Amount",
"description": "Amount deve ser maior que zero."
}
]Campos da resposta de erro
A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.
