# Análise de Pagamentos Recorrentes

Oferecemos uma API de Pagamentos Recorrentes que permite identificar as despesas repetidas de um usuário (como aluguel, contas de serviços) e as receitas repetidas (como salário), útil para perfilamento financeiro. Você pode analisar as transações de um Item e descobrir quais delas se repetem, quão regular é essa repetição e o valor médio da transação repetida.

> **Recurso de Categorização necessário**
>
> Para usar esta API, você precisará do recurso de Categorização habilitado para seu cliente. Ele é habilitado por padrão durante o período de teste. Após isso, é um recurso premium opcional.
>
> Por favor, entre em contato com nossa equipe de Vendas se você quiser habilitá-lo!

## Usando a API de Pagamentos Recorrentes

1. Obtenha uma chave de API do nosso endpoint [Auth](/reference/auth-create).
2. Use o endpoint de pagamentos recorrentes com a chave de API obtida (como o cabeçalho `X-API-Key`), e especifique um ID de Item no corpo da solicitação:

```
POST https://enrichment-api.pluggy.ai/recurring-payments
```

```json
{
  "itemId": "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}
```

3. A resposta será algo como isto:

```json
{
  "recurringPayments": [
    {
      "description": "debito aut conta agua e esgoto sabesp",
      "averageAmount": -76.78,
      "occurrences": [
        "77777777-8888-9999-0000-111111111111",
        "88888888-9999-0000-1111-222222222222",
        "99999999-0000-1111-2222-333333333333"
      ],
      "regularityScore": 0.997773784382727
    },
    {
      "description": "ebn spotify",
      "averageAmount": -21.9,
      "occurrences": [
        "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "bbbbbbb1-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "ccccccc1-cccc-cccc-cccc-cccccccccccc",
        "ddddddd1-dddd-dddd-dddd-dddddddddddd",
        "eeeeeee1-eeee-eeee-eeee-eeeeeeeeeeee",
        "fffffff1-ffff-ffff-ffff-ffffffffffff",
        "11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "33333333-cccc-cccc-cccc-cccccccccccc",
        "44444444-dddd-dddd-dddd-dddddddddddd",
        "55555555-eeee-eeee-eeee-eeeeeeeeeeee",
        "66666666-ffff-ffff-ffff-ffffffffffff"
      ],
      "regularityScore": 0.9344445222642911
    },
    {
      "description": "mp camisetadepre",
      "averageAmount": -8.57,
      "occurrences": [
        "99999999-cccc-cccc-cccc-cccccccccccc",
        "00000000-dddd-dddd-dddd-dddddddddddd",
        "aaaaaaa3-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "bbbbbbb3-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "ccccccc3-cccc-cccc-cccc-cccccccccccc",
        "ddddddd3-dddd-dddd-dddd-dddddddddddd"
      ],
      "regularityScore": 0.9199999999999999
    },
    {
      "description": "niazi chohfi textil",
      "averageAmount": -20.12,
      "occurrences": [
        "eeeeeee3-eeee-eeee-eeee-eeeeeeeeeeee",
        "fffffff3-ffff-ffff-ffff-ffffffffffff",
        "11111113-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
      ],
      "regularityScore": 0.9528595479208968
    }
  ]
}
```

`regularityScore` é um valor entre 0 e 1, indicando quão consistentes os pagamentos são em termos de tempo e valor. Um escore mais alto significa pagamentos mais regulares.

## Considerações

- **Significado do Valor:** Valores negativos representam débitos (despesas), e valores positivos representam créditos (renda). Isso se aplica a **todos os tipos de conta**: os valores são normalizados antes da análise, então uma cobrança recorrente de cartão de crédito é retornada como um `averageAmount` negativo, mesmo que o valor bruto da transação em uma conta de cartão de crédito seja positivo. Você não precisa inverter nada com base na conta de onde o pagamento veio.
- **Normalização:** As descrições das transações são normalizadas convertendo para minúsculas e removendo caracteres especiais e espaços em branco extras.
- **Ocorrências Mínimas:** Um pagamento deve ocorrer pelo menos três vezes para ser considerado recorrente.
- **Consistência de Intervalo:** Os pagamentos devem ocorrer em intervalos consistentes (aproximadamente mensalmente, dentro de uma faixa de 30 +/-5 dias).
- **Variação de Valor:** A variação nos valores das transações deve ser menor ou igual a 10% para ser considerada consistente.

> **Análise personalizada**
>
> Se você estiver interessado em uma análise de usuário mais personalizada, entre em contato com nossa equipe de Vendas para que possamos trabalhar nisso juntos!