requestPhoto: cómo pedir una foto remota desde Traccar

Una cámara que solo dispara con un evento sirve para reconstruir un incidente. Una cámara a la que puedes pedirle una foto cuando tú quieras sirve además para verificar carga, comprobar que el conductor está donde dice, o resolver una disputa por teléfono en treinta segundos.

Traccar tiene un tipo de comando dedicado exactamente para eso: requestPhoto.

Ojo: no todos los protocolos lo implementan. La lista completa de qué soporta cada uno está en cámaras compatibles con Traccar.

Qué es requestPhoto

Es uno de los tipos de comando estándar del modelo de comandos de Traccar (TYPE_REQUEST_PHOTO, cuyo identificador literal es requestPhoto). Los tipos de comando son genéricos: la interfaz te muestra "solicitar foto" y cada protocolo se encarga de traducirlo a la trama concreta que entiende su hardware.

Junto a él existen videoStart y videoStop, que son otra historia distinta —esos van por la vía del streaming en vivo, que explico en video en vivo JT1078.

Qué protocolos lo implementan

Aquí está el filtro que evita la frustración. Que el comando exista en la interfaz no significa que tu dispositivo lo entienda: hace falta que el codificador de su protocolo lo haya implementado.

Los codificadores que traducen requestPhoto a una trama real son:

• Fifotrack
• Meitrack
• PT502
• Ruptela
• Meiligao
• GPS103

Además, otros protocolos disparan la solicitud de foto por su propio camino, sin pasar por requestPhoto:

• Teltonika — solicita la foto mediante su comando de cámara (Codec12)
• GT06 / Concox — tiene una solicitud de foto propia, que en algunos casos se dispara automáticamente al recibir determinados mensajes del equipo

Si tu dispositivo no está en ninguna de estas listas, enviar requestPhoto no va a producir nada. No es un fallo de configuración.

Enviarlo desde la interfaz

1. Abre el dispositivo en el panel.
2. Menú de comandos → nuevo comando.
3. Tipo: solicitar foto (requestPhoto).
4. Envía.

Si el dispositivo está desconectado, Traccar puede encolar el comando y entregarlo en la siguiente conexión. Eso explica los eventos queuedCommandSent que ves en el log: el comando salió, no que la foto haya llegado.

Enviarlo desde la API

El endpoint es el mismo que para cualquier otro comando:

curl -u usuario:contrasena \
  -X POST https://tu-servidor.com/api/commands/send \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": 12,
    "type": "requestPhoto"
  }'

Algunos protocolos aceptan atributos adicionales (por ejemplo el canal de cámara). Eso depende enteramente del codificador de cada protocolo, así que consulta el comportamiento de tu modelo concreto antes de asumir que channel va a hacer algo.

Foto bajo demanda vs. foto por evento

Son dos flujos distintos y conviene no confundirlos:

La foto por evento (frenada brusca, SOS, detección de fatiga en equipos con DSM) no se configura en Traccar: se configura en el rastreador, con la herramienta del fabricante. Traccar solo recibe lo que el equipo decida enviarle. Esto pilla a mucha gente buscando en traccar.xml una opción que no está ahí.

Dónde acaba la foto

Cuando la foto llega, se guarda en disco bajo media.path, en la subcarpeta del dispositivo, y en la posición correspondiente aparece un atributo image con el nombre del archivo. Todo el detalle está en cómo funciona el sistema de media y en la guía de configuración de media.path.

Cuando no llega nada

Por orden de probabilidad:

1. El protocolo no lo implementa. Revisa la lista de arriba. Es la causa número uno.

2. El dispositivo está desconectado y el comando quedó encolado. Verifica el estado antes de dar por fallido el envío.

3. La transferencia superó media.bufferSize (32 MB por defecto) y el servidor la descartó. Poco habitual con fotos, frecuente con clips de video.

4. La cámara no está bien conectada al rastreador. En equipos con cámara externa, el cable es sospechoso habitual antes que el software.

5. El archivo se guardó pero no lo ves en la interfaz. Entonces es permiso de usuario sobre el dispositivo, o el proxy inverso. Comprueba primero en disco:

   ls -la /opt/traccar/media/TU_IMEI/
   

Ese ls separa limpiamente los dos mundos: si el archivo está, el problema es de entrega al navegador; si no está, el problema es del dispositivo o del protocolo.