Criar Assinatura
Cria uma assinatura ativa, processa a cobrança imediata do primeiro ciclo (salvo se houver período de teste/trial) e agenda os ciclos futuros no motor diário.
Pré-requisitos para Implementação
Antes de criar uma assinatura, certifique-se de possuir os seguintes recursos cadastrados:
- Plano: Cadastre o plano em Criar Plano e utilize o
idretornado emRecurrencePlanId. - Cliente: Cadastre o pagador em Criar Cliente e utilize o
idretornado emPaymentCustomerId. - Meio de Pagamento (Opcional): Para debitar em um cartão específico, tokenize o cartão em Vincular Meio de Pagamento e informe o
idemPaymentCustomerPaymentMethodId. Se este campo for omitido, o sistema utilizará automaticamente o Meio de Pagamento Padrão do cliente.
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 de idempotência |
Parâmetros
{
"externalId": "SUB-1002",
"paymentCustomerId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"recurrencePlanId": "f5e4d3c2-1b0a-9f8e-7d6c-5b4a3f2e1d0c",
"paymentCustomerPaymentMethodId": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
}Resposta (201 Created)
{
"id": "e1f2a3b4-5c6d-7e8f-9a01-234567890abc",
"externalId": "SUB-1002",
"status": "ACTIVE",
"currentPeriodStartsOn": "2026-09-09T10:15:00Z",
"currentPeriodEndsOn": "2026-10-09T10:15:00Z",
"nextBillingOn": "2026-10-09T10:15:00Z",
"customer": {
"id": "a1b2c3d4-...",
"name": "Carlos Eduardo"
},
"plan": {
"id": "f5e4d3c2-...",
"name": "Plano Premium Mensal",
"amount": 49.9
},
"lastPayment": {
"paymentId": "9a8b7c6d-5e4f-3a2b-1c0d-ef9a8b7c6d5e",
"amount": 49.9,
"paidOn": "2026-09-09T10:15:05Z",
"gatewayPaymentId": "123456789012"
}
}Próximos Passos
- Acompanhar o Ciclo: Consulte o status da assinatura e a data da próxima cobrança em Consultar Assinatura.
- Alterar Meio de Pagamento: Se o cliente precisar atualizar o cartão de cobrança, use Alterar Meio de Pagamento.
- Consultar Faturas: Acompanhe o histórico financeiro de faturas em Listar Faturas do Cliente.
- Cancelamento: Para encerrar a recorrência, envie uma requisição para Cancelar Assinatura.
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-2a56a168fc76c04c9689b54a0049a5dc-f9a7314fdda2ca44-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": "PaymentCustomerId",
"description": "O PaymentCustomerId é obrigatório."
},
{
"tag": "RecurrencePlanId",
"description": "O RecurrencePlanId é obrigatório."
}
]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.
