01
Scope and Requirements
APIs covered, mTLS/OAuth 2.0 requirements, and applicable BACEN regulations.
APIs Cobertas neste Playbook
| Recurso | Endpoint | Descrição |
|---|---|---|
| Cobrança Imediata | /cob e /cob/{txid} | CRUD de cobranças imediatas com QR Code |
| Cobrança c/ Vencimento | /cobv e /cobv/{txid} | Cobranças com data de vencimento (boleto Pix) |
| Pix Recebidos | /pix e /pix/{e2eid} | Consulta e devolução de Pix recebidos |
| Webhook | /webhook/{chave} | Configuração de notificações push |
| Location (Payload) | /loc e /loc/{id} | Gerenciamento de payloads para QR Code |
| Pix Automático (Rec) | /rec e /rec/{idRec} | Gerenciamento de recorrências (débito automático) |
| Lote CobV | /lotecobv/{id} | Criação e gestão de lotes de cobranças com vencimento |
| Solicitação Rec | /solicrec/{idSolicRec} | Confirmação de autorização de recorrência |
API Pix v2.9.0 — Requisitos de Segurança
- • mTLS obrigatório: Certificado ICP-Brasil (produção) ou emitido pelo PSP (homologação)
- • OAuth 2.0 Client Credentials: Escopos específicos por recurso (cob.read, cob.write, pix.read)
- • RFC 8705: Token vinculado ao certificado TLS — impede uso do token em outra conexão
Normativas Aplicáveis
| Normativa | Escopo de Aplicação |
|---|---|
| Resolução BCB nº 1/2020 | Regulamento base do arranjo Pix |
| Manual de Segurança do Pix | Requisitos técnicos de segurança |
| Manual de APIs Pix | Especificações técnicas das APIs |
| Resolução Conjunta nº 6/2023 | Compartilhamento de indícios de fraude |
| Circular BCB nº 3.978/2020 | Prevenção à lavagem de dinheiro |
| LGPD (Lei 13.709/2018) | Proteção de dados pessoais |
Mantenha um mapeamento entre cada normativa e os casos de teste correspondentes para facilitar auditorias.
02
Functional Tests
Test case matrix for /cob, /cobv, /pix and /webhook with P0/P1 prioritization.
Cobrança Imediata (/cob)
| Método | Prioridade | Caso de Teste | Validações |
|---|---|---|---|
POST /cob/{txid} | P0 | Criar cobrança com valor fixo | HTTP 201, txid, location, QR Code |
POST /cob/{txid} | P0 | Criar cobrança Pix Saque | modalidadeAlteracao, retirada |
POST /cob/{txid} | P1 | Criar cobrança Pix Troco | valor.original, valor.troco |
GET /cob/{txid} | P0 | Consultar cobrança existente | status, calendario, valor, chave |
PATCH /cob/{txid} | P1 | Revisar cobrança (alterar status) | status REMOVIDA_PELO_USUARIO |
GET /cob | P1 | Listar cobranças com paginação | parametros.paginacao, filtros |
Pix Recebidos (/pix)
| Método | Prioridade | Caso de Teste | Validações |
|---|---|---|---|
GET /pix/{e2eid} | P0 | Consultar Pix por endToEndId | e2eid, txid, valor, horario |
PUT /pix/{e2eid}/devolucao/{id} | P0 | Solicitar devolução (MD06) | rtrId, status, motivo |
GET /pix/{e2eid}/devolucao/{id} | P1 | Consultar status devolução | status, horario, motivo |
GET /pix | P1 | Listar Pix por período | inicio, fim, paginacao |
Priorize P0 para o primeiro ciclo de testes. P1 pode ser implementado em paralelo ou na segunda iteração.
03
Security Tests
OWASP API Top 10, OAuth/mTLS validation, and injection vectors for financial APIs.
OWASP API Security Top 10
| ID | Vulnerabilidade | Testes Específicos |
|---|---|---|
| API1:2023 | Broken Object Level Authorization | Tentar acessar /cob/{txid} de outro usuário; Manipular e2eid para consultar Pix alheio |
| API2:2023 | Broken Authentication | Testar tokens expirados, revogados, sem escopo; Validar mTLS certificate binding |
| API3:2023 | Broken Object Property Level Authorization | Mass Assignment: tentar alterar campos readonly como status, horario; Verificar se response expõe dados sensíveis |
| API4:2023 | Unrestricted Resource Consumption | Validar rate limiting; Testar timeout de 15s; DoS com requests paralelos |
| API5:2023 | Broken Function Level Authorization | Acessar endpoints administrativos; Testar escalação de privilégio em escopos OAuth |
| API6:2023 | Unrestricted Access to Sensitive Business Flows | Automação de criação massiva de cobranças; Abuse de devoluções |
| API7:2023 | Server-Side Request Forgery (SSRF) | Testar webhookUrl com endereços internos/localhost; Validar sanitização de URLs |
| API8:2023 | Security Misconfiguration | Headers de segurança (HSTS, CSP); Verificar error handling não expõe stack traces |
| API9:2023 | Improper Inventory Management | Mapear endpoints não documentados; Verificar versões antigas da API expostas |
| API10:2023 | Unsafe Consumption of APIs | Validar integração com DICT; Testar respostas malformadas de parceiros |
Validação OAuth 2.0 + mTLS
| Cenário | Resultado | Validação |
|---|---|---|
| Token válido + certificado correto | 200 OK | Request processado normalmente |
| Token válido + certificado diferente | 401 | cnf claim não corresponde ao certificado |
| Token expirado | 401 | TokenExpirado |
| Token sem escopo necessário | 403 | AcessoNegado - escopo insuficiente |
| Certificado expirado | Falha TLS | Handshake falha antes do request |
| Certificado revogado (CRL/OCSP) | Falha TLS | Verificar validação de revogação |
| Certificado auto-assinado | Falha TLS | Não aceito conforme regulamentação |
| Token com audience incorreto | 401 | TokenInvalido |
Segurança de Webhooks
- • SSRF: Bloquear URLs internas (localhost, 127.0.0.1, ranges privados)
- • DNS Rebinding: Resolver DNS uma única vez antes de conectar
- • Validação de Protocolo: Aceitar apenas https://, rejeitar file://, gopher://
Validar certificados mTLS, escopos OAuth, e rate limiting manualmente a cada deploy não escala. DAST automatizado no pipeline detecta vulnerabilidades antes que cheguem a produção.
A Voidr executa DAST, valida specs OpenAPI, e centraliza resultados em um único dashboard.
Ver como funciona: Segurança & Compliance04
Synthetic Monitoring
Monitoring scenarios, regulatory SLAs, and alert configuration.
Cenários de Monitoramento Recomendados
| Cenário | Frequência | SLA | Alertas |
|---|---|---|---|
| Health Check OAuth | 1 min | < 500ms | PagerDuty P1, Slack #alerts |
| Token Refresh Flow | 5 min | < 1000ms | Slack, Grafana |
| Criar + Consultar Cob | 5 min | < 2000ms | Email, Slack, Grafana |
| Webhook Delivery | 5 min | < 5000ms | PagerDuty P1 |
| Consulta DICT | 5 min | < 1500ms | Slack, Datadog |
| Fluxo E2E Pagamento | 15 min | < 10000ms | Todos os canais |
SLAs Regulatórios (Manual de Segurança do Pix)
- • Disponibilidade: Mínimo 99.5% mensal por endpoint
- • Timeout: Máximo 15 segundos para operações síncronas
- • Janela de manutenção: Comunicação prévia ao BACEN
Configure alertas em múltiplos canais (Slack, PagerDuty, email) para garantir resposta rápida a incidentes.
05
Performance Tests
Load profiles (smoke, load, stress, soak), traffic distribution and acceptance criteria.
Perfis de Carga
| Tipo | VUs | Duração | Objetivo |
|---|---|---|---|
| Smoke Test | 1-5 | 1 min | Validar scripts e ambiente de teste |
| Load Test | 100-500 | 30 min | Carga normal de produção |
| Stress Test | 500-2000 | 15 min | Encontrar breaking point |
| Spike Test | 0→1000→0 | 10 min | Picos súbitos (flash sale, 5º dia útil) |
| Soak Test | 200-300 | 4-8 horas | Memory leaks, degradação gradual |
| Breakpoint Test | Ramp up | Até falha | Capacidade máxima absoluta |
Distribuição Realista de Tráfego
| Endpoint | Tráfego | Think Time | Pacing |
|---|---|---|---|
POST /cob/{txid} (criar cobrança) | 40% | 1-3s | Random |
GET /cob/{txid} (consultar cobrança) | 35% | 0.5-1s | Constant |
GET /pix (listar recebimentos) | 15% | 2-5s | Random |
PUT /pix/{e2eid}/devolucao (devolução) | 8% | 5-10s | Random |
Webhook callbacks (simulado) | 2% | N/A | Async |
Critérios de Aceitação
Error Rate < 1%
P95 Latência < 2s
Throughput ≥ 500 TPS
Recuperação < 60s
CPU/Memory < 80%
Execute Soak Tests (4h+) regularmente para detectar memory leaks e degradação gradual que não aparecem em testes curtos.
06
Service Virtualization
Mock server for BACEN APIs, stateful stubs and fault injection.
Arquitetura de Ambiente de Testes
┌─────────────────────────────────────────────────────────────────┐
│ Ambiente de Testes Isolado │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Testes │────▶│ Mock Server │────▶│ Webhook │ │
│ │ E2E │ │ (API BACEN) │ │ Simulator │ │
│ └─────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ │ ┌───────┴───────┐ │ │
│ │ ▼ ▼ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Stateful │ │ Fault │ │ │
│ │ │ Stubs │ │ Injection│ │ │
│ │ └──────────┘ └──────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Virtualização permite testar sem dependência do ambiente real do BACEN
Cenários de Simulação
| Cenário | Comportamento | Caso de Uso |
|---|---|---|
| Happy Path | Respostas 2xx padrão | Desenvolvimento ágil, testes básicos |
| Timeout Simulation | Delay 16s → 504 Gateway Timeout | Teste de resiliência e circuit breaker |
| Rate Limiting | 429 após N requests/min | Validar exponential backoff/retry |
| Partial Failure | 50% erros aleatórios | Chaos engineering, fallback logic |
| Webhook Delay | Callback após 30min | Polling vs push, reconciliação |
| Certificate Error | Falha mTLS simulada | Handling de erros de certificado |
Mocks stateful permitem simular fluxos completos (criar cobrança → receber pagamento → processar webhook) sem integração real.
07
Synthetic Data
Generation of valid txid, e2eid, CPF/CNPJ without real data (LGPD).
Campos e Regras de Geração
| Campo | Tipo | Regra |
|---|---|---|
txid | String [26-35] | [a-zA-Z0-9]{26,35} único por CNPJ recebedor |
endToEndId (e2eid) | String [32] | E + ISPB(8) + DATA(8) + SEQ(11) + CTRL(5) |
chave (CPF) | String [11] | Faker CPF válido com dígito verificador correto |
chave (CNPJ) | String [14] | Faker CNPJ válido com dígito verificador correto |
chave (Email) | String [max 77] | user{uuid}@testdomain.pix.test |
chave (Telefone) | String [14] | +5511999{random(6)} - formato E.164 |
valor.original | Decimal [16,2] | Random 0.01-999999.99 (distribuição log-normal) |
devedor.nome | String [max 200] | Faker.name() locale pt-BR |
Exemplo: Geração de Dados PIXtypescript
import { faker } from '@faker-js/faker/locale/pt_BR';
// txid: 26-35 caracteres alfanuméricos
const txid = faker.string.alphanumeric({ length: 32 });
// CPF válido com dígito verificador
const cpf = generateValidCPF();
// endToEndId no formato BACEN
const e2eid = `E${ispb}${dateStr}${seq}${ctrl}`;
// Valor com distribuição realista
const valor = faker.finance.amount({ min: 0.01, max: 999999.99 });Conformidade LGPD
- • Zero dados reais: Dados sintéticos não contêm PII de pessoas existentes
- • Não-reversibilidade: Impossível reconstruir dados originais a partir dos sintéticos
- • Isolamento total: Ambientes de teste segregados de produção
08
CI/CD Pipeline
Quality gates per stage: linting, contract tests, DAST, load tests.
Pipeline de Qualidade
┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────┐
│ Pre- │──▶│ Build │──▶│ Integration │──▶│ Staging │──▶│ Production │
│ commit │ │ │ │ │ │ │ │ │
└──────────┘ └──────────┘ └─────────────┘ └──────────┘ └────────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌────────────┐
│Linting │ │ Unit │ │ Smoke │ │Regressivo│ │ Canary │
│OpenAPI │ │ Contract │ │ Tests │ │ Security │ │ Monitoring │
│ Schema │ │ Tests │ │ E2E │ │ Load │ │ Sintético │
└────────┘ └──────────┘ └───────────┘ └──────────┘ └────────────┘
Gates de qualidade em cada estágio previnem regressões em produção
GitHub Actions: Pipeline PIXyaml
name: PIX API Quality Gates
on: [push, pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate OpenAPI Schema
run: npx @stoplight/spectral lint openapi.yaml
- name: Contract Tests
run: npx prism proxy openapi.yaml --errors
- name: Functional Tests
run: npm run test:pix-api
- name: Security Scan (OWASP)
run: npm run security:scan
- name: Performance Baseline
run: npm run perf:smokeOrquestrar contract testing, DAST, e load testing em pipelines separados gera overhead de manutenção e resultados fragmentados entre ferramentas.
A Voidr executa todos os gates de qualidade em um único workflow e reporta resultados consolidados por PR.
Ver como funciona: Automação de Testes09
Checklist
Verification list for infrastructure, tests, security and compliance.
Infraestrutura
0/6
Testes Funcionais
0/6
Testes de Segurança
0/7
Performance
0/5
Dados e Compliance
0/5
Use este checklist como guia de implementação. O progresso é salvo automaticamente no seu navegador.
10
Próximo Passo
Automatize testes e monitoramento de APIs PIX com IA
AI Agent
AI Agent para APIs PIX
Gera casos de teste a partir da spec OpenAPI, executa em cada PR, e atualiza testes automaticamente quando a API muda. Roda na sua cloud.
Geração a partir de OpenAPI
Atualização automática de testes
Execução em cada PR