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

# Cobranças

> Como criar e gerenciar cobranças com **pagamentos.dev**

## O que são cobranças?

Cobranças são solicitações de pagamento criadas para um cliente, que podem ser
pagas usando diversos métodos, como Pix, boleto, cartão de crédito, etc.

Com **pagamentos.dev**, você pode criar, consultar, atualizar e cancelar
cobranças  de forma simples e eficiente, utilizando uma interface unificada para
diversos provedores de pagamento.

<Info>
  A disponibilidade das operações pode variar de acordo com o provedor conectado.

  Consulte a documentação do provedor para detalhes específicos sobre as
  funcionalidades suportadas.
</Info>

## Cobranças vs Pagamentos

É importante entender a diferença entre cobranças e pagamentos:

* **Cobranças**: São as solicitações de pagamento criadas para um cliente. Elas
  representam o valor que deve ser pago, o método de pagamento, o cliente
  associado, etc. As cobranças podem ter diferentes status, como `pendente`,
  `pago`, `cancelado`, etc.

* **Pagamentos**: São as transações financeiras realizadas para quitar as
  cobranças. Um pagamento pode ser bem-sucedido, falhar, ser estornado, etc.
  Os pagamentos estão diretamente relacionados às cobranças, mas representam
  a ação de pagar, enquanto as cobranças representam a solicitação de pagamento.

## Status das cobranças

Para facilitar o gerenciamento, os status das cobranças são padronizados em:

* `pendente`: A cobrança foi criada, mas ainda não foi paga.
* `pago`: A cobrança foi paga com sucesso.
* `cancelado`: A cobrança foi cancelada e não pode mais ser paga.
* `vencido`: A cobrança não foi paga dentro do prazo e está vencida.
* `falha`: Ocorreu um erro durante o processamento do pagamento.

## Criando uma cobrança

### Pix

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(),
  valor: 1000, // valor em centavos
  metodoPagamento: 'pix', // ou 'boleto', 'cartaoCredito', etc.
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})
```

### Cartão de crédito

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(),
  valor: 5000, // valor em centavos
  metodoPagamento: 'cartaoCredito',
  cliente: {
    nome: 'Maria Souza',
    documento: '987.654.321-00'
  },
  cartaoCredito: {
    token: 'token-do-cartao' // token gerado pelo provedor
  }
})
```

## Consultando uma cobrança

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

const pagamento = await pg.cobrancas.get('id-da-cobranca')

console.log(pagamento.status) // 'pendente', 'pago', 'cancelado', etc.
```

## Listando cobranças

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

const pagamentos = await pg.cobrancas.list({
  clienteDocumento: '123.456.789-00', // filtra por cliente
  status: 'pendente' // filtra por status
})

console.log(pagamentos)
```

<Info>
  Filtros disponíveis podem variar dependendo do provedor conectado. Consulte a
  documentação do provedor para detalhes específicos.
</Info>

## Cancelando uma cobrança

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

await pg.cobrancas.cancel('id-da-cobranca', { idempotencyKey: crypto.randomUUID() })
```

## Atualizando uma cobrança

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { pg } from './pagamentos'

await pg.cobrancas.update('id-da-cobranca', {
  idempotencyKey: crypto.randomUUID(),
  valor: 1500, // novo valor em centavos
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})
```