# 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
1. Siempre inserta en `c_cambios_estado` con `actualizado_automaticamente = 1`.
2. 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`.
3. Si NO se envia `id_punto`:
   - `id_estado` puede ser cualquier estado valido de `t_viaje_estados`.
   - no toca `c_viajes_puntos`.
4. No actualiza `c_viajes.id_estado`.
5. No admite fotos en este endpoint (`fotos_concat`, `foto`, multipart).

## Contrato request
Ruta:
`POST /api/trips/:id/auto-status`

Body JSON:

```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`

```json
{
  "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)
```ts
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
1. Enrutar eventos automaticos a `POST /api/trips/:id/auto-status`.
2. Si el evento es de punto, enviar siempre `id_punto` y `id_estado` en `3/4/5`.
3. No enviar fotos en este endpoint.
4. Tratar `422` como error funcional (payload correcto de forma tecnica, pero regla de negocio invalida).
5. Mantener endpoint manual actual para interaccion humana.