> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veepag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assinaturas

> Como criar, consultar, atualizar e cancelar assinaturas na API Veepag.

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.                                                              |

```bash theme={null}
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"
    }
  }'
```

<Tip>
  Use `metadata` para guardar identificadores da sua aplicação, como pedido, contrato ou plano interno. Isso facilita conciliação e suporte depois.
</Tip>

### Resposta da criação v1

A resposta do v1 confirma a criação da assinatura e também mostra o resultado da tentativa de pagamento dentro de `charge`.

Isso é importante: o endpoint pode retornar `201` porque a assinatura foi criada, mas o pagamento pode ter sido aprovado ou recusado. Para saber o resultado financeiro da tentativa, leia os campos de `charge`.

```json theme={null}
{
  "id": "subscription_id",
  "transactionId": ["transaction_id"],
  "status": "ACTIVE",
  "nextCharge": "2026-07-23T12:00:00.000Z",
  "paymentMethod": "CREDIT_CARD",
  "charge": {
    "statusCode": 200,
    "amount": {
      "value": 9900,
      "currency": "BRL"
    },
    "status": "PAID",
    "message": "Pagamento aprovado",
    "acquirer": {},
    "qrCode": null,
    "boleto": null
  }
}
```

| Campo               | Como interpretar                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `id`                | Identificador da assinatura criada.                                                            |
| `transactionId`     | Lista de transações criadas durante a tentativa de pagamento.                                  |
| `status`            | Status atual da assinatura depois da tentativa de cobrança.                                    |
| `nextCharge`        | Próxima data de cobrança da assinatura, quando disponível.                                     |
| `paymentMethod`     | Meio de pagamento usado na tentativa.                                                          |
| `charge.statusCode` | Resultado da tentativa de pagamento: `200` para aprovado ou `402` para pagamento não aprovado. |
| `charge.status`     | Status da cobrança após a tentativa.                                                           |
| `charge.message`    | Mensagem retornada pelo fluxo de pagamento.                                                    |
| `charge.acquirer`   | Dados retornados pela adquirente, quando disponíveis.                                          |
| `charge.qrCode`     | Dados de Pix, quando o meio de pagamento gerar QR Code.                                        |
| `charge.boleto`     | Dados de boleto, quando o meio de pagamento gerar boleto.                                      |

<Note>
  Para confirmar se o pagamento foi aprovado, use `charge.statusCode`, `charge.status` e `charge.message`. O HTTP `201` indica que a criação da assinatura foi processada; ele não significa, sozinho, que o pagamento foi aprovado.
</Note>

## 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                    |

### Resposta da criação v2

Como o v2 não tenta pagamento imediato, a resposta não traz sucesso ou falha de transação. Ela retorna os objetos criados para você seguir o fluxo no seu próprio momento.

```json theme={null}
{
  "subscription": {
    "_id": "subscription_id",
    "status": "CREATED"
  },
  "charge": {
    "_id": "charge_id",
    "status": "ACTIVE"
  }
}
```

Use o v2 quando a sua integração já tem um `clientId`, quer definir uma data de vencimento em `dueDate` e prefere conduzir o pagamento depois.

## 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.

```json theme={null}
{
  "companyId": "company_id",
  "subscriptionId": "subscription_id"
}
```

Resposta confirmada:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

<Note>
  Para lotes grandes, recomendamos validar primeiro com uma amostra pequena no sandbox. Assim você confirma o formato dos dados e evita retrabalho em massa.
</Note>