# Cobranças

Referência das cobranças PIX e boleto na API da SinapsePay — criar, consultar, o objeto Cobrança, situações e respostas.

## Criar uma cobrança

```http
POST /v1/cobrancas
```

Escopo `cobrancas:criar`. Cria no produto da chave (PIX Cobrança ou boleto).

| Campo | Tipo | |
|---|---|---|
| `valor` | inteiro | **Obrigatório.** Em centavos (`8990` = R$ 89,90) |
| `vencimento` | data | `AAAA-MM-DD`. PIX com vencimento; boleto exige |
| `descricao` | texto | Até 140 caracteres. Aparece para o pagador |
| `idExterno` | texto | O seu identificador (até 64). Único por organização; dá para consultar por ele |
| `pagador` | objeto | `nome`, `documento` (CPF ou CNPJ), `email`, `endereco`. Boleto e PIX com vencimento exigem; boleto exige o endereço |
| `pagador.endereco` | objeto | `cep`, `logradouro`, `numero`, `complemento`, `bairro`, `cidade`, `uf` |
| `condicoes` | objeto | `multaPercentual`, `jurosMensalPercentual`, `descontoPercentual` ou `descontoValor`, `descontoDiasAntes`, `mensagens` |
| `expiracaoSegundos` | inteiro | PIX imediato: validade do QR Code (padrão: 24 horas) |

Exemplo de PIX com vencimento e condições:

```json
{
  "valor": 15000,
  "vencimento": "2026-10-20",
  "descricao": "Mensalidade de outubro",
  "idExterno": "mensalidade-2026-10-cliente-88",
  "pagador": { "nome": "Maria Souza", "documento": "529.982.247-25" },
  "condicoes": { "multaPercentual": "2", "jurosMensalPercentual": "1" }
}
```

### Respostas

- **`201`** (PIX): o banco já emitiu; a resposta traz `pix.copiaECola` e `pix.txid`.
- **`202`**: a cobrança está `emitindo`. Acontece sempre no boleto e no PIX quando o banco demora mais de alguns segundos. Consulte depois ou espere o aviso.
- **`422`**: algum campo precisa de correção; veja `errors` (por campo).

## Consultar

```http
GET /v1/cobrancas/{id}
```

Escopo `cobrancas:ler`. `{id}` é o id da SinapsePay **ou o seu `idExterno`**.

Se a cobrança está em aberto, vencida ou expirou há menos de um dia, a consulta **pergunta ao banco na hora** (no máximo uma vez a cada 5 segundos por cobrança) e responde já atualizada. Assim, mesmo que um aviso do banco se perca, o pagamento aparece quando você consulta.

## O objeto Cobrança

```json
{
  "id": "4ec2604f-97c2-4715-9642-c6e59cb7bef8",
  "produto": "pix",
  "status": "paga",
  "valor": 8990,
  "descricao": "Pedido 1042",
  "idExterno": "pedido-1042",
  "pix": { "txid": "4ec2604f97c247159642c6e59cb7bef8", "tipo": "imediata", "copiaECola": "000201...", "expiracaoSegundos": 86400 },
  "pagamentos": [
    {
      "id": "c1a8...",
      "origem": "webhook",
      "valorOriginal": 8990,
      "valorPago": 8990,
      "pagoEm": "2026-10-06T13:53:41Z",
      "creditoEm": "2026-10-06",
      "pagoPorNome": "Maria Souza",
      "pagoPorDocumento": "52998224725",
      "endToEndId": "E75691000202610061353..."
    }
  ],
  "criadaEm": "2026-10-06T13:52:08Z",
  "statusAlteradoEm": "2026-10-06T13:53:41Z"
}
```

Boleto traz `boleto` (`nossoNumero`, `seuNumero`, `linhaDigitavel`, `codigoBarras`) no lugar de `pix`. Devoluções aparecem em `devolucoes` ([veja devoluções](/docs/devolucoes)).

## Situações

| `status` | Quer dizer |
|---|---|
| `emitindo` | Pedido enviado ao banco |
| `em_aberto` | Pronta para pagar |
| `vencida` | Passou do vencimento e ainda aceita pagamento (com multa e juros, se houver) |
| `expirada` | PIX imediato além da validade: o banco não aceita mais |
| `paga` | Pagamento recebido |
| `devolvida` | Todo o valor pago foi devolvido |
| `cancelando` → `cancelada` | Cancelada no banco a seu pedido |
| `baixada` | Paga por fora e baixada por você |
| `falhou` | O banco recusou a emissão; veja `motivoFalha` |

Um pagamento que chega com valor diferente do esperado entra com `divergencia` (`pago_a_mais`, `pago_a_menos`, `pago_em_dobro`, `pago_apos_baixa`, `pago_apos_cancelamento`).

## Cancelar e baixar

```http
POST /v1/cobrancas/{id}/cancelar
{ "motivo": "Cliente desistiu" }

POST /v1/cobrancas/{id}/baixar
{ "valorPago": 15000, "pagoEm": "2026-10-06", "forma": "dinheiro" }
```

- **Cancelar** (`cobrancas:cancelar`): o banco deixa de aceitar o pagamento. Resposta `202`; a cobrança vai de `cancelando` para `cancelada`. Se o pagamento chegar antes, ele vale e o cancelamento é recusado (`cancelamentoRecusado`).
- **Baixar** (`cobrancas:baixar`): para o que foi recebido fora do banco. `forma`: `dinheiro`, `transferencia`, `cheque` ou `outro`. A cobrança fica `baixada` e o banco deixa de aceitá-la.