ABIANAPP_NODE_PRODUCCION/CARGO_API_APP_GUIDE.md

Mercancía del viaje desde la app

Base: la misma URL de API usada por el login y los viajes. Todas las peticiones requieren Authorization: Bearer <token de sesión>. POST y PUT requieren Content-Type: application/json.

Solo el conductor asignado al viaje puede consultar, añadir o editar su mercancía. La mercancía pertenece al viaje completo y la comparten sus tramos. Las operaciones se limitan al identificador de viaje solicitado.

Consultar mercancía y tipos de embalaje

GET /api/trips/:id/cargo

{
  "success": true,
  "data": {
    "mercancias": [
      {
        "id_mercancia": 123,
        "id_tipo_embalaje": 1,
        "cantidad": 2,
        "peso": 400,
        "largo": 120,
        "ancho": 80,
        "alto": 150,
        "remontable": true,
        "tipo_embalaje": "Palet",
        "tipo_embalaje_en": "Pallet"
      }
    ],
    "embalajes": [
      { "id_tipo_embalaje": 1, "tipo_embalaje": "Palet", "tipo_embalaje_en": "Pallet" }
    ],
    "observaciones_mercancia": "Material",
    "ecmr_emitido": true
  }
}

Los nombres de embalaje del ejemplo son ilustrativos: usar los valores e IDs que devuelva el servidor. embalajes contiene las opciones activas. observaciones_mercancia es información del viaje, de solo lectura en estos endpoints. Una lista mercancias: [] permite añadir la primera línea.

Añadir una línea

POST /api/trips/:id/cargo

{
  "id_tipo_embalaje": 1,
  "cantidad": 2,
  "peso": 400,
  "largo": 120,
  "ancho": 80,
  "alto": 150,
  "remontable": true
}

Editar una línea

PUT /api/trips/:id/cargo/:cargoId

Mismo cuerpo que POST. cargoId es el id_mercancia devuelto por GET. Enviar la línea completa; no es una actualización parcial. La línea debe pertenecer al viaje indicado. Las demás líneas se conservan.

Campo	Regla
id_tipo_embalaje	Entero obligatorio; debe existir y estar activo. En edición se permite conservar el embalaje anterior aunque esté inactivo.
cantidad	Entero obligatorio mayor que cero; número de bultos.
peso	Entero obligatorio, de 0 a 9999999999; peso total de la línea en kg, no peso por bulto.
largo, ancho, alto	Enteros en centímetros, entre 0 y 2147483647. Si se omiten se guardan a cero.
remontable	Booleano; también se acepta 0/1. Si se omite se guarda como falso.

Los números deben enviarse como números JSON, no cadenas. El almacenamiento actual no admite decimales en peso o medidas; no redondear silenciosamente. Para emitir un eCMR el peso total del viaje debe ser mayor que cero.

Respuesta de guardado

POST devuelve HTTP 201; PUT devuelve HTTP 200.

{
  "success": true,
  "data": {
    "id_mercancia": 123,
    "id_tipo_embalaje": 1,
    "cantidad": 2,
    "peso": 400,
    "largo": 120,
    "ancho": 80,
    "alto": 150,
    "remontable": true,
    "tipo_embalaje": "Palet",
    "tipo_embalaje_en": "Pallet"
  },
  "ecmr_documentos_actualizados": 1,
  "ecmr_versiones": [
    {
      "id_documento": 45,
      "numero": "ECMR-VIAJE-P1-V3",
      "version": 3,
      "public_url": "https://<erp>/adm/pages/logic/ecmr/documento.php?t=<token>",
      "n_proveedor": 1
    }
  ]
}

Al añadir o editar se genera una nueva versión y un nuevo PDF de cada eCMR vigente del viaje. Se conservan los extras documentales (remolque, ADR, aduanas, autorización especial e Incoterm). Las versiones y firmas antiguas permanecen en el historial. Las nuevas versiones requieren nuevas firmas; los enlaces de firma de versiones sustituidas dejan de ser válidos.

ecmr_documentos_actualizados cuenta todas las revisiones del viaje. ecmr_versiones solo expone los documentos de los tramos asignados al conductor. Si todavía no hay eCMR, la mercancía se guarda y se devuelve 0 y []; la primera emisión continúa haciéndose desde el ERP.

El guardado y las revisiones se realizan en una misma transacción. Si faltan datos para emitir o falla un PDF, no se confirma el cambio de mercancía. Se marca el viaje como editado desde la app. No se envían invitaciones por correo o WhatsApp automáticamente en esta operación.

Flujo recomendado del frontend

1. Abrir «Mercancía» desde el detalle del viaje y cargar GET.
2. Mostrar líneas y botones «Añadir mercancía» / «Editar».
3. Usar los embalajes recibidos y convertir los campos numéricos antes de enviar.
4. Si ecmr_emitido es verdadero, avisar antes de guardar: «Se generará una nueva versión del eCMR y será necesario firmarla de nuevo».
5. Deshabilitar Guardar durante la petición; no reenviar automáticamente POST ante un timeout, para evitar duplicar líneas. Consultar el estado primero.
6. Tras el éxito, refrescar mercancía y GET /api/trips/:id/ecmr para obtener los nuevos PDFs y enlaces de firma. Desechar enlaces antiguos.
7. Mostrar los errores conservando los datos del formulario para corregirlos.

Errores

Formato: { "success": false, "error": "..." }. Una validación de campo puede añadir field, por ejemplo "field": "peso".

• 401: sesión ausente, inválida o sin DNI. Usar el flujo de login existente.
• 403: el conductor no tiene asignado el viaje.
• 404: viaje o línea inexistente, o línea de otro viaje.
• 422: datos inválidos, embalaje no permitido o datos insuficientes para emitir el eCMR. El cambio no se ha guardado.
• 500: fallo al guardar o generar documentos. No presentar éxito ni suponer que no existen mercancías.

No existe operación de eliminación en esta integración.

Operación del backend

Node invoca un proceso PHP local, sin shell y con JSON por stdin, para reutilizar el generador del ERP y mantener una única transacción de mercancía/documentos. El script solo funciona en CLI, vuelve a comprobar la asignación y exige que la base de datos coincida con DB_NAME de Node. No admite acceso HTTP. La ruta del generador está en src/services/tripCargoWriter.js; esta instalación usa /var/www/desarrollogestion/desarrollo/adm/pages/logic/ecmr/mercancia_app_cli.php.

No se necesitan migraciones. El usuario del proceso Node debe poder ejecutar PHP, leer el ERP y escribir los PDFs en su repositorio eCMR.

Validación: 73 pruebas Node y prueba de integración PHP sobre desarrollo con altas, ediciones, PDF real, versiones, permisos, fallo de emisión y rollback. Los datos y PDFs de prueba se revierten/eliminan.