Crear o Actualizar Orden de Trabajo

CREAR O ACTUALIZAR ORDEN DE TRABAJO

CABECERA

Endpoint para registrar o actualizar órdenes de trabajo en el sistema TitanicSoft desde Synergy. Permite la sincronización de órdenes con información de cliente, rutas, tarifas y vehículos.

Endpoint: /api/orden_trabajo

• POST - Para crear una nueva orden de trabajo
• PUT - Para actualizar una orden existente (synergy_id DEBE existir y no estar anulada)

---

CUERPO

JSON de Ejemplo (Payload Completo)

{
    "synergy_id": "COT-2025-REM-0001",
    "fecha": "2026-03-16",

    "cliente_synergy_id": "REM-0001",
    "cliente_contacto": "CLIENTE CONTACTO",
    "subcliente": {
        "tipo_documento": "RUC",
        "numero_documento": "20791265117",
        "razon_social": "EMPRESA SERVICIOS TECNOLÓGICOS"
    },
    "origen": {
        "lugar": "HUANCAYO",
        "direccion": "Av. Industrial 123, Tambo",
        "secuencia": "123-456-789",
        "ubigeo": "150126"
    },
    "destino": {
        "lugar": "LIMA",
        "direccion": "Calle Los Pinos 456, Arequipa",
        "secuencia": "987-654-321",
        "ubigeo": "040101"
    },

    "tarifa": {
        "tipo_servicio": "TRANSPORTE",
        "tipo_medida": "FLETE",
        "costo_medida": 3500.00
    },

    "orden_servicio": "OS-CLIENTE-2025-001",
    "producto": "Cemento Portland + Varillas",
    "cantidad_medida": 1,
    "monto_extra": 50.00,
    "operacion_monto_extra": "SUMA",
    "total_orden": 3500.00,
    "peso_ida": 23050,
    "peso_retorno": 0,
    "numero_contenedor": "CONT-123456",
    "referencia_carga_cliente": "Obra Los Portales - Etapa 2",

    "moneda": "USD",
    "tipo_cambio": "3.45",

    "detalle_importes_adicionales": [
        {
            "cantidad": 500,
            "descripcion": "SOBREESTADIA",
            "costo_unitario": 25.50,
            "importe": 12750.00
        },
        {
            "cantidad": 200,
            "descripcion": "SOBREESTADIA",
            "costo_unitario": 35.00,
            "importe": 7000.00
        }
    ]
}

---

Validaciones Detalladas

Campos Principales (Cabecera)

Campo	Tipo	Longitud	Obligatorio	Descripción
synergy_id	String	1-20	Sí	ID único de la orden en Synergy
fecha	Date	10	Sí	Fecha de la orden. Formato: Y-m-d
cliente_synergy_id	String	1-20	Sí	ID del cliente en Synergy (debe existir)
cliente_contacto	String	1-100	No	Nombre del contacto del cliente
orden_servicio	String	máx 100	Sí	Número de orden de servicio
producto	String	máx 300	Sí	Descripción del producto/carga
cantidad_medida	Decimal	-	Sí	Cantidad según tipo de medida (mayor que 0)
total_orden	Decimal	-	Sí	Total de la orden (mayor o igual a 0)
peso_ida	Decimal	-	Sí	Peso de ida en kg (mayor o igual a 0)
peso_retorno	Decimal	-	Sí	Peso de retorno en kg (mayor o igual a 0)
moneda	String	3	Sí	Moneda. Valores: PEN, USD
tipo_cambio	Decimal	-	Condicional	Tipo de cambio (obligatorio si moneda = USD)
monto_extra	Decimal	-	Sí	Monto adicional (mayor o igual a 0)
operacion_monto_extra	String	-	Sí	Operación del monto extra. Valores: SUMA, RESTA
numero_contenedor	String	máx 100	No	Número de contenedor
referencia_carga_cliente	String	máx 500	No	Referencia de carga del cliente

Subcliente (Objeto)

Campo	Tipo	Longitud	Obligatorio	Descripción
tipo_documento	String	2-30	Sí	Tipo de documento. Valores permitidos: DNI, RUC, CARNET DE EXTRANJERIA, PASAPORTE
numero_documento	String	1-15	Sí	Número de documento del subcliente. Se valida cantidad de dígitos según tipo de documento
razon_social	String	1-100	Sí	Razón social o nombre del subcliente

Reglas de validación por tipo de documento:

• DNI → exactamente 8 dígitos numéricos
• RUC → exactamente 11 dígitos numéricos
• CARNET DE EXTRANJERIA / PASAPORTE → entre 1 y 15 caracteres

Origen (Objeto)

Campo	Tipo	Longitud	Descripción
lugar	String	1-150	Lugar o ciudad de origen (referencial)
direccion	String	1-150	Dirección de origen
secuencia	String	1-20	Identificador de la dirección de origen (se almacena en direcciones)
ubigeo	String	6 exactos	Código de ubigeo de origen

Destino (Objeto)

Campo	Tipo	Longitud	Descripción
lugar	String	1-150	Lugar o ciudad de destino (referencial)
direccion	String	1-150	Dirección de destino
secuencia	String	1-20	Identificador de la dirección de destino (se almacena en direcciones)
ubigeo	String	6 exactos	Código de ubigeo de destino

Tarifa (Objeto)

Campo	Tipo	Longitud	Descripción
tipo_servicio	String	máx 30	Tipo de servicio (ej: FLETE, MUDANZA)
tipo_medida	String	máx 30	Tipo de medida (ej: TONELADA, VIAJE, M3, FLETE)
costo_medida	Decimal	-	Costo por unidad de medida (mayor que 0)

Detalle Importes Adicionales (Array Opcional)

Si se envía, cada elemento debe tener:

Campo	Tipo	Descripción
cantidad	Decimal	Cantidad (mayor que 0)
descripcion	String	Descripción del concepto (máx 100)
costo_unitario	Decimal	Costo unitario (mayor o igual a 0)
importe	Decimal	Importe total (mayor o igual a 0)

---

RESPUESTA EXITOSA

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

{
    "codigo_http": 201,
    "estado": "success",
    "accion": "CREADO",
    "titanic_id": 456,
    "numero_orden": "ORD-00001234",
    "synergy_id": "OT-2025-001234",
    "mensaje": "Orden CREADO exitosamente"
}

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

{
    "codigo_http": 200,
    "estado": "success",
    "accion": "ACTUALIZADO",
    "titanic_id": 456,
    "numero_orden": "ORD-00001234",
    "synergy_id": "OT-2025-001234",
    "mensaje": "Orden ACTUALIZADO exitosamente"
}

---

POSIBLES ERRORES

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

{
    "codigo_http": 409,
    "estado": "conflict",
    "mensaje": "La orden ya existe con este synergy_id",
    "detalles": {
        "synergy_id": "OT-2025-001234",
        "numero_orden_existente": "ORD-00001234",
        "titanic_id": 456,
        "solucion": "Use PUT para actualizar la orden existente"
    }
}

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

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

3. No Editable - Orden Anulada (PUT) - Código 400

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

4. Cliente No Encontrado - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "Cliente no encontrado en TitanicSoft"
}

5. Vehículo No Encontrado - Código 404

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "Vehículo no encontrado con la placa proporcionada"
}

6. Error en Tipo / Número de Documento de Subcliente - Código 400

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Número de documento de subcliente inválido",
    "detalles": {
        "numero_documento": "El DNI debe tener exactamente 8 dígitos"
    }
}

---