# Enriquecimento de Transações

A API de Enriquecimento é um serviço separado que, utilizando a mesma autenticação dos principais serviços da Pluggy, permite que clientes que já coletaram dados de Open Finance ou possuem dados existentes de sua base de clientes enriqueçam os dados transacionais fornecendo categorização e informações sobre comerciantes.

<Callout variant="info" title="Recurso premium">
Para habilitar a API de enriquecimento, você deve solicitar isso à equipe de vendas para habilitá-la para sua equipe.
</Callout>

## Como usar

1. Obtenha uma chave de API do nosso endpoint [Auth](/reference/auth-create).
2. Use o fluxo de categorização descrito em [Categorização de Transações](/docs/products/transaction-categorization) com a chave de API obtida e envie as transações para categorizar:

**Exemplo de conta corrente:**

```json
{
  "transactions": [
    {
      "id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
      "amount": -100,
      "date": "2024-09-06T00:00:00-03:00",
      "description": "MC DONALDS"
    }
  ],
  "clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
  "accountType": "CHECKING",
  "isBusiness": false
}
```

**Conta corrente com dados de pagamento:**

```json
{
  "transactions": [
    {
      "id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
      "amount": -100,
      "date": "2024-09-06T00:00:00-03:00",
      "description": "MC DONALDS",
      "paymentData": {
        "payer": {
          "name": "John Doe",
          "documentNumber": { "value": "123.456.789-00", "type": "CPF" }
        },
        "receiver": {
          "name": "MC DONALDS",
          "documentNumber": { "value": "42.591.651/0001-43", "type": "CNPJ" }
        }
      }
    }
  ],
  "clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
  "accountType": "CHECKING",
  "isBusiness": false
}
```

**Exemplo de cartão de crédito:**

```json
{
  "transactions": [
    {
      "id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
      "amount": -100,
      "date": "2024-09-06T00:00:00-03:00",
      "description": "MC DONALDS",
      "creditCardMetadata": {
        "payeeMCC": 1234
      }
    }
  ],
  "clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
  "accountType": "CREDIT_CARD",
  "isBusiness": false
}
```

O campo `creditCardMetadata` é opcional e melhora significativamente a precisão da categorização.

Você pode enviar até 5000 transações por solicitação.

O campo `accountType` é opcional e aceita `CHECKING` ou `CREDIT_CARD`. O campo `isBusiness` também é opcional e indica se esta é uma conta PJ ou PF.

3. A resposta será algo como isto:

```json
{
  "results": [
    {
      "id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
      "amount": -100,
      "date": "2024-09-06T00:00:00-03:00",
      "description": "MC DONALDS",
      "type": "DEBIT",
      "merchant": {
        "name": "mc donalds",
        "businessName": "ARCOS DOURADOS COMERCIO DE ALIMENTOS LTDA",
        "cnpj": "42.591.651/0001-43"
      },
      "category": "Comer fora"
    }
  ]
}
```

O campo `merchant` pode ser `null` se o comerciante for desconhecido. Veja os possíveis valores de categoria na nossa página de [Categorização de Transações](/docs/transaction-categories).

## Limites de taxa

A API de Enriquecimento limita cada aplicação a **600 solicitações por minuto**, contadas juntas nas solicitações `POST /categorize`, `POST /behavior-analysis` e `POST /recurring-payments`. A contagem é por aplicação (`clientId`), não por IP.

Uma solicitação acima do limite é respondida com `429`:

```json
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de taxa excedido"
}
```

| Cabeçalho | Significado |
| --- | --- |
| `Retry-After` | Segundos até o final da janela do minuto atual e as solicitações serem aceitas novamente. |
| `X-RateLimit-Limit` | Seu limite, em solicitações por minuto. |
| `X-RateLimit-Remaining` | Solicitações restantes na janela. `0` em um `429`. |

Aguarde `Retry-After` segundos e tente novamente. Para ficar abaixo do limite, agrupe as transações em vez de enviar uma por solicitação: `POST /categorize` aceita até 5000 transações por chamada. Se sua integração precisar de um limite maior, entre em contato com a equipe de vendas.