Seguridad y manejo de datos

Autenticación

La API se llama con una API key: el prefijo de la marca (veriko_) seguido de 64 caracteres hexadecimales aleatorios. La clave identifica a la cuenta y determina sus permisos y su cuota; no firma la petición ni caduca por sí sola. Ver autenticación.

En el servidor la clave no se guarda en claro. Las lecturas ordinarias —GET /v1/users/me/api-key (sólo con la sesión de la consola, no con la API key) y el panel— devuelven únicamente el prefijo y los cuatro últimos caracteres. El valor completo se muestra al generarla, y la consola puede volver a mostrarlo después exigiendo la contraseña de la cuenta, con bloqueo de quince minutos tras tres intentos fallidos.

Qué se guarda de cada validación

Una validación conserva el material con el que se emitió el veredicto, y ese material es el contenido de un comprobante SPEI:

• Lo enviado en la petición: fecha, monto, clave de rastreo o referencia numérica, bancos y las cuentas que se hayan mandado.
• El comprobante subido, cuando la validación se hace desde imagen, junto con los datos que la extracción leyó de él. Si al validar se solicita no conservarlo, el archivo se borra al terminar la validación y sólo se conservan los datos leídos.
• El CEP emitido por Banxico, cuando existe: su XML y su PDF, más los campos ya interpretados — nombre del ordenante y del beneficiario, RFC de cada uno cuando el comprobante los trae, las dos cuentas, el banco de cada parte, el monto, el IVA y el concepto del pago.

De ahí se sigue lo que conviene tener presente antes de integrar: el historial de una cuenta contiene datos personales de terceros —de quien envió y de quien recibió cada pago—, no sólo números de cuenta. Tratarlos es responsabilidad de quien integra.

Lo que no se guarda, porque la API nunca lo pide: los datos de autorización de un instrumento de pago —código de verificación, fecha de vencimiento, NIP—. Ninguno interviene en una validación SPEI.

Números de cuenta

Las cuentas beneficiarias guardadas, y las que viajan en cada validación, se conservan legibles: son el dato con el que se consulta a Banxico y con el que se concilia una transferencia. No se cifran a nivel de columna.

En las interfaces de Veriko, un número de tarjeta se enmascara y deja visibles los cuatro últimos dígitos; una CLABE se conserva completa. El criterio, y el caso del comprobante que llega ya enmascarado de origen, están en enmascarado de datos sensibles.

Imágenes subidas

Toda imagen que entra por POST /v1/validate-ocr pasa por un saneado que falla cerrado: si un paso no puede completarse, la petición se rechaza con 422 y la imagen no se persiste.

1. Tamaño: 40 bytes como mínimo, 12 MB como máximo.
2. Formato: sólo JPEG, PNG y WebP, detectado por los bytes de cabecera y no por la extensión. Un PDF sigue su propio saneado, descrito abajo.
3. Contraste de MIME: el tipo que dicen los bytes de cabecera y el que reporta el análisis del archivo tienen que coincidir.
4. Análisis estructural: la imagen tiene que parsearse, con un tope de 12 000 px por eje y de 60 megapíxeles en total.
5. Rastreo de polyglot: se rechaza el cuerpo que además sea un archivo de otro formato.
6. Retirada de metadatos: EXIF, XMP, perfiles ICC, bloques de texto en PNG y bloques VP8X en WebP. Ahí viajan la geolocalización, el modelo del teléfono y la fecha original de la foto.
7. Revalidación: la imagen ya limpia debe conservar sus dimensiones y su tipo.

Cuando la imagen se recupera de una image_url, la descarga se endurece aparte: sólo HTTPS, resolución de DNS con rechazo de direcciones privadas y reservadas —y con la dirección validada fijada en la conexión, para que no la cambie una resolución posterior—, un máximo de tres redirecciones que vuelven a pasar el mismo filtro, verificación estricta del certificado, tope de tamaño vigilado sobre el flujo y tiempos de espera de 5 y 15 segundos.

PDF subidos

Un comprobante en PDF también entra por POST /v1/validate-ocr. Nunca se convierte en imagen ni se reescribe: se revisa su estructura y, si pasa, se conserva y se procesa tal como llegó. Como el archivo no se reescribe, sus metadatos se conservan. El saneado también falla cerrado, con su propio código de error en cada caso:

