# Agendador de PIX Automático (Beta)

## Visão Geral

O **Agendador de PIX Automático** é uma extensão do recurso [PIX Automático](/docs/getting-started-with-pix-automático) da Pluggy que permite automatizar o agendamento de pagamentos recorrentes sem intervenção manual.

Em vez de chamar o endpoint de agendamento você mesmo para cada ciclo de pagamento, você pode habilitar o agendador ao criar a solicitação de pagamento. Uma vez que o pagador autoriza o consentimento, os pagamentos serão agendados automaticamente em cada ciclo de recorrência, sempre respeitando a janela de agendamento permitida (D+2 a D+10).

## Como funciona

Quando você cria uma solicitação de pagamento de PIX Automático com `schedulerConfiguration.enabled: true`, o sistema cuida do agendamento dos pagamentos para você. Após o pagador autorizar o consentimento, os pagamentos são agendados periodicamente de acordo com o `interval` e `startDate` configurados, dentro da janela permitida de D+2 a D+10. Isso continua automaticamente até que o consentimento expire ou seja cancelado.

## Configuração

Você configura o agendador no momento de criar a solicitação de pagamento de PIX Automático, através do objeto `schedulerConfiguration`:

```json
{
  "schedulerConfiguration": {
    "enabled": true,
    "description": "Pagamento de assinatura mensal"
  }
}
```

### Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `enabled` | `boolean` | Sim | Habilita o agendamento automático de pagamentos. |
| `description` | `string` | Não | Descrição para os pagamentos agendados (máx 140 caracteres). Se definido, substitui a `description` da solicitação de pagamento. |
| `valueForVariableAmount` | `number` | Condicional | **Obrigatório** quando o consentimento utiliza valores variáveis (`minimumVariableAmount` / `maximumVariableAmount`). Este é o valor padrão que será usado para cada pagamento agendado automaticamente. Deve estar dentro da faixa permitida. **Não permitido** quando o consentimento utiliza um `fixedAmount`. |

## Criando uma solicitação de pagamento com agendamento automático

### Exemplo de valor fixo

```bash
curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
  -H "X-API-KEY: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Assinatura mensal",
    "fixedAmount": 99.90,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "description": "Assinatura - Julho 2025"
    }
  }'
```

### Exemplo de valor variável

```bash
curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
  -H "X-API-KEY: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Conta de utilidade",
    "minimumVariableAmount": 50.00,
    "maximumVariableAmount": 500.00,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "valueForVariableAmount": 150.00
    }
  }'
```

## Lógica de agendamento

### Cálculo da data de pagamento

Cada pagamento é agendado no início de seu ciclo de recorrência. Por exemplo, um consentimento `MONTHLY` começando em 1º de julho terá pagamentos agendados para 1º de julho, 1º de agosto, 1º de setembro, etc.

De acordo com as regulamentações do Banco Central, os pagamentos devem ser agendados entre **D+2 e D+10**. Se a próxima data de pagamento já tiver passado D+2, o agendador ajusta para a data mais próxima permitida.

O agendador para automaticamente quando o consentimento expira (`expiresAt`) ou é cancelado. Em ambos os casos, um webhook `payment_request/updated` é enviado com o status da solicitação de pagamento definido como `EXPIRED` ou `CANCELED`, respectivamente.

## Regras de validação

| Cenário | Erro |
|---------|------|
| Consentimento de valor variável sem `valueForVariableAmount` na configuração do agendador | `AUTOMATIC_PIX_SCHEDULER_MISSING_VALUE_FOR_VARIABLE_AMOUNT` |
| `valueForVariableAmount` está fora da faixa de `minimumVariableAmount` / `maximumVariableAmount` | `AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_IN_RANGE` |
| `valueForVariableAmount` é fornecido, mas o consentimento utiliza um `fixedAmount` | `AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_ALLOWED` |

## Intervalos suportados

O agendador suporta todos os intervalos do PIX Automático:

- `WEEKLY` — ciclos de 7 dias
- `MONTHLY` — ciclos de mês calendário
- `QUARTERLY` — ciclos de 3 meses
- `SEMESTER` — ciclos de 6 meses
- `ANNUAL` — ciclos de 12 meses