Skip to main content

Overview

Company Management provides tools for creating and managing transport companies, assigning drivers, and monitoring company performance within the Viax platform.

Transport Company Entity

Companies are represented by a comprehensive entity:
admin/domain/entities/empresa_transporte.dart
class EmpresaTransporte {
  final int id;
  final String nombre;
  final String? nit;
  final String? razonSocial;
  final String? email;
  final String? telefono;
  final String? telefonoSecundario;
  final String? direccion;
  final String? municipio;
  final String? departamento;
  final String? representanteNombre;
  final String? representanteTelefono;
  final String? representanteEmail;
  final List<String> tiposVehiculo;
  final String? logoUrl;
  final String? descripcion;
  final EmpresaEstado estado;
  final bool verificada;
  final DateTime? fechaVerificacion;
  final int? verificadoPor;
  final int totalConductores;
  final int totalViajesCompletados;
  final double calificacionPromedio;
  final double comisionAdminPorcentaje;
  final DateTime creadoEn;
  final DateTime? actualizadoEn;
  final int? creadoPor;
  final String? notasAdmin;
}

Company States

Status: activoDisplay: ActivoCompany is operational and accepting drivers

Estado Enum Implementation

admin/domain/entities/empresa_transporte.dart
enum EmpresaEstado {
  activo('activo', 'Activo'),
  inactivo('inactivo', 'Inactivo'),
  suspendido('suspendido', 'Suspendido'),
  pendiente('pendiente', 'Pendiente'),
  eliminado('eliminado', 'Eliminado');

  final String value;
  final String displayName;
  
  const EmpresaEstado(this.value, this.displayName);

  static EmpresaEstado fromString(String? value) {
    return EmpresaEstado.values.firstWhere(
      (e) => e.value == value,
      orElse: () => EmpresaEstado.activo,
    );
  }
}

Company Statistics

Track platform-wide company metrics:
admin/domain/entities/empresa_transporte.dart
class EmpresaStats {
  final int totalEmpresas;
  final int activas;
  final int inactivas;
  final int pendientes;
  final int verificadas;
  final int totalConductores;
  final int totalViajes;

  const EmpresaStats({
    required this.totalEmpresas,
    required this.activas,
    required this.inactivas,
    required this.pendientes,
    required this.verificadas,
    required this.totalConductores,
    required this.totalViajes,
  });
}

Total Companies

All registered transport companies

Active Companies

Currently operational companies

Total Drivers

Drivers across all companies

Verified Companies

Companies with verified credentials

Pending

Companies awaiting verification

Total Trips

Completed trips across all companies

Company Information Fields

Basic Information

{
  "nombre": "Transportes Rápidos S.A.",
  "nit": "900123456-7",
  "razon_social": "Transportes Rápidos Sociedad Anónima",
  "descripcion": "Empresa de transporte especializada en servicio urbano"
}

Contact Information

{
  "email": "info@transportesrapidos.com",
  "telefono": "+57 601 234 5678",
  "telefono_secundario": "+57 312 345 6789",
  "direccion": "Calle 123 #45-67",
  "municipio": "Bogotá",
  "departamento": "Cundinamarca"
}
{
  "representante_nombre": "Carlos Gómez",
  "representante_telefono": "+57 310 123 4567",
  "representante_email": "cgomez@transportesrapidos.com"
}

Service Configuration

{
  "tipos_vehiculo": ["carro", "moto", "carro_carga"],
  "comision_admin_porcentaje": 15.0,
  "logo_url": "https://example.com/logos/empresa-123.png"
}

Performance Metrics

{
  "total_conductores": 45,
  "total_viajes_completados": 1250,
  "calificacion_promedio": 4.7
}

Vehicle Types

Companies can support multiple vehicle categories:

Motorcycle

motoStandard motorcycle transport

Car

carroPassenger vehicle service

Cargo Moto

moto_cargaMotorcycle delivery service

Cargo Van

carro_cargaVan/truck cargo service

Company Repository

Data access layer for company operations:
admin/domain/repositories/empresa_repository.dart
abstract class EmpresaRepository {
  /// Get all companies with optional filters
  Future<Result<List<EmpresaTransporte>>> getEmpresas({
    EmpresaEstado? estado,
    bool? verificada,
    int? page,
    int? limit,
  });

  /// Get company by ID
  Future<Result<EmpresaTransporte>> getEmpresaById(int id);

  /// Create new company
  Future<Result<EmpresaTransporte>> createEmpresa(
    EmpresaTransporte empresa,
  );

  /// Update company information
  Future<Result<EmpresaTransporte>> updateEmpresa(
    int id,
    Map<String, dynamic> updates,
  );

  /// Delete company (soft delete)
  Future<Result<void>> deleteEmpresa(int id);

  /// Get company statistics
  Future<Result<EmpresaStats>> getEmpresaStats();

  /// Verify company
  Future<Result<void>> verifyEmpresa(int id, int adminId);

  /// Get drivers by company
  Future<Result<List<dynamic>>> getDriversByEmpresa(int empresaId);
}

Company Provider

State management for company operations:
admin/presentation/providers/empresa_provider.dart
class EmpresaProvider with ChangeNotifier {
  final EmpresaRepository repository;
  
  List<EmpresaTransporte> _empresas = [];
  EmpresaStats? _stats;
  bool _isLoading = false;
  String? _errorMessage;
  EmpresaEstado? _currentFilter;

