> Índice completo de la documentación: https://trackerintl.com/devs/llms.txt
> Esta página en HTML: https://trackerintl.com/devs/primeros-pasos
> Estado: Parcial, revisada el 2026-10-05. Los endpoints se verificaron en producción por lectura del código y diff. Los ejemplos se ejecutaron contra un servidor simulado con datos ficticios; todavía no se han ejecutado contra una cuenta real.

# Primeros pasos

De cero a tu primera consulta: inicia sesión, lista tus vehículos, pide su última posición y trae el historial de un día, con ejemplos ejecutables.

En esta guía haces cuatro llamadas: iniciar sesión, listar vehículos, pedir sus últimas posiciones y traer el historial de un día. Necesitas un usuario de la plataforma y, según el lenguaje, cURL, Node.js 22, Python 3 con `requests` o PHP 8 con cURL.

> **Valores de ejemplo.**
>
> `TU_API_HASH`, `demo@example.com` y `TU_CONTRASENA` son marcadores. Sustitúyelos por tus valores. Los datos de las respuestas son ficticios. Nunca pegues tu hash real en tickets, repositorios ni URLs compartidas.

## 1. Inicia sesión y obtén tu hash

**Iniciar sesión y obtener el hash**

cURL:

```bash
curl -sS -X POST "https://plataforma.trackerintl.com/api/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"TU_CONTRASENA"}'
```

JavaScript:

```javascript
const BASE_URL = "https://plataforma.trackerintl.com";

const respuesta = await fetch(`${BASE_URL}/api/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "demo@example.com", password: "TU_CONTRASENA" }),
});
if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status}: ${await respuesta.text()}`);
console.log(JSON.stringify(await respuesta.json(), null, 2));
```

Python:

```python
import json
import requests

BASE_URL = "https://plataforma.trackerintl.com"

respuesta = requests.post(
    f"{BASE_URL}/api/login",
    json={"email": "demo@example.com", "password": "TU_CONTRASENA"},
    timeout=30,
)
respuesta.raise_for_status()
print(json.dumps(respuesta.json(), indent=2, ensure_ascii=False))
```

PHP:

```php
<?php
$baseUrl = "https://plataforma.trackerintl.com";

$url = $baseUrl . "/api/login";
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["email" => "demo@example.com", "password" => "TU_CONTRASENA"]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
]);
$cuerpo = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($cuerpo === false || $codigo !== 200) {
    fwrite(STDERR, "HTTP $codigo\n");
    exit(1);
}
echo json_encode(json_decode($cuerpo, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";
```

La respuesta trae tu `user_api_hash` y tus permisos:

Fragmento del ejemplo de respuesta (datos ficticios; se omiten campos).

```json
{
  "status": 1,
  "user_api_hash": "TU_API_HASH"
}
```

Copia el valor de `user_api_hash`: lo usarás en las llamadas siguientes. Ver más en [Autenticación](/devs/autenticacion).

## 2. Lista tus vehículos

**Listar vehículos**

cURL:

```bash
curl -sS -G "https://plataforma.trackerintl.com/api/get_devices" \
  -H "user-api-hash: TU_API_HASH" \
  --data-urlencode "limit=50" \
  --data-urlencode "page=1"
```

JavaScript:

```javascript
const BASE_URL = "https://plataforma.trackerintl.com";
const API_HASH = "TU_API_HASH";

const params = new URLSearchParams({
  limit: "50",
  page: "1",
});
const respuesta = await fetch(`${BASE_URL}/api/get_devices?${params}`, {
  headers: { "user-api-hash": API_HASH },
});
if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status}: ${await respuesta.text()}`);
console.log(JSON.stringify(await respuesta.json(), null, 2));
```

Python:

```python
import json
import requests

BASE_URL = "https://plataforma.trackerintl.com"
API_HASH = "TU_API_HASH"

respuesta = requests.get(
    f"{BASE_URL}/api/get_devices",
    headers={"user-api-hash": API_HASH},
    params={"limit": "50", "page": "1"},
    timeout=30,
)
respuesta.raise_for_status()
print(json.dumps(respuesta.json(), indent=2, ensure_ascii=False))
```

PHP:

```php
<?php
$baseUrl = "https://plataforma.trackerintl.com";
$apiHash = "TU_API_HASH";

