H&S LOGISTIC

Especificaciones completas · API de Facturación y Envío de Guías a SUNAT + Detracciones (4%) + Conciliación Bancaria con BCP

Laravel 11 API REST Facturación Envío Guías SUNAT Detracción 4% Conciliación BCP Alertas Inteligentes
Desarrollo con Laravel 11: Backend robusto con API propia para facturación electrónica, envío de guías a SUNAT, gestión de detracciones (4%) y conciliación bancaria dinámica con BCP.

Clientes y Panel Web App

  • Registro completo: Razón social, RUC/DNI, correo electrónico (obligatorio), teléfono celular (obligatorio para WhatsApp).
  • Múltiples puntos de entrega con dirección, coordenadas GPS, horario, responsable.
  • Panel web app para el cliente con acceso mediante email y contraseña.
  • El cliente visualiza: listado de órdenes con código único de 5 dígitos, estado actual, fecha aproximada de llegada.
  • El cliente NO visualiza la ubicación en tiempo real de la unidad por políticas de seguridad.
  • El cliente puede descargar sus facturas, guías y comprobantes de detracción desde el panel.
Acceso exclusivo por email + contraseña. Sin geolocalización de unidades.

Conductores

  • Registro: nombres, apellidos, DNI, licencia de conducir (categoría, fechas).
  • Número telefónico principal + alternativo, dirección.
  • Control de disponibilidad: Disponible, En servicio, Descanso, Vacaciones, Licencia médica.
  • Alertas automáticas ante vencimiento de licencia.
  • Historial de servicios y calificación.

Unidades y Mantenimiento

  • Registro vehicular: placa, marca, modelo, año, tipo de unidad.
  • Figuración/icono representativo para mapas.
  • Capacidad de carga (kg y m³). Tipo de carga permitida.
  • SOAT, revisión técnica: fechas, alertas.
  • Mantenimiento Preventivo: por km o tiempo.
  • Mantenimiento Correctivo: registro de averías, costos.
  • Alertas y bloqueo de unidad si no se realiza mantenimiento.

Combustible y Viáticos

  • Registro desde panel conductor: galones, monto, km actual.
  • Registro de viáticos: monto, concepto.
  • Registro de peajes: monto, plaza.
  • Control de rendimiento (km/galón).
  • Sin obligación de fotografías.

Remitentes y Almacenes

  • Registro de empresas remitentes: razón social, RUC.
  • Múltiples almacenes con dirección, GPS, responsable.
  • Puntos de recojo predefinidos.

Comercial (Cotizaciones)

  • Creación con múltiples puntos de recojo y entrega.
  • Selección de unidad, fecha tentativa, tipo de carga (fiscalizada / no fiscalizada).
  • Al aprobar → se genera Orden de Servicio con código único alfanumérico de 5 dígitos.
  • Al crear la cotización, envío automático de PDF por WhatsApp al cliente.
Código único: "7H2K9", "M3N8P" - no repetible.

Operaciones (Guías)

  • Subir guía remitente (PDF) – obligatorio.
  • Generación automática de Guía Transportista en PDF según tipo: fiscalizada (con campos SUNAT) o no fiscalizada.
  • Asignación de conductor y unidad.
  • Checklist obligatorio antes de iniciar servicio.
  • La guía transportista puede ser enviada a SUNAT vía API.
Las guías de carga fiscalizada se envían automáticamente a SUNAT.

Panel Conductor (Web App)

  • Login, dashboard de órdenes asignadas.
  • Registro de gastos: combustible, viáticos, peajes.
  • Botones: "Llegué a recojo" (geolocalización + firma digital).
  • "Llegué a entrega" (geolocalización + firma digital cliente).
  • Reporte de incidencias. Finalizar servicio.

Seguimiento GPS (Solo operaciones)

  • Captura automática cada 2 minutos.
  • Dashboard con mapa para operaciones/gerencia.
  • El cliente NO tiene acceso a la ubicación.
Ubicación solo para roles autorizados.

Contabilidad y Finanzas

  • Dashboard financiero: Cuentas por cobrar, por pagar, flujo de caja, rentabilidad por servicio.
  • Registro de pagos recibidos y conciliación bancaria.
  • Gestión de gastos operativos (combustible, mantenimiento, peajes, viáticos).
  • Reportes financieros: Estado de resultados, balance, libro de ventas/compras.
  • Integración con módulo de detracciones para registrar pagos al fisco.
  • Exportación a Excel/PDF de todos los reportes contables.
Control completo de ingresos y egresos asociados a cada orden de servicio.

