Crear o Actualizar Movimiento de Caja

CREAR O ACTUALIZAR CAJA (MOVIMIENTO DE TESORERÍA)

CABECERA

Endpoint para registrar o actualizar movimientos de caja (desembolsos, anticipos, liquidaciones) en el sistema TitanicSoft desde Synergy. Permite sincronizar operaciones de tesorería con información de personas, viajes y cuentas bancarias.

Endpoint: /api/caja

• POST - Para crear un nuevo movimiento de caja
• PUT - Para actualizar un movimiento existente (synergy_id DEBE existir)

---

CUERPO

JSON de Ejemplo (Payload)

{
    "synergy_id": "CAJ-2025-001234",
    "fecha": "2025-12-03",
    "tipo_persona": "CONDUCTOR",
    "persona_id": "PERS-001",
    "nombre_persona": "Juan Pérez",
    "viaje_id": "VIA-2025-001",
    "motivo": "GASTOS OPERATIVOS",
    "modalidad": "TRANSFERENCIA",
    "moneda": "PEN",
    "importe": 500.00,
    "tipo_cambio": 3.75,
    "descripcion": "Pago de gastos operativos del viaje",
    "observacion": "Anticipo para combustible",
    "numero_cuenta_empresa": "19112345678",
    "numero_cuenta_persona": "19123456789",
    "cuenta_bancaria_persona": "BCP - Ahorros - 19123456789",
    "voucher": "VOUCHER-001234",
    "fl_no_liquidacion_viaje": 0
}

---

Validaciones Detalladas

Campos Principales

Campo	Tipo	Longitud	Obligatorio	Descripción
synergy_id	String	1-20	Sí	ID único del movimiento en Synergy
fecha	Date	10	Sí	Fecha de la operación. Formato: Y-m-d
tipo_persona	String	-	Sí	Tipo de persona. Valores: PROVEEDOR, CONDUCTOR, ADMINISTRATIVO, OTRO
persona_id	String	1-20	Condicional	ID de la persona en Synergy. Obligatorio si tipo_persona ≠ OTRO
nombre_persona	String	1-100	Condicional	Nombre de la persona. Obligatorio si tipo_persona = OTRO
viaje_id	String	1-20	Condicional	ID del viaje (obligatorio para ciertos motivos)
motivo	String	1-50	Sí	Motivo del movimiento. Valores: GASTOS OPERATIVOS, ADELANTO VIAJE TERCERIZADO, FLETE VIAJE TERCERIZADO, PAGO SUELDO, ADELANTO SERVICIO ESCOLTA, SERVICIO ESCOLTA
modalidad	String	-	Sí	Modalidad de pago. Valores: EFECTIVO, TRANSFERENCIA, CHEQUE, DEPOSITO, TARJETA
moneda	String	3	Sí	Código de moneda. Valores: PEN, USD
importe	Decimal	-	Sí	Monto del movimiento (debe ser mayor a 0)
descripcion	String	1-500	Sí	Descripción detallada del movimiento
observacion	String	0-1000	No	Observaciones adicionales (opcional)
tipo_cambio	Decimal	-	No	Tipo de cambio (debe ser mayor a 0 si se proporciona)
voucher	String	0-100	No	Número de voucher (opcional)
fl_no_liquidacion_viaje	Integer	-	No	Flag de no liquidación del viaje. Valores: 0, 1

Campos de Cuentas Bancarias

Campo	Tipo	Longitud	Obligatorio	Descripción
numero_cuenta_empresa	String	1-50	No	Número de cuenta bancaria de la empresa (opcional)
numero_cuenta_persona	String	Variable	Condicional	Número de cuenta bancaria de la persona. Obligatorio si modalidad ≠ EFECTIVO y tipo_persona ≠ OTRO
cuenta_bancaria_persona	String	Variable	Condicional	Cuenta bancaria de la persona (texto libre). Obligatorio si modalidad ≠ EFECTIVO y tipo_persona = OTRO

