TED na Lerian - Lerian

O plugin de TED conecta sua operação ao SPB através do PSTI JD Consultores, oferecendo uma API unificada para gerenciar todas as modalidades de transferência bancária.

Padrão arquitetural

A arquitetura do plugin adota o padrão Hexagonal (Portas e Adaptadores) combinado com CQRS (Command Query Responsibility Segregation) e um design Multi-Tenant. A arquitetura hexagonal isola a lógica de negócio de detalhes de infraestrutura, como APIs, bancos de dados e clientes de serviços externos. A comunicação entre o core e o mundo exterior ocorre através de portas (interfaces) e adaptadores (implementações). O CQRS separa operações de escrita (Commands) das operações de leitura (Queries), permitindo otimizar cada lado de forma independente.

┌─────────────────────────────────────────────────────────────────┐
│                        HTTP REST API                            │
│  POST /v1/transfers/initiate  |  POST /v1/transfers/process     │
│  GET  /v1/transfers/{id}      |  GET  /v1/transfers             │
│  POST /v1/transfers/{id}/cancel                                 │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┴───────────────┐
         │   Transfer Management         │
         │   (Commands + Queries)        │
         └───────────┬───────────────────┘
                     │
     ┌───────────────┼───────────────┬──────────────┐
     │               │               │              │
┌────▼────┐    ┌────▼────┐    ┌────▼────┐    ┌───▼────┐
│ Midaz   │    │   JD    │    │  CRM    │    │ Fees   │
│ Ledger  │    │  SPB    │    │(Midaz)  │    │(Plugin)│
│ (SDK)   │    │ (SOAP)  │    │ (HTTP)  │    │ (HTTP) │
└─────────┘    └─────────┘    └─────────┘    └────────┘

Componentes principais

Componente	Responsabilidade	Tecnologia
Gestão de Transferências	Orquestra os fluxos de TED OUT, TED IN e P2P	Go, Hexagonal + CQRS
Validação e Conformidade	Aplica regras de horário, limites e prevenção de duplicados	Redis (operações atômicas)
Adaptador JD SPB	Comunicação com o sistema da JD Consultores via SOAP/XML	gowsdl, encoding/xml, crypto/rsa
Adaptador Midaz Ledger	Operações de saldo: validação, provisionamento e efetivação	midaz-sdk-golang/v2 (gRPC/HTTP)
Adaptador CRM	Valida contas e recupera informações de ledger	HTTP REST client
Adaptador de Taxas	Calcula taxas de transferência	HTTP REST client
Worker de Polling	Detecta novas transferências de entrada (TED IN)	Goroutine (intervalo de 30s)
Publicador de Webhooks	Notifica sistemas externos sobre mudanças de status	HTTP POST com retentativas e DLQ

Fluxo em duas etapas

O plugin implementa um fluxo de duas etapas para transferências de saída, permitindo que o usuário visualize a tarifa antes de confirmar:

Etapa 1: Iniciar (Initiate)

POST /v1/transfers/initiate

Calcula a tarifa e cria uma intenção de transferência válida por 24 horas. O que acontece:

Valida a conta de origem no CRM
Verifica horário de funcionamento
Detecta duplicatas (janela de 60 segundos)
Calcula tarifa via plugin-fees
Retorna initiationId e valores calculados

Etapa 2: Processar (Process)

POST /v1/transfers/process

Confirma a transferência e inicia o processamento. O que acontece:

Valida limites de uso (diário/mensal)
Verifica saldo disponível
Reserva fundos no Midaz (hold)
Envia mensagem ao SPB (TED OUT) ou executa transferência interna (P2P)
Retorna transferId e número de confirmação

Estados da transferência

Cada transferência passa por estados bem definidos:

TED OUT
TED IN
P2P

CREATED → PENDING → PROCESSING → COMPLETED
                               → REJECTED (4xx da JD)
                               → FAILED (5xx/timeout)
        → CANCELLED (usuário cancela antes do processamento)

RECEIVED → PROCESSING → COMPLETED
                      → REJECTED (destinatário não encontrado)

CREATED → PROCESSING → COMPLETED
                     → FAILED (erro Midaz)
        → CANCELLED

Estado	Descrição
`CREATED`	Transferência criada, aguardando processamento
`PENDING`	Fundos reservados, aguardando envio ao SPB
`PROCESSING`	Mensagem enviada ao SPB, aguardando confirmação
`COMPLETED`	Transferência concluída
`REJECTED`	Rejeitada pelo SPB ou destinatário não encontrado
`FAILED`	Falha técnica (timeout, indisponibilidade)
`CANCELLED`	Cancelada pelo usuário antes do processamento
`RECEIVED`	TED IN detectado, aguardando crédito

Detecção de duplicatas

