01
Alcance y Requisitos
APIs cubiertas, requisitos mTLS/OAuth 2.0, y normativas BACEN aplicables.
APIs Cubiertas en este Playbook
| Recurso | Endpoint | Descripción |
|---|---|---|
| Cobro Inmediato | /cob e /cob/{txid} | CRUD de cobros inmediatos con QR Code |
| Cobro con Vencimiento | /cobv e /cobv/{txid} | Cobros con fecha de vencimiento (boleto PIX) |
| PIX Recibidos | /pix e /pix/{e2eid} | Consulta y devolución de pagos PIX recibidos |
| Webhook | /webhook/{chave} | Configuración de notificaciones push |
| Location (Payload) | /loc e /loc/{id} | Gestión de payloads para QR Code |
| PIX Automático (Rec) | /rec e /rec/{idRec} | Gestión de recurrencias (débito automático) |
| Lote CobV | /lotecobv/{id} | Creación y gestión de lotes de cobros con vencimiento |
| Solicitud Rec | /solicrec/{idSolicRec} | Confirmación de autorización de recurrencia |
PIX API v2.9.0 — Requisitos de Seguridad
- • mTLS obligatorio: Certificado ICP-Brasil (producción) o emitido por el PSP (homologación)
- • OAuth 2.0 Client Credentials: Alcances específicos por recurso (cob.read, cob.write, pix.read)
- • RFC 8705: Token vinculado al certificado TLS — impide el uso del token en otra conexión
Normativas Aplicables
| Normativa | Alcance de Aplicación |
|---|---|
| Resolución BCB No. 1/2020 | Regulación base del arreglo PIX |
| Manual de Seguridad del PIX | Requisitos técnicos de seguridad |
| Manual de APIs PIX | Especificaciones técnicas de las APIs |
| Resolución Conjunta No. 6/2023 | Compartición de indicios de fraude |
| Circular BCB No. 3.978/2020 | Prevención del lavado de dinero |
| LGPD (Ley 13.709/2018) | Protección de datos personales |
Mantenga un mapeo entre cada normativa y los casos de prueba correspondientes para facilitar auditorías.
02
Tests Funcionales
Matriz de casos de test para /cob, /cobv, /pix y /webhook con priorización P0/P1.
Cobro Inmediato (/cob)
| Método | Prioridad | Caso de Prueba | Validaciones |
|---|---|---|---|
POST /cob/{txid} | P0 | Crear cobro con valor fijo | HTTP 201, txid, location, QR Code |
POST /cob/{txid} | P0 | Crear cobro Pix Retiro | modalidadeAlteracao, retirada |
POST /cob/{txid} | P1 | Crear cobro Pix Cambio | valor.original, valor.troco |
GET /cob/{txid} | P0 | Consultar cobro existente | status, calendario, valor, chave |
PATCH /cob/{txid} | P1 | Revisar cobro (cambiar estado) | status REMOVIDA_PELO_USUARIO |
GET /cob | P1 | Listar cobros con paginación | parametros.paginacao, filtros |
PIX Recibidos (/pix)
| Método | Prioridad | Caso de Prueba | Validaciones |
|---|---|---|---|
GET /pix/{e2eid} | P0 | Consultar PIX por endToEndId | e2eid, txid, valor, horario |
PUT /pix/{e2eid}/devolucao/{id} | P0 | Solicitar devolución (MD06) | rtrId, status, motivo |
GET /pix/{e2eid}/devolucao/{id} | P1 | Consultar estado de devolución | status, horario, motivo |
GET /pix | P1 | Listar PIX por período | inicio, fim, paginacao |
Priorice P0 para el primer ciclo de pruebas. P1 puede implementarse en paralelo o en la segunda iteración.
03
Tests de Seguridad
OWASP API Top 10, validación OAuth/mTLS, y vectores de inyección para APIs financieras.
OWASP API Security Top 10
| ID | Vulnerabilidad | Pruebas Específicas |
|---|---|---|
| API1:2023 | Broken Object Level Authorization | Intentar acceder a /cob/{txid} de otro usuario; Manipular e2eid para consultar PIX ajeno |
| API2:2023 | Broken Authentication | Probar tokens expirados, revocados, sin alcance; Validar mTLS certificate binding |
| API3:2023 | Broken Object Property Level Authorization | Mass Assignment: intentar alterar campos readonly como status, horario; Verificar si response expone datos sensibles |
| API4:2023 | Unrestricted Resource Consumption | Validar rate limiting; Probar timeout de 15s; DoS con requests paralelos |
| API5:2023 | Broken Function Level Authorization | Acceder a endpoints administrativos; Probar escalación de privilegios en alcances OAuth |
| API6:2023 | Unrestricted Access to Sensitive Business Flows | Automatización de creación masiva de cobros; Abuso de devoluciones |
| API7:2023 | Server-Side Request Forgery (SSRF) | Probar webhookUrl con direcciones internas/localhost; Validar sanitización de URLs |
| API8:2023 | Security Misconfiguration | Headers de seguridad (HSTS, CSP); Verificar que el error handling no exponga stack traces |
| API9:2023 | Improper Inventory Management | Mapear endpoints no documentados; Verificar versiones antiguas de la API expuestas |
| API10:2023 | Unsafe Consumption of APIs | Validar integración con DICT; Probar respuestas malformadas de socios |
Validación OAuth 2.0 + mTLS
| Escenario | Resultado | Validación |
|---|---|---|
| Token válido + certificado correcto | 200 OK | Request procesado normalmente |
| Token válido + certificado diferente | 401 | cnf claim no corresponde al certificado |
| Token expirado | 401 | TokenExpirado |
| Token sin alcance necesario | 403 | AcessoNegado - alcance insuficiente |
| Certificado expirado | Fallo TLS | Handshake falla antes del request |
| Certificado revocado (CRL/OCSP) | Fallo TLS | Verificar validación de revocación |
| Certificado auto-firmado | Fallo TLS | No aceptado según regulación |
| Token con audience incorrecto | 401 | TokenInvalido |
Seguridad de Webhooks
- • SSRF: Bloquear URLs internas (localhost, 127.0.0.1, rangos privados)
- • DNS Rebinding: Resolver DNS una única vez antes de conectar
- • Validación de Protocolo: Aceptar solo https://, rechazar file://, gopher://
Validar certificados mTLS, alcances OAuth y rate limiting manualmente en cada deploy no escala. DAST automatizado en el pipeline detecta vulnerabilidades antes de que lleguen a producción.
Voidr ejecuta DAST, valida specs OpenAPI y centraliza resultados en un único dashboard.
Ver como funciona: Segurança & Compliance04
Monitoreo Sintético
Escenarios de monitoreo, SLAs regulatorios, y configuración de alertas.
Escenarios de Monitoreo Recomendados
| Escenario | Frecuencia | SLA | Alertas |
|---|---|---|---|
| Health Check OAuth | 1 min | < 500ms | PagerDuty P1, Slack #alerts |
| Token Refresh Flow | 5 min | < 1000ms | Slack, Grafana |
| Crear + Consultar Cob | 5 min | < 2000ms | Email, Slack, Grafana |
| Webhook Delivery | 5 min | < 5000ms | PagerDuty P1 |
| Consulta DICT | 5 min | < 1500ms | Slack, Datadog |
| Flujo E2E Pago | 15 min | < 10000ms | Todos los canales |
SLAs Regulatorios (Manual de Seguridad del PIX)
- • Disponibilidad: Mínimo 99.5% mensual por endpoint
- • Timeout: Máximo 15 segundos para operaciones síncronas
- • Ventana de mantenimiento: Comunicación previa al BACEN requerida
Configure alertas en múltiples canales (Slack, PagerDuty, email) para garantizar respuesta rápida a incidentes.
05
Tests de Performance
Perfiles de carga (smoke, load, stress, soak), distribución de tráfico y criterios de aceptación.
Perfiles de Carga
| Tipo | VUs | Duración | Objetivo |
|---|---|---|---|
| Smoke Test | 1-5 | 1 min | Validar scripts y ambiente de prueba |
| Load Test | 100-500 | 30 min | Carga normal de producción |
| Stress Test | 500-2000 | 15 min | Encontrar breaking point |
| Spike Test | 0→1000→0 | 10 min | Picos súbitos (flash sale, día de pago) |
| Soak Test | 200-300 | 4-8 horas | Memory leaks, degradación gradual |
| Breakpoint Test | Ramp up | Hasta fallo | Capacidad máxima absoluta |
Distribución Realista de Tráfico
| Endpoint | Tráfico | Think Time | Pacing |
|---|---|---|---|
POST /cob/{txid} (crear cobro) | 40% | 1-3s | Random |
GET /cob/{txid} (consultar cobro) | 35% | 0.5-1s | Constant |
GET /pix (listar recibidos) | 15% | 2-5s | Random |
PUT /pix/{e2eid}/devolucao (devolución) | 8% | 5-10s | Random |
Webhook callbacks (simulado) | 2% | N/A | Async |
Criterios de Aceptación
Error Rate < 1%
P95 Latency < 2s
Throughput ≥ 500 TPS
Recuperación < 60s
CPU/Memory < 80%
Ejecute Soak Tests (4h+) regularmente para detectar memory leaks y degradación gradual que no aparecen en pruebas cortas.
06
Virtualización de Servicios
Mock server para APIs BACEN, stubs stateful e inyección de fallas.
Arquitectura de Ambiente de Pruebas
┌─────────────────────────────────────────────────────────────────┐
│ Ambiente de Testes Isolado │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Testes │────▶│ Mock Server │────▶│ Webhook │ │
│ │ E2E │ │ (API BACEN) │ │ Simulator │ │
│ └─────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ │ ┌───────┴───────┐ │ │
│ │ ▼ ▼ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Stateful │ │ Fault │ │ │
│ │ │ Stubs │ │ Injection│ │ │
│ │ └──────────┘ └──────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
La virtualización permite probar sin dependencia del ambiente real de BACEN
Escenarios de Simulación
| Escenario | Comportamiento | Caso de Uso |
|---|---|---|
| Happy Path | Respuestas 2xx estándar | Desarrollo ágil, pruebas básicas |
| Timeout Simulation | Delay 16s → 504 Gateway Timeout | Prueba de resiliencia y circuit breaker |
| Rate Limiting | 429 tras N requests/min | Validar exponential backoff/retry |
| Partial Failure | 50% errores aleatorios | Chaos engineering, fallback logic |
| Webhook Delay | Callback tras 30min | Polling vs push, reconciliación |
| Certificate Error | Fallo mTLS simulado | Manejo de errores de certificado |
Los mocks stateful permiten simular flujos completos (crear cobro → recibir pago → procesar webhook) sin integración real.
07
Datos Sintéticos
Generación de txid, e2eid, CPF/CNPJ válidos sin datos reales (LGPD).
Campos y Reglas de Generación
| Campo | Tipo | Regla |
|---|---|---|
txid | String [26-35] | [a-zA-Z0-9]{26,35} único por CNPJ receptor |
endToEndId (e2eid) | String [32] | E + ISPB(8) + FECHA(8) + SEQ(11) + CTRL(5) |
chave (CPF) | String [11] | CPF válido con dígito verificador correcto |
chave (CNPJ) | String [14] | CNPJ válido con dígito verificador correcto |
chave (Email) | String [max 77] | user{uuid}@testdomain.pix.test |
chave (Teléfono) | String [14] | +5511999{random(6)} - formato E.164 |
valor.original | Decimal [16,2] | Random 0.01-999999.99 (distribución log-normal) |
devedor.nome | String [max 200] | Faker.name() locale pt-BR |
Ejemplo: Generación de Datos 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 });Cumplimiento LGPD
- • Cero datos reales: Los datos sintéticos no contienen PII de personas reales
- • No reversibilidad: Imposible reconstruir datos originales a partir de los sintéticos
- • Aislamiento total: Ambientes de prueba segregados de producción
08
Pipeline CI/CD
Gates de calidad por etapa: linting, contract tests, DAST, load tests.
Pipeline de Calidad
┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────┐
│ Pre- │──▶│ Build │──▶│ Integration │──▶│ Staging │──▶│ Production │
│ commit │ │ │ │ │ │ │ │ │
└──────────┘ └──────────┘ └─────────────┘ └──────────┘ └────────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌────────────┐
│Linting │ │ Unit │ │ Smoke │ │Regressivo│ │ Canary │
│OpenAPI │ │ Contract │ │ Tests │ │ Security │ │ Monitoring │
│ Schema │ │ Tests │ │ E2E │ │ Load │ │ Sintético │
└────────┘ └──────────┘ └───────────┘ └──────────┘ └────────────┘
Quality gates en cada etapa previenen regresiones en producción
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:smokeOrquestar contract testing, DAST y load testing en pipelines separados genera overhead de mantenimiento y resultados fragmentados entre herramientas.
Voidr ejecuta todos los quality gates en un único workflow y reporta resultados consolidados por PR.
Ver como funciona: Automação de Testes09
Checklist
Lista de verificación para infraestructura, tests, seguridad y compliance.
Infraestructura
0/6
Pruebas Funcionales
0/6
Pruebas de Seguridad
0/7
Performance
0/5
Datos y Compliance
0/5
Use este checklist como guía de implementación. El progreso se guarda automáticamente en su navegador.
10
Próximo Paso
Automatice pruebas y monitoreo de APIs PIX con IA
AI Agent
AI Agent para APIs PIX
Genera casos de prueba a partir de la spec OpenAPI, ejecuta en cada PR y actualiza pruebas automáticamente cuando la API cambia. Corre en su cloud.
Generación desde OpenAPI
Actualización automática de pruebas
Ejecución en cada PR