Ir al contenido

Primeros pasos

La API de TeroVision deja que otro sistema use las cámaras de un espacio: darlas de alta, moverlas, sacar fotos, grabar, mirar el video, hablarles y manejar las automatizaciones. Todo pasa por TeroVision, en https://terovision.com/api/v1, con JSON. Quien integra nunca habla con el servidor de video ni ve sus tokens.

Hay un SDK para TypeScript/JavaScript (sdk/js, Node 18 o más nuevo) y otro para Python (sdk/python, 3.9 o más nuevo). Los dos reintentan lo que se puede reintentar, respetan Retry-After y tienen un error por cada caso.

1. Activá la verificación en dos pasos

Una clave sobrevive a la sesión, así que crearla pide más que estar adentro. Sin la verificación en dos pasos activa en Mi cuenta no se crean claves: el panel muestra el aviso en lugar del botón, y la app contesta 422 two_factor_not_enabled.

2. Creá una clave

En el panel, dentro del espacio: Desarrolladores. Solo dueños y administradores. El panel te vuelve a pedir la contraseña si pasaron más de 15 minutos, y cada alta pide un código de la app de autenticación (o uno de recuperación) en el momento.

Elegís:

  • Nombre: es lo que se ve en el panel y en la auditoría (api:<nombre>), así que conviene uno que diga qué sistema es.
  • Rol máximo: administrador, miembro o solo mira. La clave actúa como vos, con el menor entre ese rol y el tuyo de cada momento.
  • Alcances: qué partes de la API puede tocar. Ver Claves y alcances.
  • Vencimiento (de 7 días a un año) y pedidos por minuto (1 a 600, 120 de fábrica).

La clave (tv_live_<prefijo>_<secreto>) se muestra una sola vez. Guardala como un secreto, en una variable de entorno de tu servidor. Cada alta les manda un mail a vos y a los dueños del espacio, sin la clave.

3. Tu primer pedido

La clave va solo en la cabecera Authorization: Bearer. En la URL se rechaza con 400 key_in_query.

curl — resources/devportal/samples/curl/first-request.sh

export API=https://terovision.com/api/v1
# The key goes only in the Authorization header. In the URL it is rejected (400 key_in_query).
curl -s -H "Authorization: Bearer $TEROVISION_API_KEY" "$API/me"
curl -s -H "Authorization: Bearer $TEROVISION_API_KEY" "$API/cameras?per_page=10"

Con el SDK de TypeScript:

TypeScript / JavaScript — sdk/js/examples/portal/first-request.ts

const tv = new TeroVision({ apiKey: options.apiKey, baseUrl: options.baseUrl, fetch: options.fetch });
// Run this on your server, never in a browser. In production: new TeroVision({ apiKey: process.env.TEROVISION_API_KEY! })

const me = await tv.me();
console.log(me.space.name, me.key.effective_role, me.key.scopes);

const page = await tv.cameras.list({ per_page: 10 });
for (const camera of page.data) {
  console.log(camera.id, camera.name, camera.online ? 'online' : camera.connection);
}

Con el de Python:

Python — sdk/python/examples/portal/first_request.py

with TeroVision(api_key, base_url, transport=transport) as tv:  # run it on your server; the key is a secret
    me = tv.me()
    print(me["space"]["name"], me["key"]["effective_role"], me["key"]["scopes"])

    for camera in tv.cameras.list(per_page=10)["data"]:
        print(camera["id"], camera["name"], "online" if camera["online"] else camera["connection"])

GET /me dice qué clave es, en qué espacio, con qué alcances y con qué rol actúa hoy. Si contesta 401, mirá el code: invalid_key, key_revoked, key_expired o creator_suspended.

4. Los SDK

  • TypeScript: sdk/js (@terovision/sdk). npm ci && npm run build deja ESM, CJS y tipos en dist/. El paquete todavía no está publicado en npm.
  • Python: sdk/python (terovision). pip install ./sdk/python (necesita httpx).

Los dos se niegan a lo que expone la clave: el de TypeScript no arranca en un navegador salvo que se lo fuerces, y ninguno incluye la clave en sus errores ni al imprimir el cliente.

Qué sigue