O plugin detecta transferências duplicadas comparando:

Conta de origem
Dados do destinatário (ISPB, agência, conta)
Valor

Se uma transferência idêntica for enviada dentro da janela configurável (padrão: 60 segundos), o plugin retorna erro BTF-0012. Mecanismo:

Chave de idempotência: SHA256(organizationId + senderAccountId + recipient + amount)
Armazenamento: Redis com TTL configurável
Ação: Rejeitar requisições duplicadas com código 409 Conflict

Tarifas

O plugin integra-se ao plugin-fees para cálculo de tarifas em duas direções:

Operação	Tipo de tarifa
TED OUT	Cashout (débito + envio)
TED IN	Cashin (recebimento)
P2P	Configurável por organização

A tarifa é calculada na etapa de iniciação e exibida ao usuário antes da confirmação.

Comportamento em caso de indisponibilidade

Configuração	Comportamento
Fail-open (padrão)	Continua sem tarifa se plugin-fees indisponível
Fail-closed	Rejeita a operação se tarifa não puder ser calculada

Suporte multi-tenant

O plugin foi projetado para operar em diferentes modelos de implantação, garantindo isolamento de dados e configuração por cliente (tenant).

Identificação do tenant

O tenantId é extraído de um claim JWT e validado contra o cabeçalho HTTP X-Organization-Id. Essa dupla validação garante que o contexto do tenant seja propagado corretamente por toda a pilha de execução.

Isolamento de dados

Todas as consultas ao banco de dados são filtradas por organization_id, garantindo que um tenant nunca acesse dados de outro. O cache em Redis também utiliza prefixos por tenant (tenant:{tenantId}:{key}), prevenindo colisões e vazamento de informações.

Modelos de implantação

Modelo	Descrição	Caso de uso	Overhead
SaaS Multi-Tenant	Múltiplos clientes compartilhando a mesma infraestrutura	Clientes Lerian em ambiente gerenciado	~5-10ms
BYOC Single-Tenant	Um único cliente em infraestrutura dedicada	Grandes clientes com requisitos específicos	<1ms
BYOC Multi-Tenant	Cliente principal gerenciando subsidiárias	Clientes que operam como plataforma	~2-5ms

Flexibilidade: Um único código-base suporta todos os três modelos através de configuração, sem necessidade de branches separados.

Configuração por organização

Cada organização possui configuração independente:

Credenciais JD SPB (criptografadas)
ISPB próprio
URL de webhook e segredo HMAC
Configurações de tarifa
Janela de detecção de duplicatas
Modo de isolamento de dados (DATABASE, SCHEMA, SINGLE)

Observabilidade

O plugin expõe métricas, logs e traces para monitoramento completo.

Métricas (Prometheus)

transfer_initiated_total        # Contador de transferências iniciadas
transfer_completed_total        # Contador de transferências concluídas
transfer_failed_total           # Contador de falhas
transfer_duration_seconds       # Histograma de duração
jd_api_latency_seconds          # Latência de chamadas à JD

Logs estruturados

Todos os logs seguem formato JSON com campos contextuais:

tenantId: identificação do tenant
transferId: identificação da transferência
correlationId: correlação entre operações

Dados sensíveis (CPF/CNPJ) são hasheados com SHA-256.

Traces (OpenTelemetry)

Propagação de contexto entre serviços (Midaz, CRM, Fees, JD) para rastreamento distribuído.

Próximos passos

Enviar TED

Inicie transferências para outras instituições

Receber TED

Processe transferências recebidas automaticamente

Transferências P2P

Otimize transferências internas

Webhooks

Configure notificações de eventos

​Padrão arquitetural

​Componentes principais

​Fluxo em duas etapas

​Etapa 1: Iniciar (Initiate)

​Etapa 2: Processar (Process)

​Estados da transferência

​Detecção de duplicatas

​Tarifas

​Comportamento em caso de indisponibilidade

​Suporte multi-tenant

​Identificação do tenant

​Isolamento de dados

​Modelos de implantação

​Configuração por organização

​Observabilidade

​Métricas (Prometheus)

​Logs estruturados

​Traces (OpenTelemetry)

​Próximos passos

Enviar TED

Receber TED

Transferências P2P

Webhooks

Padrão arquitetural

Componentes principais

Fluxo em duas etapas

Etapa 1: Iniciar (Initiate)

Etapa 2: Processar (Process)

Estados da transferência

Detecção de duplicatas

Tarifas

Comportamento em caso de indisponibilidade

Suporte multi-tenant

Identificação do tenant

Isolamento de dados

Modelos de implantação

Configuração por organização

Observabilidade

Métricas (Prometheus)

Logs estruturados

Traces (OpenTelemetry)

Próximos passos