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

# Configurações

> Personalize o comportamento das suas assinaturas

O motor de recorrência permite personalizar o comportamento das assinaturas através da rota de configurações. Essas configurações são aplicadas automaticamente a todas as assinaturas criadas.

### Consultar Configurações

Obtendo as suas configurações atuais:

<CodeGroup>
  ```bash Request theme={null}
  curl --location 'https://api.malga.io/v1/subscriptions/settings' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
    "clientId": "YOUR_CLIENT_ID",
    "retryPolicy": [
      {"daysAfterLastAttempt": 1},
      {"daysAfterLastAttempt": 4},
      {"daysAfterLastAttempt": 9},
      {"daysAfterLastAttempt": 16}
    ],
    "statementDescriptor": "MINHA EMPRESA",
    "cancelAfterAllRetries": false,
    "createdAt": "2025-01-31T10:00:00Z",
    "updatedAt": "2025-01-31T10:00:00Z"
  }
  ```
</CodeGroup>

### Alterando as configurações

<CodeGroup>
  ```bash Request theme={null}
  curl --location --request PATCH 'https://api.malga.io/v1/subscriptions/settings' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "retryPolicy": [
      {"daysAfterLastAttempt": 1},
      {"daysAfterLastAttempt": 3},
      {"daysAfterLastAttempt": 7}
    ],
    "statementDescriptor": "NOVA EMPRESA",
    "cancelAfterAllRetries": true
  }'
  ```

  ```json Response theme={null}
  {
    "clientId": "YOUR_CLIENT_ID",
    "retryPolicy": [
      {"daysAfterLastAttempt": 1},
      {"daysAfterLastAttempt": 3},
      {"daysAfterLastAttempt": 7}
    ],
    "statementDescriptor": "NOVA EMPRESA",
    "cancelAfterAllRetries": true,
    "createdAt": "2025-01-31T10:00:00Z",
    "updatedAt": "2025-01-31T15:30:00Z"
  }
  ```
</CodeGroup>

## Conheça os parâmetros

<ParamField path="retryPolicy" type="array">
  O campo `retryPolicy` permite personalizar quando as retentativas de cobrança devem acontecer após uma falha inicial.

  **Importante**: As retentativas só acontecem quando a transação retorna `retryable = true`. Se a resposta da transação vier com `retryable = false`, a fatura falha imediatamente, independentemente da política de retry configurada.

  <Expandable title="Saiba mais">
    Se não configurado, o sistema usa a estratégia padrão:

    * **D+1**: 1ª retentativa
    * **D+4**: 2ª retentativa
    * **D+9**: 3ª retentativa
    * **D+16**: 4ª retentativa

    Exemplo de personalização:

    ```json theme={null}
    {
      "retryPolicy": [
        {"daysAfterLastAttempt": 1},
        {"daysAfterLastAttempt": 2},
        {"daysAfterLastAttempt": 4},
        {"daysAfterLastAttempt": 7},
        {"daysAfterLastAttempt": 10}
      ]
    }
    ```

    Regras de validação:

    * **Máximo 6 regras** de retry
    * **Valores crescentes**: Cada regra deve ter mais dias que a anterior
    * **Valores válidos**: Entre 1 e 30 dias por regra
    * **Soma total**: A soma de todos os `daysAfterLastAttempt` não pode exceder 30 dias
    * **Formato obrigatório**: Array de objetos com `daysAfterLastAttempt`

    **Importante**: Os dias são cumulativos. Por exemplo, `[1, 3, 5]` significa:

    * 1ª tentativa: D+1
    * 2ª tentativa: D+1+3 = D+4
    * 3ª tentativa: D+1+3+5 = D+9
  </Expandable>
</ParamField>

<ParamField path="cancelAfterAllRetries" type="boolean" default="false">
  O campo `cancelAfterAllRetries` define o comportamento da assinatura quando todas as tentativas de cobrança de uma fatura falham.

  * **false** (padrão): Assinatura vai para status `unpaid` e continua tentando nas próximas faturas
  * **true**: Assinatura é automaticamente cancelada após todas as retentativas falharem
</ParamField>

<ParamField path="statementDescriptor" type="string" maxLength={25}>
  O campo `statementDescriptor` é o texto que aparece na fatura do cartão de crédito do cliente, ajudando na identificação da cobrança.

  * **Prioridade**: Se configurado, é usado em todas as cobranças
  * **Fallback**: Se não configurado, usa o nome da assinatura
  * **Limite**: Depende das regras do banco/operadora (geralmente 13-25 caracteres)
  * **Formatação**: Texto em maiúsculas, sem caracteres especiais
</ParamField>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar primeira assinatura" icon="plus" href="/documentations/more/recurrence/engine/getting-started">
    Use suas configurações personalizadas na primeira assinatura
  </Card>

  <Card title="Monitorar retentativas" icon="chart-line" href="/documentations/more/recurrence/engine/webhooks">
    Configure webhooks para acompanhar o desempenho das retentativas
  </Card>
</CardGroup>