Guia de integracion app: API de estado automatico

Objetivo

Este endpoint registra actualizaciones automaticas de estado sin tocar el flujo manual existente.

Endpoint: POST /api/trips/:id/auto-status
Auth: Authorization: Bearer <JWT>
Uso: registrar eventos automaticos en backend y auditoria en BBDD.

Cuando usar esta API en la app

Usar esta API cuando el estado se genera automaticamente (por ejemplo, logica de geolocalizacion, reglas de negocio automatas, deteccion de llegada/salida, etc.).

No usar esta API para cambios manuales del conductor desde UI normal de estados; para eso se mantiene POST /api/trips/:id/status.

Reglas funcionales clave

Siempre inserta en c_cambios_estado con actualizado_automaticamente = 1.
Si se envia id_punto:
- id_estado solo puede ser 3, 4 o 5.
- ademas actualiza c_viajes_puntos con actualizado_automaticamente = 1 y borrado_en_app = 0.
- el trigger trg_c_viajes_puntos_tracking_au genera auditoria en c_viajes_puntos_tracking.
Si NO se envia id_punto:
- id_estado puede ser cualquier estado valido de t_viaje_estados.
- no toca c_viajes_puntos.
No actualiza c_viajes.id_estado.
No admite fotos en este endpoint (fotos_concat, foto, multipart).

Contrato request

Ruta: POST /api/trips/:id/auto-status

Body JSON:

{
  "id_estado": 5,
  "id_punto": 8123,
  "observaciones": "Cambio automatico por regla GPS",
  "ind_fallido": 0,
  "latitud": "40.416775",
  "longitud": "-3.703790",
  "fecha_y_hora": "2026-02-17 12:34:56"
}

Campos:

id_estado (obligatorio, entero > 0).
id_punto (opcional, entero > 0).
observaciones (opcional, string).
ind_fallido (opcional, default 0; acepta 0/1, false/true).
latitud y longitud (opcionales; se normalizan y pueden quedar null).
fecha_y_hora (opcional, formato YYYY-MM-DD HH:mm:ss; si no es valida se usa hora servidor).

Respuestas esperadas

200 OK

{
  "success": true,
  "trip_id": 248230,
  "id_estado": 5,
  "id_punto": 8123,
  "actualizado_automaticamente": 1,
  "updated_at": "2026-02-18T09:30:00.000Z"
}

400 payload invalido.
401 token ausente/invalido.
403 usuario sin permisos sobre el viaje.
404 viaje no existe o punto no existe.
422 si se envia id_punto con id_estado fuera de 3/4/5.
500 error interno.

Ejemplo rapido de consumo (JavaScript/TypeScript)

async function sendAutoStatus({
  baseUrl,
  token,
  tripId,
  payload
}: {
  baseUrl: string;
  token: string;
  tripId: number;
  payload: {
    id_estado: number;
    id_punto?: number;
    observaciones?: string;
    ind_fallido?: 0 | 1;
    latitud?: string;
    longitud?: string;
    fecha_y_hora?: string;
  };
}) {
  const response = await fetch(`${baseUrl}/api/trips/${tripId}/auto-status`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`
    },
    body: JSON.stringify(payload)
  });

  const body = await response.json().catch(() => ({}));

  if (!response.ok) {
    throw new Error(`auto-status failed: ${response.status} ${JSON.stringify(body)}`);
  }

  return body;
}

Checklist de integracion en app

Enrutar eventos automaticos a POST /api/trips/:id/auto-status.
Si el evento es de punto, enviar siempre id_punto y id_estado en 3/4/5.
No enviar fotos en este endpoint.
Tratar 422 como error funcional (payload correcto de forma tecnica, pero regla de negocio invalida).
Mantener endpoint manual actual para interaccion humana.

3.5 KiB Raw Blame History