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

# Solicitar antecipação

> Crie uma solicitação de antecipação de recebíveis de cartão

## Endpoint

```
POST /api/advances/
```

**Autenticação**: Bearer Token (JWT) — requer KYC aprovado

## Corpo da requisição

| Campo         | Tipo      | Obrigatório | Descrição                                                                    |
| ------------- | --------- | ----------- | ---------------------------------------------------------------------------- |
| `amountCents` | `integer` |             | Valor a antecipar em centavos. Se omitido, antecipa o saldo total disponível |
| `reason`      | `string`  |             | Motivo da solicitação (opcional, para análise interna)                       |

<Note>
  Somente uma antecipação pode estar com status `PENDING` ou `APPROVED` por vez. Tente criar outra nesse estado retorna `409 Conflict`.
</Note>

## Exemplo

```bash theme={null}
curl --request POST \
  --url https://upay-sistema-api.onrender.com/api/advances/ \
  --header 'Authorization: Bearer SEU_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "amountCents": 50000,
    "reason": "Capital de giro"
  }'
```

## Resposta de sucesso (`201 Created`)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amountCents": 50000,
    "netAmountCents": 48500,
    "feeCents": 1500,
    "feePercentage": 3.0,
    "status": "PENDING",
    "createdAt": "2026-05-25T00:00:00.000Z"
  }
}
```

| Campo            | Descrição                                    |
| ---------------- | -------------------------------------------- |
| `amountCents`    | Valor bruto solicitado                       |
| `netAmountCents` | Valor líquido a ser creditado (bruto − taxa) |
| `feeCents`       | Taxa de antecipação em centavos              |
| `feePercentage`  | Taxa de antecipação em percentual            |
| `status`         | Sempre `PENDING` ao criar                    |

## Erros comuns

| Código | Descrição                                             |
| ------ | ----------------------------------------------------- |
| `400`  | Valor inválido ou sem saldo disponível para antecipar |
| `403`  | KYC não aprovado                                      |
| `409`  | Já existe uma antecipação `PENDING` ou `APPROVED`     |

<Card title="Listar antecipações" icon="list" href="./list" horizontal>
  Acompanhe o status da sua solicitação.
</Card>