Crear o Actualizar Gasto Conductor

CREAR O ACTUALIZAR GASTO CONDUCTOR

CABECERA

Endpoint para registrar o actualizar gastos de conductor en el sistema TitanicSoft desde Synergy. Permite sincronizar gastos operativos asociados a viajes, con validación de caja válida y creación automática de tipos de gasto.

Endpoint: /api/gasto_conductor

• POST - Para crear un nuevo gasto de conductor (synergy_id NO debe existir)
• PUT - Para actualizar un gasto existente (synergy_id DEBE existir)

---

CUERPO

JSON de Ejemplo (Payload)

{
    "synergy_id": "GC-2025-001234",
    "viaje_id": "VIA-2025-001",
    "fecha": "2025-12-03",
    "tipo_gasto": "Combustible",
    "detalle": "Gasto de combustible en peaje",
    "importe": 150.50,
    "numero_documento": "F001-123456",
    "documento": "factura_combustible.pdf"
}

---

Validaciones Detalladas

Campos Principales

Campo	Tipo	Longitud	Obligatorio	Descripción
synergy_id	String	1-100	Sí	ID único del gasto en Synergy
viaje_id	String	1-20	Sí	ID del viaje en Synergy (debe existir y estar activo)
fecha	Date	10	Sí	Fecha del gasto. Formato: Y-m-d
tipo_gasto	String	1-100	Sí	Nombre del tipo de gasto operativo (se crea automáticamente si no existe)
detalle	String	1-500	Sí	Descripción detallada del gasto
importe	Decimal	-	Sí	Monto del gasto (debe ser mayor a 0)
numero_documento	String	0-100	No	Número de documento asociado (opcional)
documento	String	0-255	No	URL del archivo del documento (opcional)

Notas Importantes:

1. Viaje ID:

   • El campo viaje_id es obligatorio y debe existir en TitanicSoft con id_registro_api correspondiente
   • El viaje debe estar activo (fl_estado = 1)

2. Validación de Caja (Solo POST - Creación):

   • Al crear un nuevo gasto (POST), el viaje debe tener al menos una caja válida con:
     • motivo = 'GASTOS OPERATIVOS'
     • fl_estado = 3 (pendiente de aprobación)
   • Si el viaje no tiene caja válida, se retornará error 400

3. Tipo de Gasto:

   • El campo tipo_gasto viene como texto (nombre), no como ID
   • Si el tipo de gasto no existe en la empresa, se crea automáticamente con:
     • nombre = el nombre recibido
     • fl_estado = 1 (activo)
     • fl_proveedor = 0
   • Si el tipo de gasto existe pero está inactivo, se reactiva automáticamente

4. Documento:

   • El campo documento es opcional y debe contener el nombre del archivo
   • El archivo se guarda en writable/uploads/ con el formato: nombre_original_XXXXXX.extension
   • Se agregan 6 caracteres aleatorios al nombre original para evitar colisiones

---

RESPUESTA EXITOSA

POST (Creación) - Código HTTP 201

{
    "codigo_http": 201,
    "estado": "success",
    "accion": "CREADO",
    "titanic_id": 1234,
    "synergy_id": "GC-2025-001234",
    "viaje_numero": "2025-00012345",
    "mensaje": "Gasto de Conductor CREADO exitosamente"
}

PUT (Actualización) - Código HTTP 200

{
    "codigo_http": 200,
    "estado": "success",
    "accion": "ACTUALIZADO",
    "titanic_id": 1234,
    "synergy_id": "GC-2025-001234",
    "viaje_numero": "2025-00012345",
    "mensaje": "Gasto de Conductor ACTUALIZADO exitosamente"
}

---

POSIBLES ERRORES

1. Conflicto - Gasto Ya Existe (POST) - Código 409

{
    "codigo_http": 409,
    "estado": "conflict",
    "mensaje": "El gasto de conductor ya existe con este synergy_id",
    "detalles": {
        "synergy_id": "GC-2025-001234",
        "titanic_id": 1234,
        "solucion": "Use PUT para actualizar el gasto existente"
    }
}

2. No Encontrado - Gasto No Existe (PUT) - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "El gasto de conductor no existe con este synergy_id",
    "detalles": {
        "synergy_id": "GC-2025-001234",
        "solucion": "Use POST para crear un nuevo gasto de conductor"
    }
}

