API Portas — Móvil

1. Qué es esta API

El sistema viejo de Portas tiene una aplicación móvil (Symfony 1.4, app smatphone) con 18 módulos y tres perfiles de usuario distintos. Esta API expone esa misma funcionalidad como endpoints REST para que la reimplemente importas.com.ar.

Convive con la API Web (escritorio) en el mismo servicio y con la misma API key. Hay solapamiento deliberado: movimientos y comprobantes existen en las dos, porque en el sistema viejo también son pantallas distintas con filtros distintos.

2. Autenticación: API key + id_usuario

Son dos cosas separadas y hacen falta las dos:

id_usuario es el id_usuario_web de freewaynet.web_clientes_usuarios — el mismo padón de usuarios que usa el móvil viejo. Portas no valida la clave: el login lo hace importas contra sus propias tablas, y en cada llamada nos dice quién es.

Los endpoints exigen scope movil:read o movil:write según el caso. Por ahora también se aceptan web:read / web:write, para que la key que importas ya tiene en producción sirva sin cambios.

Errores propios de id_usuario

3. Personas y qué ve cada una

Del id_usuario sale la persona, con las mismas reglas y en el mismo orden que el executeIngresar del Symfony viejo:

El parámetro opcional id_cliente (uno o varios separados por coma: ?id_cliente=84,1167) acota ese alcance, nunca lo amplía. Le sirve sobre todo al empleado, que ve todo y quiere mirar un cliente.

4. GET /v1/movil/usuario

Quién es el usuario y qué menú mostrarle. Es el equivalente de "abrir la sesión" del móvil viejo: se llama una vez al entrar.

{
  "ok": true,
  "usuario": {
    "id_usuario_web": 123,
    "id_cliente": 1167,
    "persona": "cliente",
    "usuario": "operaciones@ferrero.com",
    "nombre": "Juan Perez",
    "cargo": "Comercio Exterior",
    "razon_social": "FERRERO ARGENTINA S.A.",
    "web_carpeta": "ferrero",
    "id_proveedor_cliente": 0,
    "id_transportista": 0,
    "interno": null,
    "notificaciones": { "impo": true, "expo": false }
  },
  "credenciales": ["Movil", "Cliente"],
  "notificaciones": {
    "impo": true, "expo": false, "oficializacion": true,
    "finalizacion_carga": true, "permiso_cumplido": false,
    "arribo_mercaderia": true, "facturacion": true, "reclamo": false,
    "vencimiento_simi_djai": false, "vencimiento_temporal": false,
    "vencimiento_forzoso": false, "digitalizacion": true,
    "reintegro_aprobado": false, "coordinacion_transporte": false
  }
}

credenciales viene con los nombres que usan los security.yml del sistema viejo, para que el menú se pueda armar con el mismo criterio.

5. PATCH /v1/movil/usuario

La pantalla "Perfil": casillas de notificación y cambio de clave. Las dos partes son opcionales — se manda lo que se quiere cambiar.

{
  "id_usuario": 123,
  "notificaciones": { "facturacion": false, "arribo_mercaderia": true },
  "clave_actual": "laDeAhora",
  "clave_nueva": "unaNuevaDe8+"
}

Es un PATCH de verdad: las casillas que no se mandan quedan como estaban. (El formulario viejo apagaba todo lo que no viniera, que es correcto para un form completo y peligroso para una API.)

6. Notificaciones por evento

La grilla de eventos de la pantalla "Perfil": una columna para importación y otra para exportación.

{
  "ok": true,
  "eventos": {
    "importacion": [
      { "id_evento": 12, "nombre": "Arribo de mercadería", "sector": "Operaciones",
        "categoria": "", "color": "#3498db", "suscripto": true }
    ],
    "exportacion": [ ... ]
  }
}

{
  "id_usuario": 123,
  "eventos": [
    { "id_evento": 12, "operacion": 1, "suscripto": false },
    { "id_evento": 15, "operacion": 2, "suscripto": true }
  ]
}

operacion: 1 = importación, 2 = exportación. Es idempotente: se puede repetir el mismo PUT sin efectos raros.

7. Dispositivos (push)

Registro del token de notificaciones push. Reemplaza /registrar_movil.

{ "id_usuario": 123, "token": "fcm-token-del-dispositivo", "so": "android" }

so: android, ios o web. Se escriben las dos cosas que escribe el viejo: el token vigente en web_clientes_usuarios (que es el que lee FreeWayNet para mandar el aviso) y el historial en web_clientes_usuarios_token.

Lista los dispositivos registrados. El token se devuelve parcial (abc123…xyz789): alcanza para reconocerlo y no sirve para mandar push.

{ "id_usuario": 123, "token": "fcm-token-del-dispositivo" }

