120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# 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.
|