> Índice completo de la documentación: https://trackerintl.com/devs/llms.txt
> Esta página en HTML: https://trackerintl.com/devs/convenciones
> Estado: Verificado, revisada el 2026-10-05. Verificado por lectura del código y diff contra producción; las formas de respuesta se midieron con datos ficticios en un entorno de pruebas. No probado con una cuenta real.

# Convenciones

URL base, formatos, zonas horarias, idioma y los cuatro tipos de paginación de la API de la plataforma, tal como se midieron.

Estas reglas valen para todas las operaciones de la [referencia](/devs/referencia).

## URL base y métodos

- Dominio base: `https://plataforma.trackerintl.com`. Si tu cuenta pertenece a un revendedor marca blanca, usa el dominio que te indique quien la administra.
- Todas las rutas empiezan por `/api`.
- Usa `GET` para consultar y `POST` solo para iniciar sesión. Algunas rutas aceptan otros métodos HTTP, pero no se recomienda usarlos.
- Las respuestas son JSON.

## Idioma

Los textos traducibles de la plataforma (por ejemplo, nombres de tipos de alerta o mensajes de error) salen en el idioma indicado con el parámetro `lang` (`es`, `en`) o con la cabecera `Accept-Language`.

## Fechas y zonas horarias

- **Entrada**: las fechas y horas que envías (`from_date`, `from_time`, `date_from`…) se interpretan en la **zona horaria configurada en la cuenta**, no en UTC. Formatos: fecha `AAAA-MM-DD`, hora `HH:MM` o `HH:MM:SS`.
- **Salida**: conviven dos tipos de campos. Los formateados (por ejemplo `time`, `raw_time`) usan la zona y el formato de la cuenta; en las mediciones el formato fue `dd-mm-AAAA HH:mm:ss`. Los campos crudos (`device_time`, `created_at`, `updated_at`…) vienen en UTC.
- Excepciones: `date_from` y `date_to` de `get_alerts_summary` se comparan sin conversión, en UTC, y `time` de `get_devices_latest` son segundos Unix en UTC.

Cada campo indica su zona en la [referencia](/devs/referencia).

## Paginación

La API no tiene un único esquema de paginación. Estos son los que se midieron:

| Operación | Cómo se pagina | Tamaño de página |
|---|---|---|
| `get_devices` | `page` y `limit`; pagina por vehículo antes de agrupar | `limit` sin tope en el código; se recomienda 200 como máximo. Con solo `page`, 100 |
| `get_devices_latest` | `page` y `limit` | 100 por defecto si envías `page` |
| `get_history_messages` | `page` y `limit`; la respuesta trae `current_page`, `last_page` y `total` | `limit` solo admite 50, 100, 200, 300, 400, 500 o 1000; cualquier otro valor se sustituye por 50 |
| `get_events` | Sin `page`: cursor (`next_cursor` en la respuesta, que envías como `cursor`). Con `page`: totales | `limit` 30 por defecto, 1000 como máximo |
| `get_routes` | `page` | 500 fijos |
| `get_reports`, `get_user_drivers` | `page` y `limit` | 10 por defecto |
| `sent_commands` | `page` | 15 fijos |

## Detalles que conviene conocer

- **Cadenas JSON dentro de JSON**: algunos campos llegan como texto que debes decodificar, por ejemplo `coordinates` en las geocercas o `sensors`, `services` y `tail` en `get_devices_latest`.
- **Valores sin dato**: varios campos de texto usan `"-"` cuando no hay valor.
- **Errores con HTTP 200**: algunas validaciones responden `200` con `{"status": 0, "errors": {...}}`. Comprueba siempre `status`. Mira [Errores](/devs/errores).
- **Permisos**: si el usuario no tiene permiso sobre un módulo, algunas operaciones devuelven una lista vacía con `200` y otras un `403`. Cada operación lo indica.