# fleetManage API

> API REST de fleetManage (gestión de flotas para transporte): órdenes, flota, conductores,
> lugares, geocercas, telemetría, precios y operaciones. FastAPI + MongoDB.

## Superficies

- **`/v1/*`** — superficie pública de producto. Autenticación por **API key**:
  cabeceras `X-API-KEY` + `X-API-SECRET`.
- **`/int/v1/*`** — superficie interna de consola. Autenticación por **JWT** (`Authorization: Bearer`,
  HS256) con claim `company_uuid`.
- Ambas exponen el **mismo contrato** de recursos.

## Convenciones

- **Aislamiento por tenant:** el `company_uuid` se resuelve **siempre** de la credencial/sesión;
  enviarlo por query o body devuelve **422**.
- **Listados:** envelope `{ "data": [...], "meta": { "limit", "offset", "total" } }`.
- **Paginación:** `?limit=` (por defecto 25, máximo 100) y `?offset=`.
- **Filtros:** `?where[campo]=valor`, rangos `?campo_gte=` / `?campo_lte=`, búsqueda `?query=`.
- **Errores:** RFC 7807 (`application/problem+json`) con un `code` estable
  (`not_found`, `validation_error`, `duplicate`, `invalid_credential`).
- **Borrado:** `DELETE /{recurso}/{id}` → **204** con *soft-delete*; `DELETE /{recurso}/bulk-delete`
  borra en lote y devuelve `{ "data": [], "meta": { "requested", "deleted" } }`.

## Operaciones implementadas hoy

Recursos `groups`, `categories` y `places` con las 6 operaciones CRUD en **las dos superficies**:

| Método | Ruta | Descripción |
|---|---|---|
| GET | `/{v1,int/v1}/{recurso}` | Listado paginado y filtrable |
| POST | `/{v1,int/v1}/{recurso}` | Crear |
| GET | `/{v1,int/v1}/{recurso}/{id}` | Detalle por `public_id` o uuid |
| PUT | `/{v1,int/v1}/{recurso}/{id}` | Reemplazar |
| PATCH | `/{v1,int/v1}/{recurso}/{id}` | Actualización parcial |
| DELETE | `/{v1,int/v1}/{recurso}/{id}` | Borrado lógico (204) |
| DELETE | `/{v1,int/v1}/{recurso}/bulk-delete` | Borrado en lote |

`GET /health` — estado del servicio (Mongo y Redis).

## Contrato y fuentes

- Contrato canónico: `docs/16-contrato-canonico.md` (prevalece sobre cualquier divergencia).
- Especificación: [`./openapi.yaml`](./openapi.yaml) — **generada** desde la app
  (`python -m api.openapi_export`), nunca editada a mano.
- Repositorio: https://github.com/cargoffer/fleetmanage

## Notas para asistentes

- Los identificadores públicos tienen prefijo por recurso (`group_…`, `place_…`) y son la forma
  recomendada de referirse a un objeto; el uuid interno también se acepta en `{id}`.
- Nunca se acepta `company_uuid` del cliente; un asistente que lo envíe recibirá 422.
- Los secretos (`secret_hash`, `password_hash`, `code_hash`, tokens de refresh) **nunca** se
  devuelven por API.