Performance e Boas Práticas
Quick Reference
Integrações de alta performance combinam requisições idempotentes, retentativas inteligentes, credenciais em cache e autenticação em camadas para maximizar vazão e taxas de aprovação.
Limites de taxa
| Nível | Limite | Escopo |
|---|---|---|
| Padrão | 100 requisições/min | Por access token |
| Burst | 20 requisições/seg | Por access token |
| Customizado | Configurável | Contate o gerente de integração |
Quando você atinge um limite de taxa, a A55 retorna HTTP 429 com um header Retry-After (segundos).
Nunca retente erros 4xx em loop apertado. Recue em 429, retente em 5xx com delay exponencial e trate recusas de cartão como terminais.
Timeouts
| Operação | Timeout recomendado | Timeout máximo |
|---|---|---|
| Requisição de token auth | 10 s | 30 s |
| Criar cobrança | 60 s | 90 s |
| Setup / validação 3DS | 30 s | 60 s |
| Zero auth | 15 s | 30 s |
| Endpoints GET / list | 10 s | 30 s |
Estratégia de retentativa
Backoff exponencial
import time, requests
def call_with_retry(url, headers, payload, max_retries=3):
for attempt in range(max_retries):
try:
r = requests.post(url, headers=headers, json=payload, timeout=60)
if r.status_code < 500:
return r
time.sleep(2 ** attempt)
except requests.exceptions.Timeout:
time.sleep(2 ** attempt)
raise Exception("Max retries exceeded")
Chaves de idempotência
Previna cobranças duplicadas de retentativas enviando um header Idempotency-Key:
curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/charge/' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: ord_001_attempt_1' \
-d '{ ... }'
| Comportamento | Detalhe |
|---|---|
| Mesma chave + mesmo body | Retorna a resposta original (sem cobrança duplicada) |
| Mesma chave + body diferente | Retorna 409 Conflict |
| Sem chave | Cada requisição cria uma nova cobrança |
Use uma combinação do seu ID de pedido e número da tentativa: {order_id}_attempt_{n}. Isso facilita o debug e previne reuso acidental.
Performance de autenticação
- Faça cache dos access tokens — Tokens são válidos por 3600 segundos. Requisite uma vez, reutilize entre chamadas
- Não requisite um token por chamada de API — Isso desperdiça orçamento de rate limit e adiciona latência
- Renove proativamente — Renove aos ~3500 segundos, não após a expiração
import os, time, requests
_token_cache = {"token": None, "expires_at": 0}
def get_token():
if time.time() < _token_cache["expires_at"] - 100:
return _token_cache["token"]
r = requests.post(
"https://core-manager.a55.tech/api/v1/auth/token",
data={
"grant_type": "client_credentials",
"client_id": os.environ["A55_CLIENT_ID"],
"client_secret": os.environ["A55_CLIENT_SECRET"],
},
timeout=10,
)
data = r.json()
_token_cache["token"] = data["access_token"]
_token_cache["expires_at"] = time.time() + data["expires_in"]
return _token_cache["token"]
Stack de otimização
| Camada | Técnica | Impacto |
|---|---|---|
| Autenticação | DataOnly 3DS para Visa/Mastercard | Maior aprovação, sem fricção de challenge |
| Credenciais | Network tokens (DPAN + criptograma) | Confiança do emissor, continuidade do ciclo de vida do cartão |
| Dispositivo | Impressão digital A55Pay.getDeviceId() | Pontuações de risco mais fortes |
| Confiabilidade | Chaves de idempotência em toda cobrança | Zero cobranças duplicadas |
| Eficiência | Cache de tokens, connection pooling | Menor latência |
Registrar PANs ou CVVs completos é um risco sério de segurança e cria responsabilidade por incidentes. Use IDs de correlação para rastreamento.
Monitore a latência p95 do seu edge até a A55, taxas de erro por rota e atraso na entrega de webhooks. Alerte antes que os clientes percebam desvios.