$url = $baseUrl . "/api/get_devices?" . http_build_query(["limit" => "50", "page" => "1"]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ["user-api-hash: " . $apiHash],
]);
$cuerpo = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($cuerpo === false || $codigo !== 200) {
    fwrite(STDERR, "HTTP $codigo\n");
    exit(1);
}
echo json_encode(json_decode($cuerpo, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";
```

La respuesta es un arreglo de grupos; cada grupo trae sus vehículos en `items`. El grupo `0` reúne los vehículos sin grupo. Un vehículo del ejemplo, con algunos de sus campos:

Fragmento del ejemplo de respuesta (datos ficticios; se omiten campos).

```json
{
  "id": 9001,
  "name": "Camioneta de prueba 01",
  "online": "online",
  "lat": -17.7733,
  "lng": -63.192099999999996,
  "speed": 42,
  "time": "05-10-2026 16:11:06"
}
```

El campo `id` identifica al vehículo en el resto de la API (por ejemplo, como `device_id`).

## 3. Pide las últimas posiciones

**Posiciones actualizadas desde un instante**

cURL:

```bash
curl -sS -G "https://plataforma.trackerintl.com/api/get_devices_latest" \
  -H "user-api-hash: TU_API_HASH" \
  --data-urlencode "time=1"
```

JavaScript:

```javascript
const BASE_URL = "https://plataforma.trackerintl.com";
const API_HASH = "TU_API_HASH";

const params = new URLSearchParams({
  time: "1",
});
const respuesta = await fetch(`${BASE_URL}/api/get_devices_latest?${params}`, {
  headers: { "user-api-hash": API_HASH },
});
if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status}: ${await respuesta.text()}`);
console.log(JSON.stringify(await respuesta.json(), null, 2));
```

Python:

```python
import json
import requests

BASE_URL = "https://plataforma.trackerintl.com"
API_HASH = "TU_API_HASH"

respuesta = requests.get(
    f"{BASE_URL}/api/get_devices_latest",
    headers={"user-api-hash": API_HASH},
    params={"time": "1"},
    timeout=30,
)
respuesta.raise_for_status()
print(json.dumps(respuesta.json(), indent=2, ensure_ascii=False))
```

PHP:

```php
<?php
$baseUrl = "https://plataforma.trackerintl.com";
$apiHash = "TU_API_HASH";

$url = $baseUrl . "/api/get_devices_latest?" . http_build_query(["time" => "1"]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ["user-api-hash: " . $apiHash],
]);
$cuerpo = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($cuerpo === false || $codigo !== 200) {
    fwrite(STDERR, "HTTP $codigo\n");
    exit(1);
}
echo json_encode(json_decode($cuerpo, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";
```

Con `time=1` obtienes todos los vehículos. En consultas posteriores envía el valor `time` que devolvió la respuesta anterior y recibirás solo los vehículos con posición nueva. La guía [Posición en vivo](/devs/guias/posicion-en-vivo) lo explica paso a paso.

## 4. Trae el historial de un día

Sustituye `device_id` por el `id` de uno de tus vehículos. Las fechas se interpretan en la zona horaria de tu cuenta.

**Recorrido de un vehículo por tramos**

cURL:

```bash
curl -sS -G "https://plataforma.trackerintl.com/api/get_history" \
  -H "user-api-hash: TU_API_HASH" \
  --data-urlencode "device_id=9001" \
  --data-urlencode "from_date=2026-10-01" \
  --data-urlencode "from_time=00:00" \
  --data-urlencode "to_date=2026-10-02" \
  --data-urlencode "to_time=23:59"
```

JavaScript:

```javascript
const BASE_URL = "https://plataforma.trackerintl.com";
const API_HASH = "TU_API_HASH";

const params = new URLSearchParams({
  device_id: "9001",
  from_date: "2026-10-01",
  from_time: "00:00",
  to_date: "2026-10-02",
  to_time: "23:59",
});
const respuesta = await fetch(`${BASE_URL}/api/get_history?${params}`, {
  headers: { "user-api-hash": API_HASH },
});
if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status}: ${await respuesta.text()}`);
console.log(JSON.stringify(await respuesta.json(), null, 2));
```

Python:

```python
import json
import requests

