# DDA: visão geral

O DDA (Débito Direto Autorizado) mostra, num só lugar, os boletos registrados no CPF/CNPJ da sua conta, sem esperar o boleto chegar por e-mail ou correio.

A ValidaPay **exibe** esses boletos; ela não os emite nem os recebe. O pagamento acontece no banco do sacado, com a linha digitável. Não existe rota para pagar um boleto do DDA.

Também não está disponível em sandbox: qualquer rota de DDA chamada com conta de sandbox devolve `403 DDA_NOT_AVAILABLE_IN_SANDBOX`.

## Como funciona

A conta se inscreve uma vez. A partir daí, os boletos emitidos contra aquele documento chegam por webhook e ficam disponíveis na listagem.

1. `POST /v1/dda/subscription` inscreve o documento da conta. A inscrição nasce em `PROCESSING`.
2. Alguns minutos depois chega `dda.subscription.updated` com `ACTIVE`, e aí a listagem libera.
3. Os boletos já registrados no documento chegam em rajada, logo após a confirmação.
4. Cada boleto novo e cada mudança de situação disparam `dda.invoice.received`.

A inscrição é **por documento**, não por conta. Se o CPF/CNPJ já estiver inscrito, a chamada devolve `409 DDA_ALREADY_SUBSCRIBED`.

## Estados da inscrição

| Status | O que significa |
|---|---|
| `PROCESSING` | Inscrição enviada, aguardando confirmação |
| `ACTIVE` | Inscrição confirmada; boletos visíveis |
| `ERROR` | Inscrição recusada; `errorMessage` traz o motivo |
| `INACTIVATING` | Cancelamento solicitado, aguardando confirmação |
| `INACTIVE` | Cancelamento confirmado |
| `INACTIVATE_FAILED` | Cancelamento recusado |

A listagem de boletos exige `ACTIVE`, `INACTIVATING` ou `INACTIVATE_FAILED`. Nos outros estados ela devolve `403 DDA_SUBSCRIPTION_NOT_ACTIVE`.

Desativar é assíncrono e pode levar horas. Enquanto está em `INACTIVATING`, os boletos continuam visíveis.

## Situação do boleto

| Status | Quando acontece |
|---|---|
| `OPEN` | Boleto em aberto |
| `PAID` | Liquidado, intra ou interbancário |
| `CANCELLED` | Baixado sem pagamento: pedido do beneficiário, decurso de prazo, protesto ou pedido da instituição |

O boleto chega com uma de sete situações distintas, reduzidas a esses três estados. As duas de liquidação viram `PAID`, as quatro demais baixas viram `CANCELLED`.

> O DDA é uma vitrine, não um extrato de pagamentos. Recomendamos não usá-lo como fonte para definir se um boleto foi pago. Use-o para visibilidade, e o seu conciliador para liquidação.

## Vencimento e prazo de pagamento

São dois campos diferentes, e a distinção importa:

| Campo | Significado |
|---|---|
| `dueDate` | Data de vencimento do boleto |
| `overdueDate` | Data limite para pagamento |

Um boleto vencido continua `OPEN`: não existe status de vencido. Para saber se ainda dá para pagar, compare a data de hoje com `overdueDate`, não com `dueDate`. Passado o `overdueDate`, o banco recusa e a cobrança passa a ser direto com o beneficiário.

## Listagem e paginação

`GET /v1/dda/invoices` aceita `status`, `startDate` e `endDate` (por vencimento), além de `limit` (1 a 100, padrão 50).

A paginação é por cursor: `pagination.lastKey` volta no corpo e é reenviado como `lastKey` na requisição seguinte. Quando `hasMore` é `false`, `lastKey` vem `null`. Cursor adulterado devolve `400 INVALID_CURSOR`.

## Eventos

| Evento | Quando |
|---|---|
| `dda.subscription.updated` | A inscrição no DDA mudou de estado. Chega alguns minutos após a ativação e pode levar horas no cancelamento. |
| `dda.invoice.received` | Boleto registrado no CPF/CNPJ da conta. Enviado na primeira vez e sempre que o `status` muda; reenvio sem mudança de situação não dispara o evento. |


## Erros

| Código | HTTP | Quando |
|---|---|---|
| `DDA_NOT_AVAILABLE_IN_SANDBOX` | 403 | Qualquer rota de DDA com conta de sandbox |
| `DDA_ALREADY_SUBSCRIBED` | 409 | Documento já inscrito |
| `DDA_SUBSCRIPTION_PROCESSING` | 409 | Inscrição anterior ainda em processamento |
| `DDA_SUBSCRIPTION_NOT_FOUND` | 404 | Consulta sem inscrição existente |
| `DDA_SUBSCRIPTION_NOT_ACTIVE` | 403 / 404 | Listagem sem inscrição ativa (403) ou cancelamento sem inscrição ativa (404) |
| `INVALID_CURSOR` | 400 | `lastKey` malformado |
| `DDA_PROVIDER_ERROR` | 400 | Falha de comunicação ao consultar o DDA |