Cómo diseñar un sandbox de API útil sin usar patentes ni personas reales
Un entorno de prueba sirve cuando reproduce decisiones y fallas del contrato, no cuando copia expedientes de producción. Los escenarios deterministas hacen posible probar sin PII.
Por Marco Ferreiro ·
Un sandbox no es una producción pequeña. Es un laboratorio con reglas propias que permite probar el contrato sin consultar una patente, una persona ni una infracción real. Su calidad se mide por las decisiones que permite ensayar y por su aislamiento, no por lo realista que parezcan los nombres.
Copiar datos y “borrar algunos campos” conserva riesgos ocultos. Un texto libre, una combinación rara de eventos o un archivo adjunto pueden seguir identificando un caso.
Empezar por decisiones, no por registros
La integración necesita saber qué hacer cuando no hay resultados, cuando una fuente queda pendiente, cuando llega una corrección o cuando se supera un límite. Cada una es una escena de prueba independiente.
Un buen catálogo mínimo incluye:
- éxito sin infracciones;
- resultado con varias fuentes;
- respuesta parcial con una fuente pendiente;
- error transitorio y reintento;
- límite de uso;
- paginación de varios elementos;
- corrección o retiro posterior;
- evento duplicado.
La entrada activa un escenario por un identificador documentado, no por coincidencia con un caso productivo.
Identidades evidentemente ficticias
Los dominios example.com, example.net y example.org están reservados para documentación. RFC 5737 reserva bloques IPv4 para ejemplos. Usarlos evita que una prueba termine contactando por accidente una dirección de terceros.
Para los vehículos se define una sintaxis exclusiva del sandbox que el entorno productivo rechaza y que no se parece a una patente válida. Nunca se toma “una patente vieja” ni se genera al azar hasta que alguna pase el validador real.
Aislamiento que pueda demostrarse
El sandbox tiene credenciales, base, colas y almacenamiento separados. Sus tareas no conocen secretos de proveedores y su red no necesita salida hacia portales oficiales. Si un fixture intenta invocar un adaptador productivo, la prueba falla.
También conviene usar un host distinto, encabezados visibles de entorno y claves que no funcionen fuera del laboratorio. La separación reduce el impacto de una configuración equivocada.
Respuestas conformes al contrato
Ficticio no significa improvisado. Las respuestas deben validar contra el mismo esquema público: tipos, campos opcionales, estados y errores. OpenAPI permite describir ejemplos por operación, pero los fixtures ejecutables deben compartir la validación usada por el servidor.
Cada escenario registra versión del contrato y resultado esperado. Si cambia un enum o se agrega un campo obligatorio, el sandbox falla en CI hasta actualizar la prueba.
Tiempo y asincronía controlables
Una API de consultas puede aceptar una solicitud y completar fuentes después. Esperar minutos reales vuelve los tests lentos e inestables. Un reloj inyectable permite avanzar desde “aceptada” a “parcial” y “completa” en instantes conocidos.
Los webhooks usan IDs deterministas y pueden repetirse para verificar idempotencia. El consumidor debe reconocer el duplicado sin que el sandbox dependa de una entrega externa.
Errores útiles, no aleatorios
Un botón que devuelve cualquier 500 sirve poco. El escenario indica clase de error, si es reintentable, cuántos intentos preceden al éxito y qué encabezados acompañan el límite.
También se prueba una respuesta malformada o truncada, pero desde un fixture marcado. Eso permite asegurar que el cliente no transforma un fallo de transporte en “sin multas”.
Un control automático contra PII
Antes de aceptar un fixture, un gate busca emails fuera de dominios reservados, IP no documentales, formatos de DNI, CUIT, teléfonos, patentes plausibles, nombres de buckets, URLs productivas y claves. El control no reemplaza la revisión, pero evita errores repetidos.
Los textos libres se escriben desde cero. No se pegan descripciones de actas, direcciones ni nombres de organismos asociados a un expediente real.
Qué no demuestra el sandbox
Un escenario verde confirma que el cliente entiende ese contrato. No demuestra que una jurisdicción esté disponible, que el resultado productivo llegue en el mismo tiempo ni que una muestra represente la distribución real.
Por eso la documentación separa “comportamiento simulado” de “cobertura vigente”. Las métricas de laboratorio no se mezclan con SLA ni estadísticas de producción.
Una experiencia que se puede compartir
El equipo recibe claves de prueba, guía de inicio, colección de escenarios y expectativas claras. Puede resetear el estado y repetir el mismo caso. Si necesita un borde nuevo, se agrega al catálogo con una razón, no con un volcado de un cliente.
El resultado es más útil que una copia desactualizada de producción: protege personas, hace reproducibles los errores y obliga a que las decisiones difíciles formen parte del contrato desde el primer día.
Metodología
- Alcance
- Diseño de un entorno aislado para probar el contrato de una API de infracciones sin conectar datos ni proveedores de producción.
- Unidad de análisis
- Escenario versionado con entrada ficticia, respuesta esperada, eventos, latencia simulada y resultado de aserciones.
- Cobertura
- Casos deterministas de vacío, datos, parcial, error, límite, reintento, corrección y paginación.
Limitaciones
- Los tiempos simulados no permiten estimar latencia ni disponibilidad reales.
- Un sandbox valida integración y decisiones, pero no certifica cobertura de fuentes productivas.
Fuentes
- Reserved Top Level DNS Names — RFC Editor (consultada el )
- IPv4 Address Blocks Reserved for Documentation — RFC Editor (consultada el )
- OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el )
- The JavaScript Object Notation Data Interchange Format — RFC Editor (consultada el )
Preguntas frecuentes
¿Se puede anonimizar una copia de producción para el sandbox?
Es más seguro diseñar fixtures sintéticos. Una copia puede conservar combinaciones, texto libre o relaciones que reidentifiquen a una persona.
¿El sandbox debe responder siempre con éxito?
No. Debe incluir errores, parciales, límites, reintentos y correcciones para probar las decisiones que la integración enfrentará.
¿Cómo evitamos que alguien envíe una patente real?
El endpoint de prueba valida una nomenclatura reservada y rechaza entradas con formato productivo; además no consulta proveedores ni bases reales.
Notas relacionadas
Por qué actas e identificadores deben viajar como texto y no como números JSON
Un número de acta no es una cantidad. Serializarlo como número puede quitar ceros, alterar dígitos o producir resultados distintos entre lenguajes.
Timeout no significa “sin multas”: cómo informar resultados parciales en una integración
Cuando una fuente no responde, el resultado es parcial o indeterminado, nunca cero. Un contrato explícito permite reintentar, alertar y decidir sin producir falsos negativos.
Circuit breaker sobre una fuente inestable
Cuando un portal empieza a fallar, insistir empeora las dos puntas. Un corte deliberado y temporal de las llamadas a esa fuente protege al organismo y devuelve antes una respuesta honesta.