# Como aprovar ou rejeitar uma antecipação via API?

> Quando a empresa pagadora exige aprovação, cada antecipação solicitada pelo
> beneficiário fica no status `PENDING` **antes da liquidação** (Pix Out). Você
> aprova ou rejeita cada solicitação via API antes que o pagamento seja enviado.

| Ação | Endpoint | Escopo |
| --- | --- | --- |
| Listar pendentes | `GET /api/v1/anticipation?status=PENDING` | `anticipation.request.read` |
| Aprovar | `POST /api/v1/anticipation/{id}/approve` | `anticipation.request.approve` |
| Rejeitar | `POST /api/v1/anticipation/{id}/reject` | `anticipation.request.approve` |

O `{id}` é o `id` da antecipação retornado na listagem. Todas as respostas são
escopadas à sua empresa (uma antecipação de outra empresa responde `404`).

## 1. Descubra as solicitações pendentes

Faça _polling_ das solicitações `PENDING` (o `beneficiaryTaxID` ajuda a
reconciliar com o seu sistema):

```sh
curl 'https://api.woovi.com/api/v1/anticipation?status=PENDING' \
    -H "Authorization: {SEU_APP_ID}"
```

### Exemplo de resposta

```json
{
  "anticipations": [
    {
      "id": "6290ccfd42831958a405debc",
      "status": "PENDING",
      "beneficiaryTaxID": "12345678909",
      "requestedAmount": 100000,
      "feeAmount": 7000,
      "netAmount": 93000,
      "feeMode": "PERCENTAGE",
      "monthlyFeePercentage": 7,
      "daysUntilDue": 7,
      "dueDate": "2026-07-25T03:00:00.000Z",
      "approvedAt": null,
      "cancelledAt": null,
      "cancelReason": null,
      "endToEndId": null,
      "failureCode": null,
      "failureReason": null,
      "createdAt": "2026-07-18T11:59:00.000Z"
    }
  ],
  "count": 1
}
```

## 2. Aprove (dispara o Pix Out)

```sh
curl 'https://api.woovi.com/api/v1/anticipation/{id}/approve' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}"
```

Aprovar dispara a liquidação: o status passa a `PROCESSING` e depois a
`CONFIRMED` quando o pagamento é enviado.

### Exemplo de resposta

```json
{
  "anticipation": {
    "id": "6290ccfd42831958a405debc",
    "status": "PROCESSING",
    "beneficiaryTaxID": "12345678909",
    "requestedAmount": 100000,
    "feeAmount": 7000,
    "netAmount": 93000,
    "feeMode": "PERCENTAGE",
    "monthlyFeePercentage": 7,
    "daysUntilDue": 7,
    "dueDate": "2026-07-25T03:00:00.000Z",
    "approvedAt": "2026-07-18T12:00:00.000Z",
    "cancelledAt": null,
    "cancelReason": null,
    "endToEndId": null,
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-07-18T11:59:00.000Z"
  }
}
```

## 3. Rejeite (opcionalmente com motivo)

```sh
curl 'https://api.woovi.com/api/v1/anticipation/{id}/reject' -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: {SEU_APP_ID}" \
    -d '{"reason": "acima do limite"}'
```

### Exemplo de resposta

```json
{
  "anticipation": {
    "id": "6290ccfd42831958a405debc",
    "status": "CANCELED",
    "beneficiaryTaxID": "12345678909",
    "requestedAmount": 100000,
    "feeAmount": 7000,
    "netAmount": 93000,
    "feeMode": "PERCENTAGE",
    "monthlyFeePercentage": 7,
    "daysUntilDue": 7,
    "dueDate": "2026-07-25T03:00:00.000Z",
    "approvedAt": null,
    "cancelledAt": "2026-07-18T12:05:00.000Z",
    "cancelReason": "acima do limite",
    "endToEndId": null,
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-07-18T11:59:00.000Z"
  }
}
```

## Idempotência e estados

- As duas ações são **idempotentes**: reenviar a mesma decisão retorna `200`
  com o estado atual. Aprovar uma solicitação já aprovada, ou rejeitar uma já
  cancelada, é um _no-op_.
- Uma decisão que conflita com o estado atual (ex.: aprovar uma rejeitada)
  retorna `409`.
- Se você não decidir, a solicitação **expira** automaticamente conforme o
  prazo configurado (`expirationDays`) e é cancelada.