1. Tamaño y firma: el mismo tope de 12 MB, y %PDF- en el primer byte.
2. Estructura: tiene que parsearse, sin datos después del final del documento y con topes de objetos y de anidamiento (pdf_invalid_structure).
3. Cifrado: se rechaza un PDF cifrado o con contraseña (pdf_encrypted).
4. Contenido activo: JavaScript, acciones automáticas, archivos adjuntos, formularios y anotaciones que no sean enlaces (pdf_active_content).
5. Contenido oculto: capas opcionales, formularios y texto fuera del área visible de la página (pdf_hidden_content).
6. Revisiones: un PDF modificado después de emitirse, con más de una revisión (pdf_modified_after_issue).
7. Páginas: de 1 a 3, contadas antes de leer el texto (pdf_too_many_pages).
8. Imágenes internas: se rechaza la codificación JBIG2 y cualquier imagen de más de 60 megapíxeles (pdf_unsupported_image).
9. Capa de texto: un tope de caracteres por página y por documento (pdf_text_layer_too_large).

El texto que trae el documento se trata como dato del comprobante, nunca como instrucción. Al descargarlo, GET /v1/validations/{id}/image entrega un PDF siempre como adjunto y con Content-Security-Policy: sandbox.

Webhooks salientes

Cada entrega se firma con HMAC-SHA256 sobre el cuerpo JSON, con un secreto propio de cada endpoint. El secreto lo genera el servidor al crear el endpoint y se rota con POST /v1/webhooks/{id}/regenerate-secret. La firma viaja en:

X-Webhook-Signature: sha256=<hex>

El detalle de la verificación, los reintentos y el apagado automático está en arquitectura de webhooks.

Retención y borrado

Los comprobantes subidos se conservan cinco años porque el artículo 30 del Código Fiscal de la Federación fija ese plazo para la documentación comprobatoria. Cumplido, el archivo se borra del almacenamiento y la validación permanece con su veredicto: la descarga del comprobante responde entonces que ya no está disponible. Ese plazo es el predeterminado. Quien integra puede solicitar que el comprobante no se conserve o borrarlo antes; en ese caso, la conservación que exija su propia obligación fiscal queda a su cargo.

DELETE /v1/validations/{id} y DELETE /v1/beneficiaries/{id} marcan el registro, no lo borran. La validación sigue siendo consultable por la propia cuenta —aparece en el listado con su fecha de borrado— y el beneficiario pasa a inactivo; ninguna de las dos operaciones retira nada del almacenamiento. El borrado definitivo, descrito a continuación, sí lo retira.

El borrado efectivo se puede hacer de dos maneras. La primera es validación por validación, desde la consola o la API, en dos pasos: primero se muestra qué se va a borrar y después se confirma. Se borran el comprobante, el CEP, los datos leídos y la copia de esa información en avisos y registros; se conserva únicamente un registro mínimo (veredicto, fechas y monto) para mantener correctos el consumo registrado y los reportes financieros. No se puede deshacer, no devuelve el consumo y no modifica las copias de respaldo. La segunda va atada a la cuenta: al eliminarla empieza un plazo de gracia de treinta días, con un correo al pedir la baja, dos avisos antes de que termine (siete días y un día antes) y una confirmación al completarse el borrado, y con los webhooks de la cuenta en pausa mientras dura; cumplido el plazo se eliminan las validaciones y sus archivos en disco (comprobantes subidos y PDF del CEP), los beneficiarios, los endpoints de webhook con sus entregas, las notificaciones, las sesiones, las claves de idempotencia y el consumo de cuota. Lo que la obligación fiscal exige conservar (los recibos de pago, los reembolsos y los créditos) permanece con el identificador de la cuenta desvinculado hasta el plazo del artículo 30 del Código Fiscal de la Federación: se borra a partir del 1 de enero del séptimo año posterior al de cada registro.

Cumplimiento

Hoy no hay ninguna atestación formal de terceros: ni SOC 2, ni ISO 27001. Quien necesite una para poder integrar conviene que lo plantee antes de empezar.

Una revisión de seguridad, un cuestionario de proveedor, un acuerdo de tratamiento de datos o una solicitud de borrado de un usuario final se coordinan con el equipo de seguridad. La política de divulgación de vulnerabilidades, y la dirección a la que escribir, se publican conforme al RFC 9116 en /.well-known/security.txt del sitio principal.