SopagueDocs
v3

Criar Assinatura

POST/v2/recurrences/subscriptions

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 id retornado em RecurrencePlanId.
  • Cliente: Cadastre o pagador em Criar Cliente e utilize o id retornado em PaymentCustomerId.
  • Meio de Pagamento (Opcional): Para debitar em um cartão específico, tokenize o cartão em Vincular Meio de Pagamento e informe o id em PaymentCustomerPaymentMethodId. Se este campo for omitido, o sistema utilizará automaticamente o Meio de Pagamento Padrão do cliente.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
AuthorizationBearer <token>SimToken JWT Bearer autenticado
Content-Typeapplication/jsonSimTipo de mídia
Idempotency-Key<guid_ou_string>SimChave de idempotência

Parâmetros

Exemplo de requisição
{
  "externalId": "SUB-1002",
  "paymentCustomerId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "recurrencePlanId": "f5e4d3c2-1b0a-9f8e-7d6c-5b4a3f2e1d0c",
  "paymentCustomerPaymentMethodId": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
}

Resposta (201 Created)

Exemplo de resposta
{
  "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

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.