Notas Importantes:

1. Tipo de Persona:

   • Si tipo_persona es CONDUCTOR, ADMINISTRATIVO o PROVEEDOR: el campo persona_id es obligatorio y debe existir en TitanicSoft
   • Si tipo_persona es OTRO: el campo nombre_persona es obligatorio

2. Viaje ID:

   • El campo viaje_id es obligatorio cuando el motivo es uno de los siguientes:
     • ADELANTO VIAJE TERCERIZADO
     • FLETE VIAJE TERCERIZADO
     • ADELANTO SERVICIO ESCOLTA
     • SERVICIO ESCOLTA
     • GASTOS OPERATIVOS

3. Regla de Negocio - GASTOS OPERATIVOS:

   • Si el motivo es “GASTOS OPERATIVOS” y se proporciona viaje_id, el viaje NO debe tener liquidación
   • Si el viaje ya está liquidado, se retornará un error 400

4. Cuentas Bancarias:

   • Si modalidad es diferente de EFECTIVO:
     • Y tipo_persona ≠ OTRO: debe proporcionarse numero_cuenta_persona
     • Y tipo_persona = OTRO: debe proporcionarse cuenta_bancaria_persona (texto libre)

---

RESPUESTA EXITOSA

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

{
    "codigo_http": 201,
    "estado": "success",
    "accion": "CREADO",
    "titanic_id": 789,
    "numero_caja": "CAJ-00001234",
    "synergy_id": "CAJ-2025-001234",
    "mensaje": "Caja CREADO exitosamente"
}

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

{
    "codigo_http": 200,
    "estado": "success",
    "accion": "ACTUALIZADO",
    "titanic_id": 789,
    "numero_caja": "CAJ-00001234",
    "synergy_id": "CAJ-2025-001234",
    "mensaje": "Caja ACTUALIZADO exitosamente"
}

---

POSIBLES ERRORES

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

{
    "codigo_http": 409,
    "estado": "conflict",
    "mensaje": "La caja ya existe con este synergy_id",
    "detalles": {
        "synergy_id": "CAJ-2025-001234",
        "numero_caja_existente": "CAJ-00001234",
        "titanic_id": 789,
        "solucion": "Use PUT para actualizar la caja existente"
    }
}

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

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "La caja no existe con este synergy_id",
    "detalles": {
        "synergy_id": "CAJ-2025-001234",
        "solucion": "Use POST para crear una nueva caja"
    }
}

3. Persona No Encontrada - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "Persona (Conductor/Administrativo/Proveedor) no encontrada en TitanicSoft"
}

4. Viaje Ya Liquidado - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "No se puede desembolsar por motivo de GASTOS OPERATIVOS, porque el viaje ya cuenta con una liquidación",
    "detalles": {
        "viaje_id": "VIA-2025-001",
        "solucion": "Debe anular la liquidación del viaje primero"
    }
}

5. Cuenta Bancaria No Encontrada - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "Cuenta bancaria de empresa no encontrada"
}

6. Modalidad Requiere Cuenta Bancaria Persona - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Debe proporcionar numero_cuenta_persona cuando modalidad no es EFECTIVO y tipo_persona no es OTRO"
}

7. Modalidad Requiere Cuenta Bancaria (OTRO) - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Debe proporcionar cuenta_bancaria_persona cuando modalidad no es EFECTIVO y tipo_persona es OTRO"
}

8. Viaje ID Obligatorio para Motivo - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "El campo viaje_id es obligatorio cuando motivo es GASTOS OPERATIVOS",
    "detalles": {
        "motivo": "GASTOS OPERATIVOS",
        "solucion": "Debe proporcionar viaje_id cuando el motivo es GASTOS OPERATIVOS"
    }
}

9. Caja Anulada No Puede Editarse (PUT) - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "La caja no puede ser editada porque está anulada",
    "detalles": {
        "estado_actual": "ANULADO",
        "numero_caja": "CAJ-00001234"
    }
}