Da de baja el dispositivo. Si era el vigente, también lo apaga en el usuario — si no, FreeWayNet le seguiría mandando avisos a un teléfono desvinculado.

8. GET /v1/movil/movimientos

Módulo ultimos_mov: la cronología de hitos y eventos de las operaciones que el usuario puede ver.

{
  "ok": true,
  "items": [
    {
      "id_carpeta": "2026.04.94961",
      "legajo": 94961,
      "referencia": "PO-88213",
      "factura": "A-0001-00012345",
      "fecha": "2026-08-20 14:32:00",
      "id_hito": 4,
      "hito": "Oficialización",
      "evento": "Despacho oficializado",
      "observacion": ""
    }
  ],
  "paginado": { "pagina": 1, "limite": 25, "total": 412, "paginas": 17 }
}

Acepta todos los filtros comunes. limit va de 1 a 200 (25 por defecto).

9. GET /v1/movil/comprobantes-adeudados

Módulo comp_adeudados: lo que el cliente todavía debe.

estado: todos (default), vencidos, a_vencer. Más todos los filtros comunes.

{
  "ok": true,
  "items": [
    {
      "id_comprobante": "A-0001-00012345",
      "legajo": 94961,
      "id_carpeta": "2026.04.94961",
      "operacion": "22001EC01030375C",
      "referencia": "PO-88213",
      "mercaderia": "Chocolate",
      "factura_proveedor": "INV-2210",
      "fecha": "2026-07-15",
      "vencimiento": "2026-08-14",
      "total": 154320.55,
      "total_comprobante": 480000.00,
      "vencido": true,
      "dias_vencido": 10,
      "cliente": ""
    }
  ],
  "estado": "vencidos",
  "resumen": {
    "comprobantes": 12, "monto": 1854320.55,
    "vencidos": 5, "monto_vencido": 640210.00, "mas_antiguo": "2026-05-02"
  },
  "paginado": { "pagina": 1, "limite": 25, "total": 12, "paginas": 1 }
}

cliente viene con la razón social solo cuando la llamada es de un empleado (que ve varios clientes); para un cliente siempre es la propia y va vacío.

10. Circulares y newsletters

Los dos tablones de novedades. Misma forma para los dos.

El listado no trae el cuerpo (son textos largos con HTML): solo título, fecha, link y palabras clave. El detalle agrega texto y texto_html. q busca en título y palabras clave.

11. POST /v1/movil/legajos/{id}/fotos

Reemplaza las tres pantallas de fotos del móvil viejo (Foto Precinto, Inspección Mercadería y Subir Remito del transportista). Una sola llamada hace lo que antes eran dos pasos (subir y "Notificar"): crea el evento en la operación, guarda las fotos y deja la notificación al cliente pendiente.

curl -X POST "https://api.portascloud.ar/v1/movil/legajos/2026.04.94979/fotos?id_usuario=123" \
     -H "Authorization: Bearer $API_KEY" \
     -F tipo=precinto \
     -F "fotos[]=@IMG_20260828_110608.jpg" \
     -F "fotos[]=@IMG_20260828_110612.jpg"

Respuesta 201:

{
  "ok": true,
  "id_carpeta": "2026.04.94979",
  "tipo": "precinto",
  "id_evento": 176,
  "id_registro": 812345,
  "evento_nuevo": true,
  "observacion": "FOTO PRECINTO (94979) - 7381ST",
  "fotos": [
    { "id_archivo": 601234, "nombre_archivo": "IMG_20260828_110608.jpg",
      "tamanio_bytes": 190935, "download_url": "https://api.portascloud.ar/v1/d/<token>",
      "ya_existia": false }
  ],
  "notificacion": "pendiente"
}

Qué pasa después. Las fotos quedan en el storage de Portas (descargables ya por download_url), el Sincronizador las lleva a la red de Portas a la carpeta del evento (FreeWayNet las muestra con el clip) y el circuito de notificaciones le avisa al cliente con las fotos, respetando sus preferencias por evento — igual que cuando se cargaban desde el móvil viejo.

12. Filtros comunes de operación

Los aceptan /movil/movimientos y /movil/comprobantes-adeudados (y los listados de las fases siguientes). Son los mismos catorce filtros que el Symfony viejo repetía en cada módulo.

Las fechas se aceptan como AAAA-MM-DD o DD/MM/AAAA. Un filtro mal escrito se ignora en silencio, igual que en el sistema viejo.

13. Errores

Formato único, igual que el resto de la API:

{ "ok": false, "error": "usuario_inexistente", "message": "No existe el usuario web 999" }

14. Fases siguientes

Todas se montan sobre la misma base: id_usuario, las mismas personas y el mismo juego de filtros.