Arquitetura & Proxy HMAC

A AfriSwitch utiliza uma arquitetura institucional segura baseada num proxy HMAC que protege o acesso à API interna https://api.afriswitch.net/api/v1/. O portal empresarial atua como camada de autenticação, orquestração e normalização.

1. Visão Geral

Cliente (Sistema Parceiro / Postman)
        ↓
Portal Empresarial AfriSwitch (autenticação da organização)
        ↓
Proxy HMAC (assinatura automática)
        ↓
API Institucional AfriSwitch
        ↓
Resposta Institucional
        ↓
Portal (normalização da resposta)
        ↓
Cliente

2. Papel do Portal AfriSwitch

• Valida que a organização está ativa
• Verifica permissões
• Aplica automaticamente a assinatura HMAC
• Encaminha o pedido para a API institucional
• Devolve uma resposta normalizada

3. O Proxy HMAC

O proxy HMAC é um componente interno que assina todos os pedidos enviados para a API institucional. Os parceiros nunca precisam de gerar assinaturas manualmente.

Serviço interno utilizado:

call_institutional_api(
    portal_company=request.company,
    method="GET/POST",
    path="/api/v1/...",
    json_body=request.json_body,
    params=request.GET,
    use_hmac=True,
)

Este serviço:

• Gera a assinatura HMAC
• Adiciona os headers necessários
• Envia o pedido para a API institucional
• Devolve a resposta bruta dentro de data

4. Estrutura da Resposta (Portal)

{
  "status": 200,
  "data": {
    ...
  }
}

O campo data contém a resposta institucional (com valores sensíveis mascarados na documentação).

5. Segurança

• As chaves API são únicas por organização
• O portal assina todos os pedidos em nome do parceiro
• Nenhuma chave interna é exposta
• Datas, referências e números são mascarados na documentação

6. Testes & Validação

• Utilize Postman com x-api-key e api-secret
• Teste fluxos PAYIN / PAYOUT
• Observe o comportamento real do operador (payment_url, OTP, USSD)
• Verifique estados via /transactions/status/

Conclusão

Esta arquitetura garante uma integração segura, escalável e de nível institucional para todos os parceiros AfriSwitch.