PetraOS

El reto está en el cambio de responsable

La venta de combustible no se resuelve en una sola transacción ni en una sola pantalla. Una solicitud pasa por ventas, validación del cliente, contratos, finanzas y logística antes de que el autotanque llegue a su destino. Cada área necesita una vista distinta de la misma operación y un criterio claro para avanzar o detenerla.

PetraOS es la plataforma que desarrollé y desplegué recientemente para PetroMex. Trabajé directamente con la organización para conocer sus procedimientos operativos y llevar esos cambios de responsabilidad al software. Está dirigida al personal comercial y de operaciones, con espacios separados para clientes y revisión documental.

El problema no era la falta de un tablero. Era mantener vinculados la operación comercial, las comunicaciones, las autorizaciones, los documentos y los registros de entrega al pasar de un responsable a otro.

Mi participación: del levantamiento al despliegue

Como consultor de tecnología y desarrollador de producto, traduzco los requerimientos de la operación al sistema: levantamiento directo de procedimientos, diseño de flujos e interfaces, implementación asistida por IA y coordinación del despliegue. Utilizo herramientas de desarrollo con IA a lo largo del proyecto; este caso no presenta su aportación como programación realizada sin asistencia.

PetroMex aporta el conocimiento operativo y las decisiones de negocio. Mi responsabilidad es hacer explícitas esas reglas, conectar los registros y presentar las excepciones de forma que el personal pueda resolverlas. Una validación del sistema respalda esa responsabilidad; no sustituye a quien autoriza la operación.

Una operación, once etapas registradas

El flujo implementado registra solicitud, cotización, aceptación, calificación del cliente, preparación del contrato, firma, contrafirma, facturación, pago, ejecución logística y cierre. Sus estados en el código son:

INQUIRY → QUOTED → ACCEPTED → QUALIFIED → CONTRACTED → SIGNED → COUNTERSIGNED → INVOICED → PAID → FULFILLMENT → COMPLETED

Esta secuencia establece un lenguaje común; no supone que todas las ventas sigan pasos idénticos. El validador permite avanzar varias etapas y retroceder una a la vez. Exige la aprobación del expediente de conocimiento del cliente —KYC— para ingresar a cualquier etapa posterior a la calificación. No impone una regla universal de pago previo a la ejecución: las operaciones nacionales y las marítimas tienen condiciones distintas.

Ejemplo ilustrativo, sin datos de clientes: una operación calificada del “Cliente A” tiene el KYC pendiente. El sistema rechaza el avance a preparación del contrato. Con el KYC aprobado, permite esa misma transición. La demostración que acompaña este caso reproduce la regla de forma local; no consulta la aplicación privada ni realiza una autorización real.

El expediente operativo como punto de unión

La aplicación en Next.js atiende el portal del personal y los flujos para clientes. Las rutas de API utilizan lógica de negocio compartida; Supabase aporta base de datos, autenticación y almacenamiento documental. Los registros de la operación vinculan comunicaciones, cotizaciones, contratos, viajes y eventos para que el personal no tenga que reconstruir ese contexto por separado.

El repositorio incluye recepción y envío de correo, integración de WhatsApp mediante Twilio, uso del SDK de Anthropic, generación de PDF y una integración de firma electrónica. Son capacidades identificadas en la implementación, no una confirmación de que todos los proveedores estén configurados, activos o en uso productivo. La aplicación está desplegada en Vercel; desplegarla no equivale a poner en servicio todas sus integraciones.

El manejo fiscal también tiene límites explícitos. La capa de proveedores de facturación revisada incluye una implementación simulada; este caso no acredita timbrado CFDI en producción. Los auxiliares de Carta Porte preparan campos de solicitud y extraen un folio fiscal, pero extraer ese identificador no acredita la autenticidad del documento ni valida su firma digital.

Tres decisiones que van más allá de la interfaz

Aplicar la regla donde se modifica el registro. Ocultar un botón no constituye un control de autorización. Las comprobaciones de KYC se aplican en la validación de etapas y en el endpoint de firma. El repositorio incluye pruebas de regresión para aprobaciones pendientes, rechazadas o ausentes, incluso cuando se intenta firmar después de un cambio en la calificación del cliente.

Reconocer las excepciones legítimas sin permitir cualquier cambio. Una secuencia rígida de pago no representaría las distintas modalidades de venta. El validador separa la regla compartida de KYC del orden de pago, admite avances válidos y limita el retroceso a una etapa. Al reabrir una operación concluida, elimina los campos de resolución para no mantener un caso activo registrado como cerrado.

Distinguir identidad de permisos. Iniciar sesión no autoriza a intervenir en cualquier flujo. Las pruebas de rutas distinguen el acceso de operadores y administradores del acceso de intermediarios, y verifican la vinculación entre token y operación en la ruta correspondiente de confirmación de pago. Es una afirmación más precisa que describir toda la aplicación como “segura”.

Evidencia y alcance de la revisión

Este caso se contrastó con documentación, implementación y definiciones de pruebas del repositorio el 2 de octubre de 2026. Se revisaron, entre otras, stage-transition-rules.test.js, contract-sign-kyc-gate.test.ts, resource-authz-routes.test.ts, auditLog.test.ts, invoiceProvider.test.ts y carta-porte.test.js.

Estas pruebas especifican el comportamiento de los controles de etapas, permisos, registros de auditoría, respuestas ante fallas y auxiliares documentales. Varias utilizan servicios simulados. Su existencia acredita los casos de regresión previstos; no significa que se hayan ejecutado para preparar este caso, que las integraciones externas hayan sido validadas en vivo ni que exista una auditoría de cumplimiento o seguridad concluida.

Desplegado, con los siguientes criterios de evaluación definidos

El hito alcanzado es pasar del levantamiento directo de la operación a una aplicación desplegada, conforme a mi registro profesional actualizado. El desarrollo continúa. No publico cifras de clientes, volumen de transacciones, ahorro o disponibilidad sin una fuente de medición autorizada.

La siguiente evaluación debe medir el tiempo entre responsables, las excepciones pendientes, la integridad documental y la frecuencia con que los usuarios necesitan ayuda para concluir un flujo. Son mediciones propuestas, no resultados alcanzados.

El código del producto es privado. Este caso público presenta el flujo, las decisiones y una demostración con datos ficticios sin exponer expedientes de clientes, credenciales ni acceso al repositorio privado. La terminal cinematográfica es una ilustración editorial del sector, no una grabación del producto desplegado.