Provedores de liquidação plugáveis

Para: Dev · Adm — Conferido em 2026-10-31.

Esta seção ensina a escrever, plugar, certificar, operar e trocar um provedor de liquidação: o serviço que traduz o Dracma para a API de um parceiro (um PSP, um banco, uma rede cripto). Tudo o que é específico do parceiro mora no provedor; o núcleo do Dracma não conhece nenhum parceiro pelo nome. O contrato que une as duas pontas se chama SPP (Settlement Provider Protocol), versão 1.

O que é

Um provedor é um processo à parte, com usuário Linux, unit systemd, porta e saída de rede próprios. Ele fala HTTP e JSON em loopback com o executor do Dracma, autenticado por HMAC interno v2, e traduz cada operação (criar cobrança, pagar saque, validar callback) para a API do parceiro. O executor é o único chamador.

Quatro provedores existem hoje:

Provedor Parceiro Direções Observação
simulator nenhum (dinheiro de mentira) entrada e saída Sintético: recusado em produção. Serve para dev, hml e para a certificação.
maximaxpay MaximaxPay entrada e saída PIX de cobrança e de saque; callback assinado com HMAC-SHA256 sobre o corpo cru.
mercadopago Mercado Pago só entrada Credencial de teste declarada no descriptor; callback assinado sobre um manifesto.
chain redes cripto (dracma_chain_rs) só entrada Cobrança on-chain por endereço derivado de xpub; entrega progresso por eventos no barramento.

Quem só usa a API

Se você integra o conector pela API v1 (depósitos e saques), nada muda para você. Os endpoints, os webhooks, os estados e os códigos de erro públicos continuam iguais. Trocar ou plugar um provedor acontece atrás da API, sem deploy do núcleo e sem mudança de contrato com o seu conector.

Por que provedores plugáveis

A decisão (ADR-0041, em linguagem de produto): hoje somos parceiros de um PSP, amanhã podemos não ser. Antes, o nome de cada parceiro estava espalhado em vários repositórios (restrições de banco, enums de API, listas no painel, regras de rede), e trocar de parceiro exigia mexer no núcleo. Agora:

  • Plugar e desplugar a qualquer momento, sem deploy do núcleo. O provedor é registrado, habilitado, drenado e desabilitado por comandos do ops.
  • Sem dependência: o provedor fora do ar não derruba o executor. O dado é persistido, o alerta dispara e o trabalho retoma quando ele volta. O contrário também vale: o provedor sobe sozinho.
  • Uma fonte de verdade: o descriptor que o provedor publica diz o que ele sabe fazer, quais campos de credencial pede, quais URLs e hosts usa. Painel, API e ops derivam tudo dele; ninguém mantém lista de provedores.
  • Terceiros em pé de igualdade: um provedor escrito por outra empresa roda na mesma fronteira de segurança e passa pela mesma certificação.
  • Comportamento preservado: a extração dos adaptadores atuais não muda o que o dinheiro faz (breaker, failover, ambiguidade de saque continuam iguais).

Como funciona

flowchart LR PSP[Parceiro / PSP real] -- callback --> ING[Ingress] ING --> EXE[Executor] EXE -- "SPP v1: HTTP JSON em loopback + HMAC v2" --> PRV[Provedor dracma_psp_nome] PRV -- "HTTPS (egress declarado)" --> PSP EXE <--> REG[(Registro de provedores)] OPS[dracma_ops] -- "register, enable, drain, unplug" --> EXE OPS -. "usuário, unit, porta, par HMAC, egress, ingress" .-> PRV PRV -. "GET /spp/v1/descriptor" .-> EXE
  • Executor: dono do dinheiro, do cofre de credenciais, do breaker, do failover e do registro. É o único cliente do SPP.
  • Provedor: tradutor puro. Sem banco de domínio, sem cofre, sem tenant, sem ledger. A credencial do tenant chega a cada chamada, no corpo, e é descartada ao fim.
  • Ingress: recebe o callback do parceiro em /callbacks/{provider}/{connection_id} e o encaminha ao executor; rota nova para provedor novo não existe, o ops gera a partir do registro.
  • Ops: instala o provedor (usuário, unit, porta, segredo HMAC, regras de saída e entrada) e aciona o registro. Toda operação em servidor passa por ele.

Mapa da seção

Página Para que serve
Protocolo SPP v1 Transporte, HMAC v2, cabeçalhos, todas as operações com exemplos, idempotência, erros, credencial, callbacks, saúde e guarda de ambiente.
Descriptor O JSON que o provedor publica: capacidades, schemas de credencial e configuração, ambientes, egress, callbacks.
Ciclo de vida Registrar, habilitar, drenar, desabilitar e desplugar; o que acontece com trabalho em voo.
Escrever um provedor Passo a passo, do esqueleto ao primeiro depósito de teste.
Certificação A suíte que todo provedor passa antes de ser habilitado em hml e prd.
Segurança Isolamento, rede, segredos, entrada e supply chain de terceiros.
Runbook de troca de parceiro Como sair de um parceiro e entrar em outro sem parar a operação.

Glossário curto

Termo Significado
SPP Settlement Provider Protocol: o contrato HTTP/JSON entre executor e provedor.
Provedor Serviço dracma_psp_<nome> (ou dracma_chain_rs) que implementa o SPP.
Descriptor Documento do provedor com capacidades, schemas, URLs e política de ambiente.
Registro Tabela do executor com os provedores, o estado de cada um e o hash do descriptor.
Conexão Vínculo de um tenant com um provedor: credencial cifrada, configuração e prioridade.
Modo sandbox (ambiente de teste do parceiro) ou live (dinheiro real).
Efeito Se uma falha deixou rastro no parceiro: none (garantidamente não) ou unknown (talvez).
Isca Credencial aleatória usada para que callback de conexão inexistente custe o mesmo que o de uma real.

Como começar em 5 passos

  1. Leia o protocolo e escolha as operações que o seu parceiro suporta; as demais respondem 501 unsupported.
  2. Escreva o descriptor com capacidades, schemas e hosts de saída.
  3. Implemente as rotas seguindo Escrever um provedor; comece pelo descriptor, health e a verificação HMAC.
  4. Rode a certificação contra o provedor local até ficar verde.
  5. Peça ao ops para instalar, registrar e habilitar (veja ciclo de vida); revise a segurança antes de ir a hml.

Erros comuns

  • Tratar o simulator como parceiro real: ele é sintético e a guarda de ambiente o recusa em produção.
  • Gravar a credencial do tenant no provedor. Ela só existe em memória durante a chamada.
  • Classificar timeout de saque como falha definitiva: é effect: unknown, e o executor consulta em vez de reenviar.
  • Esperar que o callback mova dinheiro. Ele só avisa; o dinheiro se move após a consulta de confirmação.

Próximos passos

Comece pelo protocolo SPP v1. Se o seu caso é trocar de parceiro, vá direto ao runbook.