BASE_URL = "https://plataforma.trackerintl.com"
API_HASH = "TU_API_HASH"

respuesta = requests.get(
    f"{BASE_URL}/api/get_history",
    headers={"user-api-hash": API_HASH},
    params={"device_id": "9001", "from_date": "2026-10-01", "from_time": "00:00", "to_date": "2026-10-02", "to_time": "23:59"},
    timeout=30,
)
respuesta.raise_for_status()
print(json.dumps(respuesta.json(), indent=2, ensure_ascii=False))
```

PHP:

```php
<?php
$baseUrl = "https://plataforma.trackerintl.com";
$apiHash = "TU_API_HASH";

$url = $baseUrl . "/api/get_history?" . http_build_query(["device_id" => "9001", "from_date" => "2026-10-01", "from_time" => "00:00", "to_date" => "2026-10-02", "to_time" => "23:59"]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ["user-api-hash: " . $apiHash],
]);
$cuerpo = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($cuerpo === false || $codigo !== 200) {
    fwrite(STDERR, "HTTP $codigo\n");
    exit(1);
}
echo json_encode(json_decode($cuerpo, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";
```

La respuesta trae el recorrido dividido en tramos de conducción y de parada, y totales del periodo. El rango máximo es de 31 días. Un fragmento de los totales:

Fragmento del ejemplo de respuesta (datos ficticios; se omiten campos).

```json
{
  "distance_sum": "9.2 Km",
  "top_speed": "31 kph",
  "move_duration": "1h 28min 0s",
  "stop_duration": "30min 0s"
}
```

## Todo junto en un script

Este script encadena los cuatro pasos: inicia sesión, toma el primer vehículo de tu lista y pide su historial.

**Script completo**

cURL:

```bash
#!/usr/bin/env bash
# Requiere curl y jq.
BASE_URL="https://plataforma.trackerintl.com"

# 1. Inicio de sesión
HASH=$(curl -sS -X POST "$BASE_URL/api/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"TU_CONTRASENA"}' | jq -r '.user_api_hash')

# 2. Vehículos (arreglo de grupos con sus vehículos en "items")
VEHICULOS=$(curl -sS -G "$BASE_URL/api/get_devices" -H "user-api-hash: $HASH" --data-urlencode "limit=50")
echo "Vehículos: $(echo "$VEHICULOS" | jq '[.[].items[]] | length')"

# 3. Historial del primer vehículo
ID=$(echo "$VEHICULOS" | jq -r '[.[].items[]][0].id')
curl -sS -G "$BASE_URL/api/get_history" -H "user-api-hash: $HASH" \
  --data-urlencode "device_id=$ID" \
  --data-urlencode "from_date=2026-10-01" --data-urlencode "from_time=00:00" \
  --data-urlencode "to_date=2026-10-02" --data-urlencode "to_time=23:59" \
  | jq -r '"\(.distance_sum) en \(.items | length) tramos"'
```

JavaScript:

```javascript
const BASE_URL = "https://plataforma.trackerintl.com";

async function llamar(ruta, { metodo = "GET", query = {}, cuerpo, hash } = {}) {
  const url = `${BASE_URL}${ruta}?${new URLSearchParams(query)}`;
  const headers = {};
  if (hash) headers["user-api-hash"] = hash;
  if (cuerpo) headers["Content-Type"] = "application/json";
  const respuesta = await fetch(url, { method: metodo, headers, body: cuerpo && JSON.stringify(cuerpo) });
  if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status} en ${ruta}`);
  return respuesta.json();
}

// 1. Inicio de sesión
const sesion = await llamar("/api/login", {
  metodo: "POST",
  cuerpo: { email: "demo@example.com", password: "TU_CONTRASENA" },
});
const hash = sesion.user_api_hash;

// 2. Vehículos (arreglo de grupos con sus vehículos en "items")
const grupos = await llamar("/api/get_devices", { hash, query: { limit: "50" } });
const vehiculos = grupos.flatMap((grupo) => grupo.items);
console.log(`Vehículos: ${vehiculos.length}`);

// 3. Historial del primer vehículo
const primero = vehiculos[0];
const historial = await llamar("/api/get_history", {
  hash,
  query: { device_id: String(primero.id), from_date: "2026-10-01", from_time: "00:00", to_date: "2026-10-02", to_time: "23:59" },
});
console.log(`${primero.name}: ${historial.distance_sum} en ${historial.items.length} tramos`);
```

Python:

```python
import requests

BASE_URL = "https://plataforma.trackerintl.com"


def llamar(ruta, metodo="GET", query=None, cuerpo=None, hash_api=None):
    cabeceras = {"user-api-hash": hash_api} if hash_api else {}
    respuesta = requests.request(metodo, f"{BASE_URL}{ruta}", params=query, json=cuerpo, headers=cabeceras, timeout=30)
    respuesta.raise_for_status()
    return respuesta.json()


# 1. Inicio de sesión
sesion = llamar("/api/login", metodo="POST", cuerpo={"email": "demo@example.com", "password": "TU_CONTRASENA"})
hash_api = sesion["user_api_hash"]

# 2. Vehículos (arreglo de grupos con sus vehículos en "items")
grupos = llamar("/api/get_devices", query={"limit": "50"}, hash_api=hash_api)
vehiculos = [vehiculo for grupo in grupos for vehiculo in grupo["items"]]
print(f"Vehículos: {len(vehiculos)}")

# 3. Historial del primer vehículo
primero = vehiculos[0]
historial = llamar(
    "/api/get_history",
    query={"device_id": str(primero["id"]), "from_date": "2026-10-01", "from_time": "00:00", "to_date": "2026-10-02", "to_time": "23:59"},
    hash_api=hash_api,
)
print(f"{primero['name']}: {historial['distance_sum']} en {len(historial['items'])} tramos")
```

PHP:

```php
<?php
$baseUrl = "https://plataforma.trackerintl.com";

function llamar(string $ruta, array $query = [], ?array $cuerpo = null, ?string $hash = null): array
{
    global $baseUrl;
    $ch = curl_init($baseUrl . $ruta . ($query ? "?" . http_build_query($query) : ""));
    $cabeceras = $hash ? ["user-api-hash: " . $hash] : [];
    $opciones = [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30];
    if ($cuerpo !== null) {
        $cabeceras[] = "Content-Type: application/json";
        $opciones[CURLOPT_POST] = true;
        $opciones[CURLOPT_POSTFIELDS] = json_encode($cuerpo);
    }
    $opciones[CURLOPT_HTTPHEADER] = $cabeceras;
    curl_setopt_array($ch, $opciones);
    $texto = curl_exec($ch);
    $codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($texto === false || $codigo !== 200) {
        fwrite(STDERR, "HTTP $codigo en $ruta\n");
        exit(1);
    }
    return json_decode($texto, true);
}

// 1. Inicio de sesión
$sesion = llamar("/api/login", [], ["email" => "demo@example.com", "password" => "TU_CONTRASENA"]);
$hash = $sesion["user_api_hash"];

// 2. Vehículos (arreglo de grupos con sus vehículos en "items")
$grupos = llamar("/api/get_devices", ["limit" => "50"], null, $hash);
$vehiculos = array_merge(...array_column($grupos, "items"));
echo "Vehículos: " . count($vehiculos) . "\n";

// 3. Historial del primer vehículo
$primero = $vehiculos[0];
$historial = llamar("/api/get_history", [
    "device_id" => (string) $primero["id"],
    "from_date" => "2026-10-01", "from_time" => "00:00",
    "to_date" => "2026-10-02", "to_time" => "23:59",
], null, $hash);
echo $primero["name"] . ": " . $historial["distance_sum"] . " en " . count($historial["items"]) . " tramos\n";
```

## Siguientes pasos

- [Convenciones](/devs/convenciones): zonas horarias, formatos y paginación.
- [Errores](/devs/errores): qué significa cada respuesta de error.
- [Referencia de la API](/devs/referencia): todas las operaciones documentadas.
- [Guías](/devs/guias): sincronizar con un ERP o CRM, posición en vivo e historial por periodos.