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

# Roteamento por percentual

> Distribuição de volume entre gateways usando o algoritmo de maior déficit.

Define quanto do volume de transações deve ser processado por cada gateway. Ideal para distribuir carga, reduzir dependência de um único provedor ou realizar testes A/B entre gateways.

## Como funciona o algoritmo

O sistema usa **Maior Déficit Primeiro** (Largest-Deficit-First). Em vez de sortear aleatoriamente, ele observa as últimas 10 transações aprovadas e calcula qual gateway está mais "devendo" em relação à sua cota.

**Exemplo:**

```
Últimas 10 transações aprovadas com cartão:
  Pagarme:  7 transações
  Safe2Pay: 3 transações

Regras configuradas:
  Pagarme:  70%
  Safe2Pay: 30%

Cálculo:
  Pagarme:  esperado = 10 × 0.70 = 7.0 | real = 7 | déficit = 0.0
  Safe2Pay: esperado = 10 × 0.30 = 3.0 | real = 3 | déficit = 0.0

Próximas 10 transações (agora com 11 no histórico, considera as últimas 10):
  Se Pagarme processa a 11ª → Pagarme: 7/10, Safe2Pay: 3/10
  Pagarme:  esperado = 10 × 0.70 = 7.0 | real = 7 | déficit = 0.0
  Safe2Pay: esperado = 10 × 0.30 = 3.0 | real = 3 | déficit = 0.0
  → empate: vence quem tem maior percentual → Pagarme
```

O efeito prático é que a distribuição converge naturalmente para as proporções configuradas, sem picos ou oscilações bruscas.

***

## Escopo por método de pagamento

As regras podem ser configuradas de forma diferente para cartão e PIX:

| `payment_method` | Aplicação                                               |
| ---------------- | ------------------------------------------------------- |
| `card`           | Apenas transações de cartão                             |
| `pix`            | Apenas transações PIX                                   |
| `null` (omitido) | Padrão — aplica a todos os métodos sem regra específica |

Se existir uma regra para `card` e outra padrão (`null`), transações de cartão usam a regra de cartão; transações PIX sem regra específica usam a padrão.

***

## Consultar regras atuais

`GET /api/v1/company/gateways/routing` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
[
  { "gateway_id": 1, "gateway_slug": "pagbank",  "payment_method": "card", "percentage": 70 },
  { "gateway_id": 4, "gateway_slug": "safe2pay",  "payment_method": "card", "percentage": 30 },
  { "gateway_id": 1, "gateway_slug": "asaas",  "payment_method": null,   "percentage": 100 }
]
```

***

## Definir regras

`PUT /api/v1/company/gateways/routing` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "payment_method": "card",
  "gateways": [
    { "gateway_slug": "pagarme",  "percentage": 70 },
    { "gateway_slug": "safe2pay", "percentage": 30 }
  ]
}
```

<Warning>
  Os percentuais devem somar exatamente **100** ou todos ser **0** (que remove as regras daquele método). Qualquer outra soma retorna `422`.
</Warning>

Para remover regras de um método e voltar ao fallback por ordem:

```json theme={null}
{
  "payment_method": "card",
  "gateways": [
    { "gateway_slug": "pagarme",  "percentage": 0 },
    { "gateway_slug": "safe2pay", "percentage": 0 }
  ]
}
```