# Quickstart

**Preview 0.45** Disponible · Preview 0.45. La API puede cambiar antes de la 1.0: ver [Fases de lanzamiento](/docs/es/resources/release-phases/).

## Antes de empezar

- Una cuenta de DevLab con equipo (organización <tu organización>, equipo <tu equipo>). La API key de tu equipo está en [Tu cuenta](/account): <tu key>. En los ejemplos aparece como `<your-api-key>`.
- La URL de Engine de tu entorno está en el kit de un protocolo, en [Tu integración](/integration) (un protocolo → **Kit** → `.env.example` → la línea `ENGINE_BASE`; [dónde exactamente](/docs/es/access/kit/#dónde-está-la-url-de-engine)): el kit reúne la configuración del cliente de ese protocolo, el entorno de tu backend y un starter listo para ejecutar por modo ([Tu kit](/docs/es/access/kit/)). Los ejemplos la llaman `$ENGINE`.
- Para la vía cURL, `curl` y `jq` instalados.
- Para el SDK, Node.js 20.3 o posterior (`@neurologyca/capture-server` solo corre en el servidor).
- Guarda la API key en tu servidor. Nunca la pongas en una página ni en una app.
- Para el SDK, el **token del registro** (`NODE_AUTH_TOKEN`): **lo entrega Neurologyca con tu invitación**, por el mismo canal que la key; no está en DevLab.

> ¿Has iniciado sesión con un equipo? Tu organización y tu equipo aparecen en esta página, y tu API key está en [Tu cuenta](/account). El catálogo de tu organización, con cada protocolo en el visualizador, está en [Tu integración](/integration).

En qué puedes inscribir a las personas depende de **los contextos de tu organización** (ver [Qué es Engine 2](/docs/es/start/what-is/)). Este quickstart usa **Measurement**: una posición, un step e indicadores sin interpretación. Engine recomienda un baseline antes de cualquier protocolo; la inscripción responde con `baselineWarning`, pero no bloquea, así que este quickstart se lo salta.

Qué consigues: una persona medida con la cámara o un vídeo, y los indicadores que devuelve Engine, en tu propia página.

> Lo más rápido: en [Tu integración](/integration), un protocolo → **Kit** → **Descargar .zip** con **Incluir mi key**, y `npm install && npm start`. Mides en pocos minutos ([Tu kit](/docs/es/access/kit/#los-starters)). Las pestañas de abajo construyen lo mismo a mano.

## Elige tu camino

### SDK

#### 1. Configura el registro

En una carpeta nueva para el quickstart, crea `.npmrc` con:

```ini
@neurologyca:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```

Después define el token del registro en tu shell, antes de instalar:

```bash
export NODE_AUTH_TOKEN="<your-registry-token>"
```

En PowerShell:

```powershell
$env:NODE_AUTH_TOKEN = "<your-registry-token>"
```

#### 2. Instala

```bash
npm init -y && npm pkg set type=module
npm install @neurologyca/capture@0.45.0 @neurologyca/capture-server@0.20.1 esbuild
```

#### 3. Tu backend

Crea a una persona, la inscribe en Measurement y hace de proxy de las llamadas del navegador con tu key. El navegador nunca lleva un token. No lo despliegues: no tiene sesión, así que cualquiera que lo abra capturaría con tu key a través de su proxy.

Guarda `server.mjs`, `index.html` y `page.js` en esa carpeta. `server.mjs` sirve `index.html` desde ahí y el bundle desde `public/page.js`, que crea el paso 5. Los tres ficheros se publican tal cual se ejecutan, así que sus comentarios y mensajes están en inglés.

```js title="server.mjs"
// Your backend for the quickstart (Node 20.3+). It creates one person, enrols them in Measurement and proxies the
// browser's calls to Engine with your key, which only lives here.
//   ENGINE_BASE=<your Engine URL> ENGINE_API_KEY=<your key> node server.mjs
import http from 'node:http'
import { readFile } from 'node:fs/promises'
import { createEngineAdmin, createTokenSource, createEngineProxy, ownsAll } from '@neurologyca/capture-server'
import { toNodeListener } from '@neurologyca/capture-server/node'

const { ENGINE_BASE, ENGINE_API_KEY, PORT = '3000' } = process.env
if (!ENGINE_BASE || !ENGINE_API_KEY) throw new Error('Set ENGINE_BASE (your environment\'s Engine URL, in your kit) and ENGINE_API_KEY')

// 1. One person and their enrolment. In your app: your signed-in user, and the pair saved in your database.
const admin = createEngineAdmin({ baseUrl: ENGINE_BASE, apiKey: ENGINE_API_KEY })
const measurement = (await admin.listProtocolLibrary()).find((p) => p.name === 'Measurement' && p.status === 'published')
if (!measurement) {
  console.error('Your environment does not offer the Measurement protocol yet. Ask Neurologyca, or use the cURL tab with another protocol.')
  process.exit(1)
}
const { externalId } = await admin.createUser({ name: 'quickstart-user' }) // the package generates an opaque UUID
const { userProtocolId } = await admin.enrol(externalId, measurement.pid)
const next = await admin.getNextPosition(userProtocolId)
if (!next) throw new Error('The enrolment has no position to capture')
const pair = { userProtocolId, protocolMechanicId: next.protocolMechanicId }
console.log(`Person ${externalId} enrolled in Measurement. Each start creates one: delete it when you are done (irreversible), with ENGINE_BASE and ENGINE_API_KEY set as for server.mjs:
  node --input-type=module -e "import { createEngineAdmin } from '@neurologyca/capture-server'; await createEngineAdmin({ baseUrl: process.env.ENGINE_BASE, apiKey: process.env.ENGINE_API_KEY }).deleteUser('${externalId}')"`)

// 2. The proxy: the browser calls /engine/* with no token and the proxy adds yours. ownsAll checks every id a route
// carries: here, only this person's enrolment.
const tokens = createTokenSource({ baseUrl: ENGINE_BASE, apiKey: ENGINE_API_KEY })
const engine = toNodeListener(createEngineProxy({
  baseUrl: ENGINE_BASE,
  tokens,
  mountPath: '/engine',
  authorize: async (_req, route) => ownsAll(route, {
    userProtocol: async (up) => up === pair.userProtocolId,
    user: async (userId) => userId === externalId,
  }),
}))

// 3. The page, its bundle and the pair.
const files = new Map([['/', ['index.html', 'text/html']], ['/page.js', ['public/page.js', 'text/javascript']]])
const server = http.createServer(async (req, res) => {
  const url = req.url ?? '/'
  if (url.startsWith('/engine/')) return engine(req, res) // before any body parser
  if (url === '/pair') {
    res.writeHead(200, { 'content-type': 'application/json' })
    return res.end(JSON.stringify(pair))
  }
  const file = files.get(url)
  if (!file) { res.writeHead(404); return res.end() }
  res.writeHead(200, { 'content-type': file[1] })
  res.end(await readFile(new URL(file[0], import.meta.url)))
})
server.listen(Number(PORT), () => {
  const { port } = /** @type {import('node:net').AddressInfo} */ (server.address())
  console.log(`Open http://localhost:${port}`)
})
```

#### 4. Tu página

```html title="index.html"
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Quickstart: Measurement with the SDK</title>
<p><label>Optional, a video of yours with a face: <input id="file" type="file" accept="video/*"></label></p>
<video id="video" muted playsinline width="320"></video>
<p><button id="start">Start</button> <button id="cancel" disabled>Cancel</button></p>
<pre id="out"></pre>
<script type="module" src="/page.js"></script>
</html>
```

```js title="page.js"
// Your page: a short Measurement capture with the SDK, from the camera or from a video file of yours.
// Bundle it for the browser: npx esbuild page.js --bundle --format=esm --outfile=public/page.js
import { createProtocolClient, classifyMediaError } from '@neurologyca/capture'

const out = /** @type {HTMLPreElement} */ (document.querySelector('#out'))
const video = /** @type {HTMLVideoElement} */ (document.querySelector('#video'))
const picker = /** @type {HTMLInputElement} */ (document.querySelector('#file'))
const cancel = /** @type {HTMLButtonElement} */ (document.querySelector('#cancel'))

// One client for the whole page, created when it loads and reused for every capture.
const client = createProtocolClient({
  baseUrl: '/engine', // your backend's proxy: the browser carries no token
  keepPrepared: true, // what prepare() loaded survives a capture: measure again without preparing in between
  taxonomy: { contextId: 'measurement' }, // Measurement: any value; required by the SDK, though Measurement does not send it (0.29.0)
  startup: { includeUserAgent: false }, // the startup report stays in the SDK: no user agent, and nothing is sent anywhere
  // The SDK's own words for each startup stage of a capture (userMessage), ready to show.
  onStartupStage: (e) => { if (e.kind === 'capture' && e.userMessage) out.textContent = e.userMessage },
  onWarning: (w) => console.warn(w.code, w.message),
  onError: (e) => { out.textContent = `${e.code}: ${e.message}` }, // a failure mid-capture (a 409, a lost session): its cause
})
// Prepare once, before the first click, so Start does not wait for the face model. It never calls Engine and asks for no
// permission. With keepPrepared the models stay between captures: no prepare() after one. It does not reject on a failed
// load (the capture then loads it itself). The SDK releases what it kept when the page goes away (pagehide): you do not
// listen for it. Call client.release() only when you drop the client, or between one person and the next.
const prepare = () => { client.prepare().catch((e) => console.warn(e.code, e.message)) }
prepare()

document.querySelector('#start')?.addEventListener('click', async () => {
  out.textContent = 'Capturing…'
  // Cancel: before the capture starts, the signal cuts the start; once it runs, session.abort() ends it.
  const stopper = new AbortController()
  /** @type {Awaited<ReturnType<typeof client.captureProtocol>> | null} */
  let session = null
  cancel.disabled = false
  cancel.onclick = () => { stopper.abort(); void session?.abort().catch(() => { /* already over */ }) }
  try {
    // The pair comes from your backend (it enrolled the person), never from the browser.
    const { userProtocolId, protocolMechanicId } = await (await fetch('/pair')).json()
    const file = picker.files?.[0]
    video.srcObject = null // an earlier camera run left its stream here, and it would hide your video
    if (file) video.src = URL.createObjectURL(file) // a video of yours: give it its src BEFORE capturing
    session = await client.captureProtocol({
      captureId: crypto.randomUUID(), // yours: it joins this capture's warnings and startup report
      userProtocolId,
      protocolMechanicId,
      source: file ? { type: 'video', el: video } : { type: 'webcam' },
      signal: stopper.signal,
      // Your video: play it now (muted, so it plays on its own). The camera: show the SDK's preview in your <video>.
      onStarted: (preview) => { if (!file) video.srcObject = preview.srcObject; video.play().catch((e) => { out.textContent = String(e) }) },
      triggerAnalysis: false, // Measurement: nothing to interpret. SDK 0.29.0 skips it when Engine returns interpreted: false; keep it until yours does
    })
    const [step] = session.plan.steps // Measurement has one step, of 6 s or more
    if (file) video.currentTime = 0 // the SDK loaded its model meanwhile: rewind so no second of your file is lost
    await session.step(step.order).run({ durationMs: 15_000 }) // a shorter video ends it earlier
    const outcome = await session.stop()
    console.log(outcome)
    out.textContent = JSON.stringify(outcome, null, 2)
  } catch (e) {
    // classifyMediaError names the cause: insecure-context (not HTTPS or localhost), denied, no-device, in-use, no-frames…
    const err = /** @type {Error & { code?: string }} */ (e)
    out.textContent = stopper.signal.aborted ? 'Cancelled.' : `${classifyMediaError(e) ?? err.code ?? err.name}: ${err.message}`
    await session?.abort().catch(() => { /* already over */ })
  } finally {
    cancel.onclick = null
    cancel.disabled = true
  }
})
```

`taxonomy: { contextId: 'measurement' }` y `triggerAnalysis: false`: el `contextId` sigue siendo obligatorio, aunque Measurement no lo envía. Desde la 0.29.0 el SDK se salta solo el análisis cuando Engine dice `interpreted: false`; producción aún no lo devuelve, así que mantén `triggerAnalysis: false` ([Solo medir](/docs/es/guides/measurement/)).

El cliente se crea una sola vez, al cargar la página, y `client.prepare()` corre enseguida: carga el modelo de la cara mientras la persona lee la página, así que **Start** no lo espera. `prepare()` nunca llama a Engine, no pide ningún permiso y no rechaza si falla una descarga (la captura carga entonces lo que necesita). Con `keepPrepared: true` lo cargado se queda para la siguiente captura del mismo cliente, así que no hay ningún `prepare()` entre capturas: cada una adopta lo que dejó la anterior (en Safari e iOS, solo la cara). El SDK lo suelta solo al salir de la página; llama a `client.release()` solo al soltar el cliente, o entre una persona y la siguiente en el mismo dispositivo. `signal` es lo que usa Cancel: corta el arranque y, con la captura en marcha, `session.abort()` la termina. `captureId` es tuyo y une los avisos de la captura con su informe de arranque. `startup: { includeUserAgent: false }` deja el user agent del navegador fuera de ese informe, que se queda en el SDK: nada lo envía a ningún sitio. `onStartupStage` da el texto propio del SDK para cada etapa (`userMessage`), listo para mostrar. Más en [Preparar antes de Empezar](/docs/es/sdk/on-device/#preparar-antes-de-empezar) y [La pantalla de arranque](/docs/es/sdk/on-device/#la-pantalla-de-arranque); para que el arranque no se note en tu flujo, [Cargar los modelos](/docs/es/guides/load-models/).

#### 5. Ejecútalo

```bash
npx esbuild page.js --bundle --format=esm --outfile=public/page.js
ENGINE_BASE="<engine base URL>" ENGINE_API_KEY="<your-api-key>" node server.mjs
```

En PowerShell, la segunda línea es:

```powershell
$env:ENGINE_BASE = "<engine base URL>"; $env:ENGINE_API_KEY = "<your-api-key>"; node server.mjs
```

`ENGINE_BASE` es el mismo valor que `$ENGINE`: la URL de Engine de tu entorno, que está en tu kit ([dónde](/docs/es/access/kit/#dónde-está-la-url-de-engine)).

Abre `http://localhost:3000` en Chrome, Edge o Safari (16.4+): la cámara solo se abre en HTTPS o en `localhost`. Pulsa **Start** y permite la cámara, o elige antes un vídeo tuyo con una cara. Pulsa **Start** una vez, y para medir otra vez vuelve a arrancar `server.mjs`: el par es una posición, Engine lo rechaza una vez capturada, y cada arranque crea e inscribe a una persona nueva. Con la cámara, la página enseña la vista previa de la cámara (la del SDK, en tu `<video>`); con un vídeo, lo reproduce cuando empieza la captura y lo rebobina antes del step, para no perder ni un segundo. Para probarlo en el móvil, mira [Pruébalo en tu móvil](/docs/es/sdk/on-device/#probar-en-tu-móvil).

Salida esperada, en la página y en la consola:

```json
{
  "status": "complete",
  "hcis": {
    "valence": "<number>",
    "arousal": "<number>",
    "Confusion": "<number>",
    "Stress_intens": "<number>"
  },
  "hcisByStep": {
    "1": {
      "valence": "<number>",
      "arousal": "<number>",
      "Confusion": "<number>",
      "Stress_intens": "<number>"
    }
  },
  "frameCount": 450,
  "interpretation": null,
  "structured": null
}
```

Los valores salen de la cara de una persona, así que aquí van sin ellos; los nombres son los indicadores públicos que recibes. El ejemplo enseña 4 de las 65 señales en total, de una captura de prueba con Measurement, que recibe todos los indicadores públicos; otro contexto puede recibir menos ([cuáles](/docs/es/concepts/results/#human-context-indicators)). El resultado llega segundos después de que acabe el step de 15 segundos: bastante menos de un minuto desde que se pulsa Start.

¿Sin cámara ni vídeo? [Mira el ejemplo en el playground](/playground).

### cURL

#### 1. Pide un token

```bash
export ENGINE="<engine base URL>"
export ENGINE_API_KEY="<your-api-key>"

TOKEN=$(curl -s -X POST "$ENGINE/token" \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\":\"$ENGINE_API_KEY\"}" | jq -r .token)
```

Respuesta esperada:

```json
{ "token": "<jwt>", "expiresIn": 3600 }
```

#### 2. Crea un usuario

Engine identifica a las personas con un id que eliges tú (`externalId`). Usa un id opaco, nunca un email ni un nombre. Cada ejecución crea una persona nueva: `EXT` lleva la hora, así que repetir los pasos crea otra. El paso 8 la borra.

```bash
EXT="quickstart-$(date +%s)"
curl -s -X POST "$ENGINE/users" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"externalId\":\"$EXT\",\"name\":\"quickstart-user\"}"
```

Respuesta esperada (recortada):

```json
{
  "externalId": "quickstart-1767225600",
  "name": "quickstart-user",
  "createdBy": "<your-credential-name>",
  "lastAccessAt": null
}
```

#### 3. Mira qué puede usar tu organización e inscribe al usuario

El catálogo es **el de tu organización**: Neurologyca asigna contextos a cada organización, y estas listas solo contienen protocolos de esos contextos. Lista primero tus contextos y tus protocolos:

```bash
curl -s "$ENGINE/catalog/contexts" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {name, taxonomy}'
curl -s "$ENGINE/catalog/protocols" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {pid, name, status}'
```

Tus listas serán distintas. En el entorno de pruebas todas las organizaciones ven **Baseline** y **Measurement**, que allí es universal; por ejemplo:

```json
[
  {
    "pid": "00000000-0000-4000-8000-0147b17fe72c",
    "name": "Measurement",
    "status": "published"
  },
  {
    "pid": "00000000-0000-4000-8000-53ac3da6df87",
    "name": "Baseline",
    "status": "published"
  }
]
```

Filtra por `status: published`: el catálogo trae también versiones archivadas con el mismo nombre, y una archivada se puede inscribir con un aviso, así que sin el filtro podrías inscribirte en la antigua.

Cada entrada trae el `pid` con el que se inscribe. Toma el protocolo Measurement e inscribe al usuario:

```bash
# Measurement by default. To use another protocol, set PROTOCOL to its pid before running this block.
PROTOCOL=${PROTOCOL:-$(curl -s "$ENGINE/catalog/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.[] | select(.name=="Measurement" and .status=="published") | .pid')}

if [ -z "$PROTOCOL" ]; then
  echo "Your environment does not offer the Measurement protocol yet. Set PROTOCOL to a pid from the list above (except Baseline) and run this block again." >&2
  false
else
  UP=$(curl -s -X POST "$ENGINE/user-protocols" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId)
  echo "UP=$UP"
fi
```

Si tu entorno aún no ofrece el protocolo Measurement, el bloque se para con un mensaje en inglés que dice eso: fija `PROTOCOL` al pid de un protocolo de la lista de arriba (salvo Baseline) y vuelve a ejecutar el bloque.

Engine responde así (recortado); el bloque solo se queda con `userProtocolId`. El `baselineWarning` es el recordatorio del baseline:

```json
{
  "status": "active",
  "protocol": {
    "name": "Measurement"
  },
  "baselineWarning": {
    "missing": true,
    "expired": false,
    "invalid": false,
    "message": "No baseline found for this user."
  }
}
```

Si Measurement no está en tu lista (tu entorno aún no lo ofrece), este quickstart funciona igual con **cualquier protocolo cuya siguiente posición tenga un solo step** (lo compruebas en el paso 4), salvo Baseline, en el que no se inscribe a nadie (ver [Baseline](/docs/es/concepts/baseline/)): envía la muestra como ese step. Si la mecánica tiene varios steps, la sesión sigue abierta hasta que **cada** step recibe sus propios lotes y su propio `Final` (`step: N`); los steps que declaran `media` esperan el `mediaId` que mostraste.

#### 4. Busca la posición que hay que capturar

```bash
PM=$(curl -s "$ENGINE/user-protocols/$UP" -H "Authorization: Bearer $TOKEN" \
  | jq -r .nextProtocolMechanic.protocolMechanicId)

curl -s "$ENGINE/user-protocols/$UP/mechanics/$PM" \
  -H "Authorization: Bearer $TOKEN" | jq '.mechanic.steps'
```

La muestra cubre **un** step, así que comprueba que la posición tiene exactamente uno:

```json at="mechanic.steps"
[
  {
    "order": 1,
    "type": "measurement_free",
    "minTimeSeconds": 6
  }
]
```

#### 5. Envía la captura

En producción, Capture produce estos frames en el navegador. Aquí envías una muestra: descarga [la captura de ejemplo](/docs/samples/sample-capture.json) (unos 3 MB) en la carpeta donde ejecutas estos comandos. Es **sintética**: una malla facial genérica, no es la cara de nadie, así que sus indicadores no describen a nadie. Contiene diez lotes de 30 frames del step 1, numerados del 1 al 10, y el último lleva `Final`.

```bash
# The last batch is the Final. Engine aggregates the step when the Final arrives,
# so give the previous batch a few seconds to be processed.
LAST=$(jq 'length' sample-capture.json); i=0
jq -c '.[]' sample-capture.json | while read -r packet; do
  i=$((i + 1)); [ "$i" -eq "$LAST" ] && sleep 3
  echo "$packet" | jq --arg up "$UP" --arg pm "$PM" '. + {userProtocolId:$up, protocolMechanicId:$pm}' \
  | curl -s -X POST "$ENGINE/process-kpn-emo" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-
  echo
done
```

Cada lote responde `202`. Envía los diez en orden, con una pausa breve antes del `Final`: un hueco o un `Final` que falta dejan el step abierto.

```json
{
  "code": 202,
  "message": "KPN-EMO enqueued successfully, processing...",
  "status": "accepted",
  "framesReceived": 30,
  "framesWithoutFeaturesMeta": 0,
  "framesWithoutMediaTime": 30,
  "step": 1
}
```

#### 6. Lee los resultados

Los resultados están listos cuando la sesión se completa (unos segundos con esta muestra). Hasta entonces la respuesta viene vacía, así que consulta en bucle, durante tres minutos como mucho:

```bash
for _ in $(seq 1 60); do
  curl -s "$ENGINE/results/$UP/$PM" -H "Authorization: Bearer $TOKEN" \
    | jq -e '(.rawResults["1"] // {}) | del(.stepType) | length > 0' >/dev/null 2>&1 && break
  sleep 3
done
curl -s "$ENGINE/results/$UP/$PM" -H "Authorization: Bearer $TOKEN" | jq '{aggResults}'
```

Respuesta esperada, recortada a cuatro indicadores (la real trae muchas más señales):

```json
{
  "aggResults": {
    "1": {
      "mean": {
        "valence": 6.751,
        "arousal": 69.775,
        "Confusion": 14.618,
        "Stress_intens": 54.195
      }
    }
  }
}
```

`rawResults` trae los mismos indicadores para cada frame.

#### 7. Opcional: una interpretación

Measurement devuelve indicadores, no una interpretación: pedir `POST /analyze` sobre una captura de Measurement devuelve `409` (`PROTOCOL_NOT_ANALYSED`), porque Measurement nunca se interpreta. Una interpretación necesita un protocolo de un contexto con taxonomía: envías su taxonomía con `POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context` antes de los frames, y pones `triggerAnalysis: true` en el lote `Final` o llamas a `POST /analyze` después. Las [vías de integración](/docs/es/start/paths/) y la guía de tu contexto lo cuentan.

#### 8. Limpia

Cada ejecución deja en tu organización una persona, su inscripción y sus resultados. Bórralos al terminar: `DELETE /users/{externalId}` elimina a la persona y todos sus datos (capturas, sesiones, inscripciones, baseline y consentimientos). Es irreversible y el cuerpo debe repetir el `externalId` en `confirm`.

```bash
curl -s -X DELETE "$ENGINE/users/$EXT" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"confirm\":\"$EXT\"}"
```

Respuesta esperada (los recuentos dependen de lo que capturaste):

```json
{
  "deleted": "quickstart-1767225600",
  "counts": {
    "frames": 120,
    "sessions": 1,
    "userProtocols": 1,
    "subjectStates": 1,
    "consents": 1,
    "thresholds": 0,
    "policies": 0
  }
}
```

Para medir a la misma persona otra vez, no la crees de nuevo: un `POST /users` con el mismo `externalId` responde `409`. Conserva a la persona y abre una inscripción nueva con `POST /user-protocols` (una posición se captura una vez, así que una medición nueva necesita una inscripción nueva). Una credencial `read_all` solo puede borrar a las personas que creó.

### Python

Este código corre en tu servidor: la API key nunca llega al navegador. Necesita Python 3.8+ y `requests` (`pip install requests`), elegido frente a `urllib` de la biblioteca estándar porque envía JSON y cabeceras en una sola llamada. Los siete bloques son un solo script, `quickstart.py`, que se ejecuta en la carpeta donde descargas [la captura de ejemplo](/docs/samples/sample-capture.json):

```bash
ENGINE_BASE="<engine base URL>" ENGINE_API_KEY="<your-api-key>" python quickstart.py
```

#### 1. Pide un token

```python
import json, os, sys, time
import requests

# La URL de Engine de tu entorno está en tu kit (ENGINE_BASE: la pestaña cURL la llama $ENGINE). La API key, solo en tu servidor.
ENGINE = os.environ["ENGINE_BASE"]
API_KEY = os.environ["ENGINE_API_KEY"]

r = requests.post(f"{ENGINE}/token", json={"apiKey": API_KEY})
r.raise_for_status()
token = r.json()["token"]
auth = {"Authorization": f"Bearer {token}"}
```

La respuesta es la misma que en la pestaña cURL: `token` y `expiresIn` (segundos).

#### 2. Crea un usuario

Usa un id opaco (`externalId`), nunca un email ni un nombre. Cada ejecución crea una persona nueva: `ext` lleva la hora, así que repetir el script crea otra. El paso 7 la borra.

```python
ext = f"quickstart-{int(time.time())}"
r = requests.post(f"{ENGINE}/users", headers=auth, json={"externalId": ext, "name": "quickstart-user"})
r.raise_for_status()
print(r.status_code, r.json())
```

#### 3. Mira qué puede usar tu organización e inscribe al usuario

El catálogo es el de tu organización, como en la pestaña cURL. Si Measurement no está, pon en `PROTOCOL` el pid de un protocolo cuya siguiente posición tenga un solo step (nunca Baseline).

```python
# El catálogo de tu organización. Measurement por defecto; para usar otro protocolo, pon su pid en PROTOCOL.
protocols = requests.get(f"{ENGINE}/catalog/protocols", headers=auth).json()
for p in protocols:
    print(p["pid"], p["name"], p["status"])
protocol = os.environ.get("PROTOCOL") or next(
    (p["pid"] for p in protocols if p["name"] == "Measurement" and p["status"] == "published"), None
)
if not protocol:
    sys.exit("Your environment does not offer the Measurement protocol yet. Set PROTOCOL to a pid from the list above (except Baseline).")
r = requests.post(f"{ENGINE}/user-protocols", headers=auth, json={"user": ext, "protocol": protocol})
r.raise_for_status()
up = r.json()["userProtocolId"]
```

#### 4. Busca la posición que vas a capturar

La muestra cubre un step, así que el script comprueba que la posición tenga exactamente uno.

```python
pm = requests.get(f"{ENGINE}/user-protocols/{up}", headers=auth).json()["nextProtocolMechanic"]["protocolMechanicId"]
steps = requests.get(f"{ENGINE}/user-protocols/{up}/mechanics/{pm}", headers=auth).json()["mechanic"]["steps"]
if len(steps) != 1:
    sys.exit(f"This position has {len(steps)} steps and the sample covers one: use a position with a single step.")
```

#### 5. Envía la captura

Diez lotes en orden, con una pausa breve antes del `Final`: cada uno responde `202`.

```python
# La captura de ejemplo, descargada junto a este script: diez lotes del step 1, el último Final.
with open("sample-capture.json") as f:
    packets = json.load(f)
for i, packet in enumerate(packets):
    if i == len(packets) - 1:
        time.sleep(3)  # Engine agrega el step cuando llega el Final: dale unos segundos al lote anterior
    r = requests.post(f"{ENGINE}/process-kpn-emo", headers=auth, json={**packet, "userProtocolId": up, "protocolMechanicId": pm})
    r.raise_for_status()
    print(r.status_code, r.json()["framesReceived"])
```

#### 6. Lee los resultados

```python
# Listos cuando la sesión se completa; hasta entonces la respuesta está vacía, así que sondea hasta tres minutos.
for _ in range(60):
    results = requests.get(f"{ENGINE}/results/{up}/{pm}", headers=auth).json()
    step1 = (results.get("rawResults") or {}).get("1") or {}
    if any(k != "stepType" for k in step1):
        break
    time.sleep(3)
print(json.dumps({"aggResults": results.get("aggResults")}, indent=2))
```

La respuesta es la misma que en la pestaña cURL: `aggResults` por step, y `rawResults` con los mismos indicadores para cada frame. Measurement no se interpreta: para una interpretación, mira el paso 7 de la pestaña cURL.

#### 7. Limpia

Borra a la persona y todos sus datos (irreversible; `confirm` repite el `externalId`).

```python
# Limpia: borra a la persona y todos sus datos (irreversible; "confirm" repite el externalId).
r = requests.delete(f"{ENGINE}/users/{ext}", headers=auth, json={"confirm": ext})
r.raise_for_status()
print(r.status_code, r.json()["counts"])
```

Para medir a la misma persona otra vez, no llames a `POST /users` por segunda vez con el mismo `externalId` (responde `409`): conserva a la persona y abre una inscripción nueva con `POST /user-protocols`.

## Qué puede salir mal

Algunos fallos responden con un error; otros responden `2xx` y solo se notan después.

- Un error de la cámara o del vídeo en la página: `classifyMediaError` dice su causa. `insecure-context`: no estás en HTTPS ni en `localhost`. `denied`: se denegó el permiso de la cámara. `no-device` o `in-use`: no hay cámara, u otra aplicación la tiene. `no-frames` (`CaptureStartError`): la cámara se abrió pero no dio ningún frame útil, o tu vídeo estaba en pausa o ya había terminado.
- `E_RESULTS_TIMEOUT`: no es una pérdida; lee los resultados más tarde con el mismo par (ver [Los resultados en tu backend](/docs/es/sdk/results-backend/)).
- Un `403` desde `/engine/…`: el `ownsAll` del proxy rechazó un id que no es de esta persona.

| Qué ves | Por qué |
| --- | --- |
| `npm install` responde `401`/`404` para `@neurologyca/…` | Falta `NODE_AUTH_TOKEN` en esta terminal o es incorrecto ([Instalación](/docs/es/start/install/)) |
| La captura se para en el modelo de la cara (`CaptureStartError`, `stage: 'face-model'`) | Tu red bloquea cdn.jsdelivr.net o storage.googleapis.com: permítelos o aloja tú los modelos ([Cargar los modelos](/docs/es/guides/load-models/)) |
| `401` con el cuerpo vacío (y `WWW-Authenticate: Bearer`) | Falta el token o ha caducado. Pide otro con `POST /token` |
| `401 { "code": 401, "message": "Invalid credentials." }` en `/token` | La API key es incorrecta, está revocada o ha caducado, o tu organización está suspendida (la misma respuesta en todos los casos) |
| `404 { "code": 404, "message": "Not found." }` | Un id que no existe o no es tuyo; Engine no dice cuál de las dos |
| `409 POSITION_ALREADY_COMPLETED` | Esa posición ya tiene una captura completada. Para medir otra vez, vuelve a inscribir |
| `202` con `framesWithoutFeaturesMeta` mayor que 0 | Los frames sin `featuresMeta` no dan valence ni arousal |
| `202` con `framesWithoutMediaTime` igual al total del lote | Normal si no envías `mediaTimeMs` (dónde estaba un reproductor de estímulo, opcional por frame). Es información, no un error |
| `202` en todos los lotes, pero los resultados siguen vacíos | Un hueco en la numeración de los lotes, un `Final` que falta o una mecánica con más steps de los que enviaste |

Más en [Límites declarados](/docs/es/concepts/limits/).

## Siguiente

[Vías de integración](/docs/es/start/paths/): Qué vía de integración elegir y dónde se procesa, con las cifras medidas.

[En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

[Solo medir](/docs/es/guides/measurement/)

[Los resultados en tu backend](/docs/es/sdk/results-backend/)
