Tutorial completo - Administrador
Día a día del Administrador. Configuración inicial del sistema, razones sociales, roles, bitácoras y mantenimiento. Incluye una sección para Pricing.
Para quién es esta guía
Para el rol Administrador: el responsable técnico-operativo del sistema. Configuras lo que el resto del equipo usa, mantienes los catálogos críticos y diagnosticas problemas cuando aparecen.
Tus responsabilidades
Configuración inicial
Razones sociales emisoras, credenciales SAT, tipos de cambio, penalizaciones.
Usuarios y roles
Crear usuarios, asignar roles, ajustar permisos cuando se necesite.
Bitácoras
API logs, email logs, activity log. Diagnóstico de problemas.
Mantenimiento
Comandos artisan periódicos, importación de catálogos SAT, depuración.
Permisos que tienes
Como Administrador tienes todos los permisos del sistema. Puedes ver y hacer cualquier cosa. Por eso la responsabilidad se vuelve principalmente de disciplina y proceso más que de límites técnicos.
Setup inicial del sistema
Si estás llegando a un Embarque recién instalado:
Configura el archivo .env
El instalador técnico debe configurar:
DB_*— credenciales de base de datos.FACTURAPI_SECRET_KEYyFACTURAPI_MODE— sandbox para pruebas, live para producción.FACTURAMA_USER/FACTURAMA_PASSWORD— fallback de timbrado.BANXICO_TOKEN— para tipo de cambio automático.EMPRESA_*— datos del intermediario logístico.MAIL_*— configuración SMTP de salida.SHOW_DEMO_LOGIN=falseen producción.
Importa catálogos SAT
Pídele al técnico ejecutar:
php artisan sat:importar-codigos-postales
Esto carga el catálogo c_CodigoPostal para validar Carta Porte sin pegarle al SAT.
Siembra roles y permisos
php artisan db:seed --class=RoleSeeder
Crea los 8 roles base con sus permisos.
Crea las razones sociales emisoras
Configuración → Razones Sociales → Nueva.
Captura por cada entidad fiscal: RFC, razón social, régimen, código postal de expedición y credenciales del timbrador (FacturAPI o Facturama). Las credenciales se guardan encriptadas.
Crea usuarios iniciales
Configuración → Usuarios. Da de alta a los miembros del equipo y asigna su rol. El sistema envía correo con contraseña inicial.
Carga catálogos comerciales
Da de alta:
- Tipos de servicio (con sus prefijos de folio).
- Tipos de unidad alineados con
c_ConfigVehicular. - Tipos de documento según lo que manejes.
- Empresas de factoraje si aplica.
- Agentes aduanales si operas internacional.
Verifica correo y queue
Pídele al técnico verificar que el queue worker está corriendo (php artisan queue:work) y que el SMTP funcione enviando un correo de prueba.
Tu rutina diaria
Revisa el dashboard general
Estadísticas globales y huecos de asignación: clientes sin vendedor, sin customer service, sin operador.
Atiende notificaciones de errores
Si hay errores recurrentes (timbrado, envío de correo, jobs fallidos), Sentry te avisa. Diagnóstica.
Revisa bitácoras si hay quejas
Configuración → API Requests Log si alguien reporta problema con FacturAPI/Facturama. Email Logs si hay reclamos de correos no recibidos.
Distribuye trabajo por demanda
Asigna operadores a clientes nuevos, ajusta permisos de usuarios cuando cambian de rol.
Tareas frecuentes
Razones sociales emisoras
Configuración → Razones Sociales → Nueva.
- Datos fiscales: RFC, razón social, régimen, código postal de expedición.
- Timbrador: marca
usa_facturapitrue/false. Captura las credenciales correspondientes. - Activa la razón social para que aparezca en el selector al crear embarques.
Las credenciales se guardan encriptadas en la base de datos.
Para pasar una razón social a producción, edítala y cambia FACTURAPI_MODE a live. Cuidado: a partir de ese momento se cobran timbres reales.
Edita la razón social y captura las credenciales nuevas. Las anteriores se sobrescriben encriptadas.
Usuarios y roles
Configuración → Usuarios → Nuevo.
Captura nombre, correo, asigna rol y opcionalmente un vendedor superior o gerente para jerarquías.
El sistema envía correo con contraseña inicial al usuario.
Si un usuario necesita un permiso que su rol no incluye:
- Considera cambiar su rol si el permiso es estructural.
- Si es un permiso ad hoc, asígnalo directamente al usuario desde su perfil.
- Documenta por qué se lo asignaste para auditoría posterior.
Cuando alguien deja la organización, desactívalo en lugar de borrarlo. Esto preserva el histórico de embarques creados, aprobaciones, etc.
Bitácoras y diagnóstico
Configuración → API Requests Log. Cada llamada a APIs externas (FacturAPI, Facturama, Banxico, SAT) queda registrada con:
- Endpoint y método.
- Status code y tiempo de respuesta.
- Payload enviado y respuesta recibida.
Útil cuando un timbrado falla y FacturAPI da un mensaje confuso. Aquí ves exactamente qué se envió.
Configuración → Email Logs. Cada correo enviado por el sistema:
- Destinatario, asunto, adjuntos.
- Fecha y resultado (enviado, fallido).
- Error si falló.
Útil cuando un cliente dice "no me llegó la factura" — verificas si se envió y a qué dirección.
Auditoría a nivel sistema. Registra cambios críticos: cancelaciones, aprobaciones, ediciones de datos sensibles. Consulta cuando hay dudas o auditorías.
Mantenimiento periódico
El SAT actualiza periódicamente sus catálogos (códigos postales, claves de producto, etc.). Re-importa cuando salga una versión nueva:
php artisan sat:importar-codigos-postales
Si detectas pagos PPD sin complemento (revisión periódica):
php artisan complementos:generar-automaticos
Es seguro re-ejecutar — omite los pagos que ya tienen complemento.
El comando programado lo hace automático, pero puedes correrlo manualmente:
php artisan cancelaciones:verificar-pendientes
Archivos subidos pero no asociados quedan en storage temporal. Limpieza periódica:
php artisan uploads:clean-temp
Activa el portal externo para un proveedor:
php artisan portal:habilitar-proveedor {proveedor_id}
Genera credenciales y las envía por correo al contacto del proveedor.
Errores y problemas frecuentes
- API Requests Log → filtra por el embarque.
- Revisa el payload enviado y la respuesta.
- Si el error es de catálogo SAT (CP1xx), sigue Errores de timbrado SAT.
- Si es algo nuevo, contacta a soporte de FacturAPI con el log.
Email Logs → busca por destinatario o asunto. Si dice "enviado", probablemente está en spam del cliente. Si dice "fallido", revisa el error.
Síntoma: complementos no se generan, BOLs no se envían, status SAT no se actualiza. Pide al técnico verificar php artisan queue:work y reiniciar si es necesario.
Sin tipo de cambio del día, los embarques en USD usan el último valor. Captura manual desde Configuración → Tipos de Cambio si Banxico tarda en responder.
Sección para Pricing
El rol Pricing se enfoca en el ecosistema de proveedores: gestión de catálogo, agentes aduanales, empresas de factoraje y reportes de proveedores.
Lo que tienes
| Permiso | Para qué |
|---|---|
proveedores.view / create / edit / delete | CRUD completo de proveedores |
documentos.subirFacturaProveedor / subirCartaPorteProveedor | Cargar documentos del proveedor |
agentes-aduanales.view / create / edit / delete | CRUD completo de agentes aduanales |
factoraje.view / create / edit / delete / empresas | CRUD de operaciones y empresas de factoraje |
reportes.proveedores | Reportes específicos de proveedores |
Tus tareas
Sigue Alta de proveedor nuevo. Cubre captura, choferes, unidades, activación de portal y primera operación.
Cada proveedor debe tener su:
- Constancia fiscal vigente.
- Póliza de seguro vigente.
- Permiso SCT vigente (si es autotransportista).
- Opinión de cumplimiento SAT.
Configura recordatorios cuando se acerquen vencimientos.
Configuración → Empresas de Factoraje. Captura RFC, comisiones por defecto, días de crédito y datos bancarios. Crea el usuario del portal externo.
Para embarques internacionales. Cada agente con su patente, RFC y datos de contacto.
Reportes filtrados por proveedor: volumen, retrasos, incidentes. Útiles para evaluar relaciones comerciales.
Siguiente paso
Last updated today
Built with Documentation.AI