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

# Cobranças

> Como criar, pagar, cancelar e marcar cobranças como pagas.

Cobranças conectam cliente, produto, vencimento, valor e opções de pagamento. Use esse recurso quando você precisa gerar uma cobrança específica para um cliente, acompanhar seu status ou conciliá-la manualmente.

## Criar cobrança

`POST /v1/charge` cria uma cobrança para um cliente e produto. No exemplo abaixo, criamos uma cobrança de mensalidade no sandbox.

```bash theme={null}
curl --request POST 'https://sandbox.api.veepag.com/v1/charge' \
  --header 'apiKey: keyId.secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "companyId": "company_id",
    "clientId": "client_id",
    "productId": "product_id",
    "dueDate": "2026-07-23",
    "amount": 99.9,
    "description": "Mensalidade julho"
  }'
```

<Note>
  Em `POST /v1/charge`, o valor de `amount` é convertido para centavos internamente com `Math.round(amount * 100)`.
</Note>

## Pagar cobrança

`POST /v1/charge/pay` processa o pagamento da cobrança, mas usa reCAPTCHA em vez de `apiKey` ou `token`.

Esse endpoint é diferente dos demais porque faz parte de um fluxo mais próximo de checkout/pagamento. Se você estiver integrando esse caminho, valide a experiência completa no sandbox antes de seguir para homologação.

Campos obrigatórios confirmados:

| Campo           | Descrição                        |
| --------------- | -------------------------------- |
| `_id`           | ID da cobrança.                  |
| `companyId`     | ID da empresa.                   |
| `referenceId`   | Referência da cobrança.          |
| `paymentMethod` | Método de pagamento.             |
| `installments`  | Obrigatório no DTO, default `1`. |

## Cancelar cobrança

`PUT /v1/charge/cancel` cancela a cobrança e altera o status para `CANCELED_MANUAL`.

```json theme={null}
{
  "companyId": "company_id",
  "chargeId": "charge_id"
}
```

Em sucesso, o endpoint não retorna corpo de resposta.

## Marcar como paga

`PUT /v1/charge/paid` marca uma cobrança como paga. Esse caminho é útil para conciliações ou operações em que a confirmação de pagamento acontece fora do fluxo automático.

```json theme={null}
{
  "companyId": "company_id",
  "_id": "charge_id"
}
```

Esse endpoint é idempotente quando a cobrança já está `PAID`: a API retorna a própria cobrança.

## Exportar cobranças

`GET /v1/charge/exports` exporta até 10.000 itens. Reduza o período ou os filtros se esse limite for excedido.

<Tip>
  Para conciliação, exporte períodos menores e mantenha o mesmo critério de filtro entre as consultas. Isso facilita comparar os dados com seu sistema interno.
</Tip>