  Future<void> loadEmpresas({bool refresh = false}) async {
    _setLoading(true);
    
    final result = await repository.getEmpresas(
      estado: _currentFilter,
      page: 1,
      limit: 50,
    );

    result.fold(
      (failure) => _setError(failure.message),
      (empresas) {
        _empresas = empresas;
        _isLoading = false;
        notifyListeners();
      },
    );
  }

  Future<void> createEmpresa(EmpresaTransporte empresa) async {
    final result = await repository.createEmpresa(empresa);
    
    result.fold(
      (failure) => _setError(failure.message),
      (newEmpresa) {
        _empresas.add(newEmpresa);
        notifyListeners();
      },
    );
  }

  Future<void> updateEmpresa(int id, Map<String, dynamic> updates) async {
    final result = await repository.updateEmpresa(id, updates);
    
    result.fold(
      (failure) => _setError(failure.message),
      (updatedEmpresa) {
        final index = _empresas.indexWhere((e) => e.id == id);
        if (index != -1) {
          _empresas[index] = updatedEmpresa;
          notifyListeners();
        }
      },
    );
  }
}

Commission Configuration

Set platform commission rates per company:
1

Navigate to Company

Select a company from the list
2

Edit Commission

Tap “Edit” and locate the commission field
3

Enter Percentage

Set the commission percentage (e.g., 15.0 for 15%)
4

Save Changes

Confirm to apply the new commission rate
Default commission is 15%. This can be customized per company based on agreements.

Assigning Drivers to Companies

Drivers can be assigned to companies for proper organization:
// In User Management, when editing a conductor:
Future<bool> updateUser({
  required int userId,
  String? tipoUsuario,
  int? empresaId,  // Company ID to assign
  String? empresaNombre,
}) async {
  final result = await manageUserUseCase.updateUser(
    adminId: adminId,
    userId: userId,
    tipoUsuario: tipoUsuario,
    empresaId: empresaId,
  );

  return result.fold(
    (failure) => false,
    (success) {
      if (success && empresaId != null) {
        // Driver is now assigned to company
        notifyListeners();
      }
      return success;
    },
  );
}
Drivers must be assigned to a company to ensure proper commission tracking and payment distribution.

Company Verification

Verify company credentials before activation:
Future<Result<void>> verifyEmpresa(int empresaId, int adminId) async {
  // Verify:
  // - NIT is valid
  // - Legal representative documents
  // - Business registration
  // - Insurance policies
  
  final result = await repository.verifyEmpresa(empresaId, adminId);
  
  return result.fold(
    (failure) => Error(failure),
    (success) {
      // Update local state
      final index = _empresas.indexWhere((e) => e.id == empresaId);
      if (index != -1) {
        _empresas[index] = _empresas[index].copyWith(
          verificada: true,
          fechaVerificacion: DateTime.now(),
          verificadoPor: adminId,
        );
        notifyListeners();
      }
      return Success(success);
    },
  );
}

Platform Earnings by Company

Track commissions owed by each company:
admin/presentation/screens/platform_earnings_screen.dart
class PlatformEarningsScreen extends StatefulWidget {
  final int adminId;

  const PlatformEarningsScreen({
    super.key,
    required this.adminId,
  });
}

// Displays:
// - Total trips per company
// - Total earnings per company
// - Platform commission earned
// - Outstanding payments

Earnings Calculation

// For each company trip:
final tripTotal = 50000; // COP
final commissionRate = empresa.comisionAdminPorcentaje; // 15%
final platformEarnings = tripTotal * (commissionRate / 100); // 7500 COP
final driverEarnings = tripTotal - platformEarnings; // 42500 COP

Company CopyWith Method

Immutable updates to company entities:
admin/domain/entities/empresa_transporte.dart
EmpresaTransporte copyWith({
  int? id,
  String? nombre,
  String? nit,
  String? razonSocial,
  String? email,
  String? telefono,
  String? telefonoSecundario,
  String? direccion,
  String? municipio,
  String? departamento,
  String? representanteNombre,
  String? representanteTelefono,
  String? representanteEmail,
  List<String>? tiposVehiculo,
  String? logoUrl,
  String? descripcion,
  EmpresaEstado? estado,
  bool? verificada,
  DateTime? fechaVerificacion,
  int? verificadoPor,
  int? totalConductores,
  int? totalViajesCompletados,
  double? calificacionPromedio,
  double? comisionAdminPorcentaje,
  DateTime? creadoEn,
  DateTime? actualizadoEn,
  int? creadoPor,
  String? notasAdmin,
}) {
  return EmpresaTransporte(
    id: id ?? this.id,
    nombre: nombre ?? this.nombre,
    nit: nit ?? this.nit,
    // ... all fields
  );
}

Company Filtering

Filter companies by various criteria:
Filter by activo, inactivo, suspendido, pendiente, or eliminado

Best Practices

Always verify company credentials (NIT, legal representative, insurance) before approving.
Set commission rates based on service type, volume, and agreements. Standard is 15%.
Regularly review company metrics like completion rate, driver count, and customer ratings.
Use the Platform Earnings screen to monitor commission payments from companies.
Use the notes field to document important changes or agreements with companies.

Driver Management

Assign drivers to companies

User Management

Manage company user accounts

Pricing Configuration

Set pricing by vehicle type

Build docs developers (and LLMs) love