POST/api/v1/subscriptions

Criar assinatura

Bearer tokenescopo create:subscriptions

Cria uma order de assinatura (PerfectPay) e devolve a URL de checkout + o ID da transação. Responde 201 Created.

Escopo necessário: create:subscriptions.

Utilize o checkoutUrl recebido para realizar o pagamento manualmente.

Este endpoint não emite renovação e só deve ser utilizado se o usuário não possuir assinatura ativa. Upgrade, migração de plano e cancelamento ainda não estão disponíveis via API: contante o suporte para tratar para tratar destes assuntos.

Body

Campo	Tipo	Obrigatório?	Valores / restrições
`planId`	string	sim	id de um dos nossos planos. Consulte os planos via `GET /api/v1/plans`
`billingCycle`	string	sim	`monthly` \| `annual`
`couponCode`	string	não	código de cupom

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/subscriptions \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-sub-001" \
  -d '{
    "planId": "pro",
    "billingCycle": "monthly",
    "couponCode": "PROMO10"
  }'

Resposta — 201

JSON

{ "success": true, "data": {
  "orderId": "ord_...",
  "paymentMethod": "perfectpay",
  "status": "pending",
  "planId": "pro",
  "billingCycle": "monthly",
  "checkoutUrl": "https://..."
}}

Redirecione o usuário para checkoutUrl para concluir o pagamento. A assinatura é ativada quando o webhook PerfectPay confirma. Acompanhe por GET /api/v1/subscriptions (escopo read:subscriptions).

Idempotência

Envie o header Idempotency-Key (opcional, ≤128 chars, TTL 24h). Repetir a mesma chave retorna a resposta original, sem criar nova order. Ver Idempotência.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	body inválido, `planId`/`billingCycle` ausentes
`FORBIDDEN`	403	token sem `create:subscriptions`
`NOT_FOUND`	404	plano indisponível
`SUBSCRIPTION_ALREADY_ACTIVE`	409	já possui assinatura ativa → contate o suporte
`RATE_LIMITED`	429	rate limit
`INTERNAL_ERROR`	500	erro interno

Ver Códigos de erro e Escopos.