Orquestração - PlugToPay

Como o gateway é escolhido

A cada pagamento, o roteador percorre três camadas em ordem de prioridade:

1. gateway_first_try no body da requisição?
   → Sim: usa esse gateway (se habilitado)
   → Não: continua ↓

2. Existem regras de roteamento por percentual para esse método?
   → Sim: seleciona pelo algoritmo de maior déficit
   → Não: continua ↓

3. Fallback: primeiro gateway habilitado, ordenado por `order`

1 — Ordem dos gateways (fallback)

Quando nenhuma regra de percentual está ativa, o sistema usa o gateway com menor order dentre os habilitados. É o mecanismo de fallback garantido — sempre existe um gateway escolhido se pelo menos um estiver habilitado.

Consultar ordem atual

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

[
  { "gateway_id": 1, "gateway_slug": "pagarme",  "order": 1, "enabled": true  },
  { "gateway_id": 4, "gateway_slug": "safe2pay",  "order": 2, "enabled": true  },
  { "gateway_id": 2, "gateway_slug": "stripe",    "order": 3, "enabled": false }
]

Atualizar ordem

PUT /api/v1/company/gateways/order — requer X-Client-ID + X-API-Key. A posição no array define a prioridade: índice 0 vira order = 1, índice 1 vira order = 2, e assim por diante. Gateways ausentes da lista são mantidos e reposicionados após os listados.

{
  "gateways": [
    { "gateway_id": 4 },
    { "gateway_id": 1 },
    { "gateway_id": 2 }
  ]
}

Resultado: Safe2Pay = prioridade 1, Pagarme = prioridade 2, Stripe = prioridade 3.

Gateways desabilitados (enabled: false) são ignorados durante o roteamento mesmo que estejam no topo da ordem. Apenas gateways habilitados participam do fallback.

2 — Roteamento por percentual

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.

[
  { "gateway_id": 1, "gateway_slug": "pagarme",  "payment_method": "card", "percentage": 70 },
  { "gateway_id": 4, "gateway_slug": "safe2pay",  "payment_method": "card", "percentage": 30 },
  { "gateway_id": 1, "gateway_slug": "pagarme",  "payment_method": null,   "percentage": 100 }
]

Definir regras

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

{
  "payment_method": "card",
  "gateways": [
    { "gateway_id": 1, "percentage": 70 },
    { "gateway_id": 4, "percentage": 30 }
  ]
}

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

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

{
  "payment_method": "card",
  "gateways": [
    { "gateway_id": 1, "percentage": 0 },
    { "gateway_id": 4, "percentage": 0 }
  ]
}

3 — Configurações da empresa

As configurações de orquestração ficam em GET /PUT /api/v1/user/company/config — requer Bearer JWT.

{
  "time_to_wait_sync": 6.0,
  "default_response": "sync",
  "retry_failed_payments": true,
  "max_retry_attempt": 3
}

`time_to_wait_sync`

Controla por quanto tempo (em segundos) o servidor aguarda a resposta do gateway antes de devolver uma resposta HTTP ao cliente. O que acontece internamente:

Requisição chega
    ↓
Coroutine criada — processa o pagamento em paralelo
    ↓
Servidor aguarda até time_to_wait_sync segundos
    ↓
Gateway respondeu a tempo?
    SIM → 201 com resultado completo (approved / failed)
    NÃO → 202 com transaction_id ("pagamento em processamento")
              ↓
           Gateway responde depois → webhook entregue ao seu servidor

Valor	Comportamento
Padrão	`5.0` segundos
Mínimo	`0.5` segundos
Máximo	`30.0` segundos

O 202 não significa falha — significa que o gateway ainda não respondeu. O resultado final sempre chega via webhook.

`default_response`

Define o modo padrão de resposta independentemente do tempo de espera.

Valor	Comportamento
`sync` (padrão)	Aguarda até `time_to_wait_sync` — pode retornar `201` ou `202`
`async`	Retorna `202` imediatamente, sem aguardar o gateway

Use async quando a latência de resposta for crítica e seu sistema já está preparado para receber o resultado via webhook.

`retry_failed_payments` e `max_retry_attempt`

Controlam o comportamento de retentativa automática quando um gateway recusa o pagamento.

Campo	Padrão	Range	Descrição
`retry_failed_payments`	`true`	—	Habilita retentativas automáticas em caso de falha
`max_retry_attempt`	`5`	1–10	Número máximo de tentativas por transação

Cada retentativa seleciona o próximo gateway disponível usando a mesma lógica de roteamento (percentual → ordem). O resultado de cada tentativa fica registrado no array transactions[] da resposta. Não são refeitas retentativas para os seguintes motivos de recusa:

expired_card — cartão vencido
insufficient_founds — saldo insuficiente

Nesses casos, uma nova tentativa no mesmo ou em outro gateway resultaria na mesma recusa, então o sistema interrompe imediatamente.

Referência rápida de rotas

Método	Rota	Auth	Descrição
`GET`	`/api/v1/company/gateways/order`	`X-Client-ID` + `X-API-Key`	Consultar ordem atual
`PUT`	`/api/v1/company/gateways/order`	`X-Client-ID` + `X-API-Key`	Definir ordem dos gateways
`GET`	`/api/v1/company/gateways/routing`	`X-Client-ID` + `X-API-Key`	Consultar regras de percentual
`PUT`	`/api/v1/company/gateways/routing`	`X-Client-ID` + `X-API-Key`	Definir regras de percentual
`GET`	`/api/v1/user/company/config`	`Bearer JWT`	Consultar configurações
`PUT`	`/api/v1/user/company/config`	`Bearer JWT`	Atualizar configurações

​Como o gateway é escolhido

​1 — Ordem dos gateways (fallback)

​Consultar ordem atual

​Atualizar ordem

​2 — Roteamento por percentual

​Como funciona o algoritmo

​Escopo por método de pagamento

​Consultar regras atuais

​Definir regras

​3 — Configurações da empresa

​time_to_wait_sync

​default_response

​retry_failed_payments e max_retry_attempt

​Referência rápida de rotas

Como o gateway é escolhido

1 — Ordem dos gateways (fallback)

Consultar ordem atual

Atualizar ordem

2 — Roteamento por percentual

Como funciona o algoritmo

Escopo por método de pagamento

Consultar regras atuais

Definir regras

3 — Configurações da empresa

`time_to_wait_sync`

`default_response`

`retry_failed_payments` e `max_retry_attempt`

Referência rápida de rotas