Gestión de Detracciones 4% fijo

  • Porcentaje único: 4% sobre el monto total de la factura (base imponible + IGV + otros tributos).
  • Lógica de pago:
    • Cliente paga detracción: El monto final a pagar por el cliente = total factura - (4% del total). La empresa deposita el 4% al fisco.
    • Empresa asume detracción: Cliente paga el total de la factura completa. La empresa asume el costo del 4% y deposita al fisco.
  • Registro de cada detracción: N° factura, monto base, porcentaje aplicado (4%), monto detracción, responsable pago (cliente/empresa), estado (pendiente/pagado), fecha límite de depósito a SUNAT.
  • Generación de constancia de detracción y reporte diario de depósitos pendientes.
Alerta antes del vencimiento del depósito de detracción (máximo 5 días después del pago).

Facturación a Crédito

  • Condiciones de pago configurables: Contado, Crédito 15 días, Crédito 30 días, Crédito 45 días, etc.
  • Plazos personalizados por cliente (aprobación previa).
  • Control de vencimiento de facturas: alertas automáticas de cobranza.
  • Módulo de cobranzas: Registro de seguimiento, promesas de pago, reporte de morosidad.
  • Intereses moratorios automáticos según días de atraso.
  • Envío de recordatorios de pago por WhatsApp y correo electrónico.
Cada factura registra condición de pago y fecha de vencimiento.

Conciliación Bancaria BCP

  • Carga del reporte BCP: El sistema permite importar el archivo (Excel/CSV/TXT) que el banco BCP emite con los movimientos de la cuenta.
  • Matching automático: El sistema cruza los movimientos del banco con los registros internos de facturas, pagos de clientes, depósitos de detracciones, etc.
  • Detección de diferencias: Identifica automáticamente montos no conciliados, cargos no registrados o pagos duplicados.
  • Propuesta de conciliación: El sistema sugiere la asignación de movimientos bancarios a facturas o documentos internos.
  • Dashboard de conciliación: Visualización del estado (conciliado / pendiente / diferencia) con fecha de corte.
  • Generación del reporte de conciliación bancaria automático para auditoría.
Dinámico e inteligente: Basta con subir el reporte del BCP para que el sistema actualice automáticamente la conciliación bancaria.

Alertas Inteligentes (Módulo Transversal)

  • Detracciones 4%: Alerta 2 días antes del vencimiento del depósito a SUNAT.
  • Créditos: Alerta 5 días antes del vencimiento de factura.
  • Conciliación: Alerta cuando hay diferencias no resueltas en la conciliación bancaria por más de 3 días.
  • Finanzas: Alerta cuando un cliente supera su límite de crédito.
  • Operaciones: Mantenimiento próximo, vencimiento SOAT/Revisión Técnica.
  • Canales: WhatsApp, correo electrónico, notificaciones en sistema (campana).
Todas las alertas son registradas en un log de auditoría.

Flujo completo del negocio (End-to-End)

1️⃣ Registros base

Clientes, remitentes, conductores, unidades + condiciones de crédito.

2️⃣ Cotización

Vendedor crea cotización → Envío PDF WhatsApp.

3️⃣ Aprobación

Convierte a Orden con código único 5 dígitos y configura detracción (quién paga el 4%).

4️⃣ Operaciones

Sube guía remitente, genera Guía Transportista, asigna conductor.

5️⃣ API SUNAT

Envío de guía fiscalizada y factura electrónica.

6️⃣ Facturación y Detracción

Emite factura (contado/crédito). Calcula detracción del 4%.

7️⃣ Cobranza y Depósito

Registra pago del cliente. Alerta de depósito del 4% a SUNAT.

8️⃣ Conciliación Bancaria

Carga reporte BCP → Matching automático → Diferencias reportadas.

9️⃣ Finanzas y Reportes

Actualiza cuentas contables, libros, rentabilidad.

Lógica de Detracción (4%) y Pago

  • Caso 1: Paga el cliente
    Ej: Factura S/ 10,000. Detracción 4% = S/ 400.
    Cliente paga S/ 9,600 (factura - detracción).
    Empresa deposita S/ 400 a SUNAT.
  • Caso 2: Asume la empresa
    Factura S/ 10,000. Detracción 4% = S/ 400.
    Cliente paga S/ 10,000 completo.
    Empresa asume costo extra de S/ 400 para depósito a SUNAT.
  • Registro contable: se refleja en el libro de compras/ventas y en la cuenta "Detracciones por pagar (4%)".
  • Base de cálculo: Monto total de la factura = base imponible + IGV + otros cargos.
Porcentaje fijo: 4% sobre el monto total de la factura.

Listado de Detracciones

  • Tabla interactiva con filtros por: RUC cliente, rango de fechas, estado, responsable del pago.
  • Columnas: N° Factura | Cliente | Monto Factura | % Detracción (4%) | Monto Detracción | Responsable Pago | Estado Depósito SUNAT | Fecha Límite
  • Exportación a Excel y PDF.

Módulo Financiero Integrado

  • Cuentas por Cobrar: Saldo pendiente por cliente, antigüedad de facturas.
  • Cuentas por Pagar (Detracciones): Montos que la empresa debe depositar a SUNAT (4%).
  • Flujo de caja proyectado: Ingresos vs egresos por detracciones y gastos operativos.
  • Rentabilidad por orden: Ingreso - (gastos + detracción asumida).

