Assinaturas representam recorrências vinculadas a um cliente e a um produto. Use esse fluxo quando sua operação precisa cobrar o cliente de forma recorrente, com regras de produto, vencimento e pagamento associadas.
Na Veepag, existem dois caminhos principais para criar assinaturas. A versão v1 cria a assinatura e já tenta o pagamento; a versão v2 cria a assinatura e a cobrança, mas deixa o pagamento para outro momento.
Criar assinatura v1
POST /v1/subscription cria a assinatura, gera a cobrança e tenta o pagamento imediato. Esse fluxo é útil quando você já tem os dados necessários para iniciar a recorrência e cobrar o cliente no mesmo momento.
Campos obrigatórios confirmados:
| Campo | Regra |
|---|
companyId | String obrigatória. |
product.id | ID do produto. |
paymentMethod | Enum CREDIT_CARD, DEBIT_CARD, BOLETO ou PIX. |
paymentProfile | Obrigatório para CREDIT_CARD: holderName, cardNumber, cardExpiration. |
client.name | Obrigatório quando client é enviado. |
client.doc ou client.cpf | CPF/CNPJ válido. |
curl --request POST 'https://sandbox.api.veepag.com/v1/subscription' \
--header 'apiKey: keyId.secret' \
--header 'Content-Type: application/json' \
--data '{
"companyId": "company_id",
"product": { "id": "product_id" },
"paymentMethod": "CREDIT_CARD",
"installments": 1,
"client": {
"name": "Maria Silva",
"doc": "12345678909",
"email": "maria.silva@example.com"
},
"paymentProfile": {
"holderName": "MARIA SILVA",
"cardNumber": "4111111111111111",
"cardExpiration": "10/2026",
"cardCvv": "123"
},
"metadata": {
"externalOrderId": "pedido_123"
}
}'
Use metadata para guardar identificadores da sua aplicação, como pedido, contrato ou plano interno. Isso facilita conciliação e suporte depois.
Criar assinatura v2
POST /v2/subscription cria a assinatura e a cobrança, mas não tenta o pagamento imediato. Esse caminho é melhor quando o cliente já existe na Veepag e você quer controlar o momento do pagamento separadamente.
Principais diferenças:
| v1 | v2 |
|---|
Cliente inline em client | Cliente existente em clientId |
Produto em product.id | Produto em productId |
| Pagamento imediato | Cria subscription + charge sem pagamento |
Não recebe dueDate no DTO público | dueDate obrigatório |
Cancelar assinatura
PUT /v1/subscription/cancel cancela uma assinatura. Use esse endpoint quando o cliente encerrou a recorrência ou quando sua operação precisa interromper cobranças futuras.
{
"companyId": "company_id",
"subscriptionId": "subscription_id"
}
{
"success": true,
"message": "Assinatura cancelada com sucesso."
}
Criação em lote
POST /v1/subscription/list recebe companyId e list. O processamento é assíncrono por fila, com blocos de 3.000 itens e delay de 15 minutos entre blocos.
O schema dos itens de list não está tipado na codebase (z.any()). Antes de usar esse endpoint em produção, confirme o layout esperado com o time Veepag.
Para lotes grandes, recomendamos validar primeiro com uma amostra pequena no sandbox. Assim você confirma o formato dos dados e evita retrabalho em massa.