3. Viaje No Encontrado - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "Viaje no encontrado en TitanicSoft",
    "detalles": {
        "viaje_id": "VIA-2025-001",
        "solucion": "El viaje debe ser enviado primero a Synergy"
    }
}

4. Viaje Inactivo - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "El viaje está inactivo",
    "detalles": {
        "viaje_id": "VIA-2025-001",
        "viaje_numero": "2025-00012345"
    }
}

5. Viaje Sin Caja Válida (Solo POST) - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "El viaje no tiene una caja válida para crear gastos de conductor",
    "detalles": {
        "viaje_id": "VIA-2025-001",
        "viaje_numero": "2025-00012345",
        "solucion": "El viaje debe tener al menos una caja con motivo \"GASTOS OPERATIVOS\""
    }
}

6. Error de Validación - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en la validación de datos",
    "detalles": {
        "synergy_id": "The synergy_id field is required.",
        "viaje_id": "The viaje_id field is required.",
        "fecha": "The fecha field is required.",
        "detalle": "The detalle field is required.",
        "importe": "The importe field is required.",
        "tipo_gasto": "The tipo_gasto field is required."
    }
}

7. Error Interno - Código 500

{
    "codigo_http": 500,
    "estado": "server_error",
    "mensaje": "Error interno del servidor",
    "detalles": "Detalle del error"
}

---

REGLAS DE NEGOCIO

1. Comportamiento POST vs PUT

• POST (Crear):

  • Valida que synergy_id NO exista en la base de datos
  • Valida que el viaje tenga caja válida
  • Crea nuevo registro con id_moneda = 1 (PEN por defecto)
  • Asigna id_empresa e id_usuario del token JWT

• PUT (Actualizar):

  • Valida que synergy_id SÍ exista en la base de datos
  • Actualiza todos los campos enviados
  • Mantiene el archivo anterior si no se envía uno nuevo

2. Validación de Caja

La validación de caja solo aplica al crear (POST), no al actualizar (PUT). Esto permite actualizar gastos incluso si la caja cambió de estado.

3. Creación Automática de Tipo de Gasto

• Si el tipo de gasto no existe, se crea automáticamente
• Si existe pero está inactivo, se reactiva automáticamente
• Esto permite flexibilidad en la integración sin necesidad de configuración previa

4. Manejo de Archivos

• El campo documento es opcional
• Si se proporciona, debe ser el nombre del archivo
• El sistema genera un nombre único agregando 6 caracteres aleatorios
• Los archivos se guardan en writable/uploads/

---

EJEMPLOS DE USO

Ejemplo 1: Crear Gasto de Conductor con Documento

Request:

POST /api/gasto_conductor
Content-Type: application/json
Authorization: Bearer {token}

{
    "synergy_id": "GC-2025-001234",
    "viaje_id": "VIA-2025-001",
    "fecha": "2025-12-03",
    "tipo_gasto": "Peaje",
    "detalle": "Pago de peaje en ruta Lima-Trujillo",
    "importe": 45.00,
    "numero_documento": "PEA-001",
    "documento": "comprobante_peaje.pdf"
}

Response (201 Created):

{
    "codigo_http": 201,
    "estado": "success",
    "accion": "CREADO",
    "titanic_id": 1234,
    "synergy_id": "GC-2025-001234",
    "viaje_numero": "2025-00012345",
    "mensaje": "Gasto de Conductor CREADO exitosamente"
}

Ejemplo 2: Actualizar Gasto de Conductor

Request:

PUT /api/gasto_conductor
Content-Type: application/json
Authorization: Bearer {token}

{
    "synergy_id": "GC-2025-001234",
    "viaje_id": "VIA-2025-001",
    "fecha": "2025-12-03",
    "tipo_gasto": "Combustible",
    "detalle": "Gasto de combustible actualizado",
    "importe": 200.00,
    "numero_documento": "F001-123456"
}

Response (200 OK):

{
    "codigo_http": 200,
    "estado": "success",
    "accion": "ACTUALIZADO",
    "titanic_id": 1234,
    "synergy_id": "GC-2025-001234",
    "viaje_numero": "2025-00012345",
    "mensaje": "Gasto de Conductor ACTUALIZADO exitosamente"
}

---

NOTAS TÉCNICAS

• El endpoint utiliza transacciones de base de datos para garantizar integridad
• Se registra en Centinela para auditoría
• Rate limiting: máximo 10 requests por minuto por usuario
• Autenticación requerida mediante JWT token