Carga de Reporte BCP

  • Formatos soportados: Excel (.xlsx, .xls), CSV, TXT (formato estándar BCP).
  • Mapeo automático: El sistema reconoce las columnas del reporte BCP (fecha, descripción, monto débito, monto crédito, saldo, etc.).
  • Carga masiva: Permite cargar reportes de múltiples cuentas bancarias (BCP Empresarial).
  • Historial de cargas: Registro de todos los reportes subidos con fecha y usuario.
📁 Formato de archivo aceptado: Reporte de movimientos BCP (descargado desde BCP Empresas / Banca Web)

Matching Automático

  • El sistema cruza automáticamente cada movimiento bancario con:
    • Facturas emitidas (número de comprobante, monto, fecha).
    • Pagos registrados de clientes (número de operación, monto).
    • Depósitos de detracciones a SUNAT.
    • Gastos operativos (peajes, combustible, mantenimiento).
  • Criterios de matching: Monto + fecha aproximada ± 3 días + referencia textual.
  • Sugerencia manual en caso de ambigüedad.

Dashboard de Conciliación

  • Visualización de movimientos bancarios vs registros internos.
  • Estados: ✅ Conciliado | ⚠️ Pendiente | ❌ Diferencia.
  • Resumen por fecha de corte: saldo contable vs saldo bancario.
  • Reporte de diferencias con opción de ajuste manual o creación de asiento contable.
  • Generación de "Acta de Conciliación Bancaria" en PDF.
La conciliación se actualiza dinámicamente cada vez que se carga un nuevo reporte del BCP.

Alertas de Conciliación

  • Movimientos no conciliados: Alerta si hay movimientos bancarios sin match después de 5 días.
  • Diferencias significativas: Alerta cuando la diferencia entre saldo contable y bancario supera un umbral configurable.
  • Facturas pagadas no registradas: Detecta abonos bancarios que no corresponden a ninguna factura emitida.
  • Notificaciones al área de contabilidad y finanzas por WhatsApp/email.

Eventos con notificación WhatsApp al Cliente

  • 📄 Cotización creada: Envío PDF + código.
  • ✅ Cotización aprobada: "Orden #5H2K9 generada".
  • 👨‍✈️ Conductor asignado: Datos del conductor y unidad.
  • 📦 Recojo completado.
  • 🚚 Actualización de fecha estimada.
  • 🎯 Entregado.
  • 📑 Factura emitida: disponible en panel + recordatorio de pago si es crédito.
  • ⏰ Recordatorio de vencimiento de factura (5 días antes y al día siguiente).
Implementación con Laravel Notification Channels + Queues.

Panel del Cliente

  • Acceso por email + contraseña.
  • Visualiza: código de orden, estado, fecha aproximada de llegada, facturas con saldo pendiente.
  • Descarga de facturas, guías y comprobantes de detracción.
  • No ve ubicación de unidades.

API de Facturación Electrónica

  • Endpoint: POST /api/v1/facturar
  • Campos adicionales: condicion_pago (contado/credito), dias_credito, detraccion_responsable (cliente/empresa), porcentaje_detraccion = 4%.
  • Genera XML UBL 2.1, envía a SUNAT, recibe CDR.
  • Respuesta JSON con número de comprobante, link PDF/XML, monto detracción (4%) y responsable.

API de Envío de Guías a SUNAT

  • Endpoint: POST /api/v1/enviar-guia
  • Envío automático de Guías fiscalizadas a SUNAT.
  • Webhook de respuesta y estado consultable.

Webhooks y Callbacks

  • Recepción de CDR y actualización de estado de factura/guía.
  • Logs completos para auditoría.

Backend - Laravel 11

  • Laravel 11 + PHP 8.2+.
  • API RESTful con Laravel Sanctum.
  • Eloquent ORM, Migrations, Seeders.
  • Laravel Queues + Redis/Database.
  • Spatie Permissions para roles.

Frontend y PWA

  • Next.js + TypeScript + Tailwind CSS.
  • PWA para conductores (offline).
  • Diseño responsive.

Seguridad y Códigos

  • Código único de 5 dígitos alfanuméricos por orden.
  • JWT + roles, HTTPS.

Base de Datos

  • MySQL 8.0+.
  • Tablas adicionales: detracciones (4%), conciliacion_bancaria, movimientos_bcp, cuentas_por_cobrar, condiciones_pago, alertas_config.
  • Backups automáticos.
Laravel 11 · API Facturación + Detracción 4% + Conciliación Bancaria BCP + Crédito
✅ Detracciones 4% con lógica de pago cliente/empresa ✅ Conciliación bancaria dinámica cargando reporte BCP ✅ Facturación a crédito con alertas ✅ Alertas inteligentes