Como projetei uma arquitetura assíncrona resiliente integrando WordPress a serviços bancários

Integrações bancárias não falham de forma previsível.

Elas falham com:

• 502 inesperado
• Timeout no meio da execução
• Portal em manutenção
• Modal bloqueante invisível
• API retornando success=false mas trazendo dados
• Webhook chegando fora de ordem

E quando existe cobrança por consumo envolvida, o erro não é apenas técnico.

Ele vira problema financeiro.

Foi nesse contexto que projetei uma arquitetura assíncrona resiliente para integrar WordPress a um serviço bancário externo.

O Problema

A arquitetura precisava resolver simultaneamente:

• Receber requisição via REST no WordPress
• Enviar para um serviço externo
• Aguardar processamento assíncrono
• Receber resultado via webhook
• Controlar consumo de créditos
• Evitar dupla cobrança no mesmo dia
• Garantir rastreabilidade completa

Tudo isso sem bloquear o usuário e sem depender da estabilidade do serviço externo.

Decisões Arquiteturais

1. Modelo Assíncrono Controlado por Estado

Implementei um modelo de estados persistidos:

• pending
• completed
• failed

Cada requisição recebe:

• request_id interno (controle do sistema)
• provider_request_id (controle do fornecedor)

Isso permite rastrear inconsistências e lidar com webhooks fora de ordem.

1. Consumo Inteligente de Créditos

Crédito não é consumido na requisição.

Ele só é debitado quando:

• A consulta realmente executa
• O fluxo chega ao estado completed
• Não houve execução prévia no mesmo dia para o mesmo usuário

Isso evita:

• Dupla cobrança
• Cobrança por falha técnica
• Inconsistência contábil

1. Separação entre Falha Técnica e Falha de Negócio

Nem todo erro é igual.

• Timeout → falha técnica
• Portal em manutenção → indisponibilidade externa
• success=false mas com dados → execução válida com warning

O sistema foi projetado para classificar essas situações corretamente e agir de forma diferente em cada uma.

1. Detecção Ativa de Instabilidade

Integrações bancárias muitas vezes utilizam portais web.

Implementei:

• Detecção de modais bloqueantes
• Identificação de manutenção programada
• Captura de evidências para auditoria

Se o portal estiver indisponível, o fluxo aborta de forma controlada e retorna erro padronizado.

1. Padronização de Respostas

O front-end nunca recebe erro bruto.

Recebe um objeto estruturado contendo:

• status
• error_code
• error_message
• dados processados (quando houver)

Isso garante previsibilidade na experiência do usuário.

Fluxo Simplificado

1. WordPress recebe requisição
2. Salva como pending
3. Envia para serviço externo
4. Serviço processa
5. Webhook retorna resultado
6. Sistema valida estado
7. Atualiza para completed ou failed
8. Consome crédito se aplicável

Arquitetura simples na teoria.

Complexa na prática.

Resultados

• Redução de inconsistências financeiras
• Maior previsibilidade no fluxo
• Sistema preparado para instabilidade externa
• Base reutilizável para novos serviços

Aprendizado Principal: Projetar sistemas críticos não é sobre escrever código que funciona quando tudo está bem. É sobre estruturar o sistema para sobreviver quando tudo dá errado.

Stack utilizada:

• PHP (WordPress REST)
• Node.js
• Playwright
• Webhooks
• Controle transacional de créditos
• Modelagem de estado persistido

Compartilho outros estudos e projetos no LinkedIn: Bianca Melo > https://www.linkedin.com/in/bianca-melo-a92450233/