Certificação de provedores¶

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

Nenhum provedor entra em hml ou produção sem passar pelo kit de conformidade (dracma_spp_conformance). Esta página mostra o que ele prova, como montar o fake do parceiro, como rodar e o que precisa estar marcado no checklist antes de pedir o enable.

O que é¶

A suíte fala o protocolo SPP v1 pelo loopback, como se fosse o executor (assina HMAC v2, envia a credencial no corpo), contra o seu adaptador, que por sua vez conversa com um parceiro falso (fake-PSP) controlado pela suíte. Ela prova comportamento, não implementação: serve para qualquer linguagem.

Regras fixas:

• Sem pular teste. Não existe skip. Se a capacidade é false no descriptor, o caso vira "a rota responde 501 unsupported".
• Sem efeito externo real. O adaptador roda em modo sandbox, apontando só para o fake. Nada sai para o parceiro de verdade.
• Mesma semântica de hoje. Cada caso preserva uma regra que o executor já consome (breaker, failover, reconciliador). Um adaptador que passa na suíte pode substituir os atuais sem mudar comportamento.

Quando usar¶

• Ao terminar um adaptador novo (antes do primeiro register em hml).
• A cada mudança do descriptor ou de comportamento do adaptador (recertificação).
• No CI do repositório do provedor, a cada PR.

Como funciona¶

Cenários canônicos do fake¶

O perfil precisa mapear estes cenários para respostas reais do parceiro (os que não se aplicam ao parceiro são declarados n/a com justificativa, nunca omitidos):

Exemplo de perfil¶

provider: exemplo
operations:
  create_charge:
    upstream: { method: POST, path: /v1/pix/charges, must_contain: [identifier, amount] }
    scenarios:
      ok:        { status: 201, body: { id: "ch_1", brcode: "000201...", expires_at: "2026-11-01T12:00:00Z" } }
      http_400:  { status: 400, body: { error: "invalid_amount" } }
      http_503:  { status: 503, body: "" }
      garbage_2xx: { status: 200, body: "<html>ok</html>" }
  get_payout:
    upstream: { method: GET, path: /v1/pix/transfers, query: [clientIdentifier] }
    scenarios:
      ok:        { status: 200, body: { status: "PAID", id: "tr_1", e2e: "E2E123", amount: "10.50" } }
      http_404:  { status: 404, body: { error: "not_found" } }

Rodar¶

spp-conformance run \
  --url http://127.0.0.1:7101/spp/v1 \
  --hmac-secret-env INTERNAL_HMAC_EXEMPLO_EXECUTOR \
  --fake-profile conformance/profile.yaml \
  --out relatorio.json

Código de saída diferente de zero se qualquer caso obrigatório falhar. O relatório traz descriptor_sha256, versão da suíte, casos com evidência e o resumo passed/total. Depois, o ops grava a certificação no registro:

dracma_ops provider certify exemplo --report relatorio.json

O que a suíte cobre¶

Matriz de erros (a mais importante)¶

Para toda operação de rede declarada, a suíte injeta cada cenário e confere a resposta exata. É esta tabela que garante que o breaker e o failover do executor continuam corretos:

Em consultas, o 404 do recurso segue a regra da operação: saque desconhecido é resposta not_found (não erro), cobrança sem registro volta pending ou unrecognized, referência de outro sistema volta deposit_id: null, chave DICT inexistente é key_not_found.

Caos¶

Suíte do executor¶

Além da suíte do autor, o executor roda X-01 a X-10 em hml com o provedor registrado: breaker por provedor, failover de depósito, saque que nunca troca de provedor, drenagem, unplug com trabalho em voo, callbacks (401 uniforme e mesma latência para conexão desconhecida), guarda de ambiente, teste diferencial contra o adaptador em-processo, mudança de descriptor e a prova de que o núcleo não tem lista de provedores.

Checklist de certificação¶

Marque tudo antes de pedir enable em hml ou prd.

Contrato

• [ ] GET /descriptor válido; name imutável; egress_hosts completo e mínimo.
• [ ] Toda capacidade true implementada; toda false responde 501 unsupported.
• [ ] Segredos do credential_schema com x-secret; rótulos e ajuda em português.
• [ ] Rotas servidas iguais ao OpenAPI do SPP (diff vazio).

Comportamento

• [ ] Suíte 100% nos casos obrigatórios, relatório anexado, nenhum skip.
• [ ] Caos 100%: sem queda, vazamento nem dupla execução.
• [ ] Idempotência provada para cobrança e saque.
• [ ] Matriz de erros inteira verde; nenhum erro ambíguo virou definitivo.
• [ ] Callback sobre os bytes crus, comparação em tempo constante, isca, fuzz.

Segurança e operação

• [ ] Usuário Linux próprio, unit hardened, container não-root somente leitura, egress só do descriptor, bind em loopback.
• [ ] Nenhum segredo de longa duração; logs sem credencial nem dado pessoal.
• [ ] SBOM e scan sem vulnerabilidade crítica ou alta aberta.
• [ ] Matriz de acesso no CI do provedor e pentest de entrada limpo.
• [ ] Guarda de ambiente provada; nenhum efeito externo real fora de produção.

Observabilidade e documentação

• [ ] Logs JSON com trace_id; métricas e traces propagados; dashboard e alertas como código.
• [ ] README do provedor com parceiro, credenciais, limites, particularidades e runbook de falha do parceiro.

Integração

• [ ] Suíte do executor (X-01 a X-10) verde em hml.
• [ ] Certificação gravada para o descriptor_sha256 atual.
• [ ] Revisão de segurança por quem não escreveu o adaptador.

Aprovação, validade e recertificação¶

• Passa com 100% dos casos obrigatórios aplicáveis, zero skip. Casos recomendados aparecem no relatório e não bloqueiam.
• Reprova com qualquer falha. A suíte nunca é editada para passar: corrige-se o adaptador. Se o contrato é que está errado, abre-se emenda ao protocolo.
• Caso intermitente reprova e abre defeito; "repetir até passar" não vale.
• A certificação vale para o descriptor_sha256 e a versão da suíte certificados. Mudou qualquer campo do descriptor, ou o comportamento do adaptador: recertifica.
• Suíte nova de versão menor: provedores já habilitados têm 30 dias para recertificar e não são desabilitados.
• Se o parceiro mudou a API (sinal: unrecognized_response em 1% ou mais das chamadas), recertifica depois do ajuste.
• A certificação não substitui o monitoramento: breaker e alertas continuam valendo em produção.

Erros comuns¶

Próximos passos¶

• Escrever um provedor
• Protocolo SPP v1
• Ciclo de vida