1. Autenticación B2B (API Key)

Obtener una API Key

Opción dashboard (recomendada): inicie sesión en /dashboard → sección API Keys — Integradores B2B. La clave completa solo se muestra una vez al crearla.

Opción CLI:

python scripts/create_api_key.py --name "Partner Sandbox" --scopes integrate,audit:read --env sandbox

Formato de la key: hx_sandbox_<32 caracteres> o hx_live_... en producción.

Enviar la key en cada petición

Use uno de estos métodos en el header HTTP (o en el handshake WebSocket):

Authorization: Bearer hx_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: hx_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

El scope integrate implica acceso de auditoría. admin implica todos los scopes.

Cuándo se exige API Key

2. Variables y configuración

Variables del servidor (operador)

Variables Postman (colección)

Variables cliente Node.js

3. Flujo de integración recomendado

Resumen visual (producción — WebSocket en vivo)

Enrolamiento vs verificación

3.1 ¿Qué es el challenge (PAD-02)?

En cada sesión biométrica el servidor genera un reto de voz aleatorio. El usuario debe decir la frase indicada en el micrófono. Esto reduce replay de audio grabado y ataques con WAV estático.

En WebSocket (flujo productivo y único de biometría): el cliente muestra la frase, el usuario habla en vivo y se envía challenge_id en ClientHello y end_of_stream. El cliente gestiona la temporización del reto automáticamente; no hace falta calcular t0/t1 manualmente. La verificación y el enrolamiento de voz se realizan exclusivamente por esta vía (Ruta A).

// Respuesta típica POST /api/session/init
{
  "session_id": "a1b2c3d4-...",
  "app_session_token": "...",
  "expires_at": 1730000000,
  "challenge": {
    "challenge_id": "ch_abc123",
    "challenge_type": "text",
    "value": "Di: 7 4 2"
  }
}

3.2 Consumo paso a paso (sin perderse)

Siga este orden. Cada paso indica método, headers, cuerpo y qué guardar para el siguiente.

Glosario rápido de variables

Ruta A — Flujo productivo (cliente Node + WebSocket)

Authorization: Bearer {{api_key}}
X-API-Key: {{api_key}}

{
  "status": "ok",
  "name": "Partner Sandbox",
  "scopes": ["integrate", "audit:read"],
  "environment": "sandbox"
}

Content-Type: application/json
Authorization: Bearer {{api_key}}

{
  "captcha_token": "mock-token",
  "flow": "verify",
  "device_info": {
    "hw_id": "mi-voz-001",
    "model": "MiApp",
    "os": "windows",
    "app_version": "1.0.0"
  }
}

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "app_session_token": "token-url-safe...",
  "expires_at": 1730003600,
  "challenge": {
    "challenge_id": "ch_abc123",
    "challenge_type": "text",
    "value": "Di: 7 4 2"
  }
}

Authorization: Bearer {{api_key}}
Content-Type: multipart/form-data

{ "status": "ok", "message": "Ambiente registrado" }

Authorization: Bearer {{api_key}}
X-API-Key: {{api_key}}

Content-Type: application/json
Authorization: Bearer {{api_key}}

{
  "session_id": "{{session_id}}"
}

{ "status": "confirmed", "subject_id": "uuid-del-sujeto" }

Authorization: Bearer {{api_key}}

{
  "items": [
    {
      "session_id": "{{session_id}}",
      "decision": "ALLOW",
      "reason_code": null,
      "endpoint": "/api/ws/stream",
      "success": true
    }
  ],
  "total": 1
}

Ruta B — Integración REST con Postman

{ "status": "ok" }

X-API-Key: {{api_key}}

{
  "status": "ok",
  "name": "Partner Sandbox",
  "scopes": ["integrate"]
}

Content-Type: application/json
Authorization: Bearer {{api_key}}

{
  "captcha_token": "mock-token",
  "flow": "verify",
  "device_info": {
    "hw_id": "postman-demo-hw-001",
    "model": "Postman",
    "os": "integration-test"
  }
}

{
  "captcha_token": "mock-token",
  "flow": "enrollment",
  "device_info": {
    "hw_id": "postman-demo-hw-001",
    "model": "Postman",
    "os": "integration-test"
  }
}

{
  "session_id": "...",
  "challenge": {
    "challenge_id": "...",
    "value": "Di: 3 8 1"
  }
}

Authorization: Bearer {{api_key}}
Content-Type: multipart/form-data

{ "status": "ok" }

{
  "deviceId": "postman-mic-01",
  "label": "Postman integration"
}

{
  "session_id": "{{session_id}}"
}

{
  "error_code": "WS_HANDSHAKE_FAILED",
  "error_phase": "streaming",
  "message": "Ejemplo integrador Postman",
  "session_id": "{{session_id}}",
  "hw_id": "postman-demo-hw-001",
  "device_model": "Postman",
  "os": "integration-test",
  "app_version": "postman-1.0"
}

4. Guía Postman

Importar la colección

1. Descargue la colección con el botón siguiente.
2. En Postman → Import → Upload Files → seleccione el archivo JSON descargado.
3. Abra la colección → pestaña Variables → configure base_url y api_key → Save.

Variables de colección (detalle)

Orden de ejecución en Postman

Recorra las carpetas en este orden la primera vez. Los pasos detallados con headers, cuerpos y respuestas están en la Ruta B (§3.2). Para biometría productiva use la Ruta A.

OpenAPI: en Postman puede importar como enlace {{base_url}}/openapi.json (sustituya {{base_url}} por la URL de su entorno). La UI Swagger en /docs puede verse en blanco por políticas de seguridad; use esta guía o la colección descargable.

5. Cliente de referencia Node.js

Cliente de demostración para audio en vivo por WebSocket: captura de micrófono real, prefonación, cuenta atrás y envío de tramas forenses. Incluye flujos enroll y verify.

Requisitos

• Node.js 18+
• Micrófono
• PortAudio en el sistema (para naudiodon)
• API Key sandbox y API en marcha

Instalación tras descargar

cd hearthingx-node-live-stream
npm install

naudiodon está en optionalDependencies: npm install ya lo intenta instalar. Si el micrófono falla, compruebe con npm ls naudiodon o ejecute npm install naudiodon para ver el error de compilación (p. ej. falta PortAudio en Windows).

Selección de micrófono (--device-id opcional)

Para listar dispositivos disponibles (comando local, no requiere API Key):

node src\index.js list-devices

Ejemplo con micrófono concreto (opcional):

node src\index.js verify ^
  --base-url http://localhost:8000 ^
  --api-key hx_sandbox_SU_KEY ^
  --hw-id mi-voz-001 ^
  --device-id 2

--hw-id = identidad biométrica en HearthingX (obligatorio y estable entre enroll/verify).
--device-id = hardware de captura PortAudio (opcional; default predeterminado del SO).
En Windows también puede fijar el predeterminado en Configuración → Sonido → Entrada y omitir --device-id.

Parámetros del cliente (referencia)

Ejecución paso a paso

1. npm install en la carpeta del cliente descargado.
2. Opcional: node src\index.js list-devices si necesita un micrófono distinto al predeterminado.
3. Primera vez — enrollment: node src\index.js enroll --base-url ... --api-key ... --hw-id mi-voz-001
4. Siguientes veces — verify con el mismo --hw-id.
5. El cliente valida health → session/init → muestra challenge → ambiente → WebSocket → auditoría.

# 1. Enrolar (primera vez) — sin --device-id (micrófono predeterminado)
node src\index.js enroll ^
  --base-url http://localhost:8000 ^
  --api-key hx_sandbox_SU_KEY ^
  --hw-id mi-voz-001 ^
  --duration 10 --countdown 5

# 2. Verificar (mismo hw-id)
node src\index.js verify ^
  --base-url http://localhost:8000 ^
  --api-key hx_sandbox_SU_KEY ^
  --hw-id mi-voz-001 ^
  --duration 10 --countdown 5

6. Endpoints — Health (públicos)

{ "status": "ok" }

{
  "status": "ok",
  "pad_model_loaded": true,
  "engine_status": "ready",
  "last_inference_latency_ms": 42.5
}

7. Endpoints — Sesión

{
  "captcha_token": "mock-token",
  "flow": "verify",
  "device_info": {
    "hw_id": "partner-hw-001",
    "model": "Postman",
    "os": "integration-test"
  }
}

{
  "session_id": "a24d601c-e4bc-45f2-8e84-311f0a56c231",
  "app_session_token": "urlsafe-token...",
  "expires_at": 1730000000,
  "challenge": {
    "challenge_id": "uuid",
    "challenge_type": "phoneme",
    "value": "Mi voz es mi firma de identidad"
  }
}

8. Endpoints — Ambiente (S1)

9. Endpoints — Challenge

{
  "challenge_id": "uuid",
  "challenge_type": "phoneme",
  "value": "Di: uno dos tres"
}

10. Endpoint — Confirmación de enrolamiento

{ "session_id": "uuid-de-la-sesion" }

11. Endpoints — Dispositivo

{ "deviceId": "mic-partner-01", "label": "Micrófono integración" }

12. Endpoints — Métricas

13. Partner API v1 — Health

{
  "success": true,
  "client_id": "0316453b-32d7-469f-9f8c-be0f5777a87e",
  "name": "Partner Sandbox",
  "environment": "sandbox",
  "scopes": ["audit:read", "integrate"]
}

14. Partner API v1 — Auditoría

Todos requieren scope audit:read (o integrate / admin).

Campos relevantes en auth-logs

15. Partner API v1 — Administración de keys

Scope admin requerido. Uso interno / operadores.

16. WebSocket — Protocolo de streaming

Mensajes JSON del protocolo

Servidor → Cliente: ACK (conexión)

{ "type": "ACK", "status": "ready", "session_id": "uuid" }

Cliente → Servidor: ClientHello

{
  "type": "ClientHello",
  "device_info": { "hw_id": "partner-hw-001", "model": "MyApp", "os": "android" },
  "client_nonce": "550e8400-e29b-41d4-a716-446655440000",
  "geohash_init": "dr5reg000",
  "timestamp_start": 1730000000000,
  "gps_available": false,
  "audio_layout": "block",
  "client_version": "sdk-1.0.0",
  "challenge_id": "uuid-del-challenge"
}

Servidor → Cliente: ACK (handshake OK)

{
  "type": "ACK",
  "status": "ok",
  "server_nonce": "base64-16-bytes",
  "server_recv_ms": 1730000000000,
  "server_send_ms": 1730000000001
}

Cliente → Servidor: end_of_stream

{
  "type": "end_of_stream",
  "timestamp_end": 1730000005000,
  "total_frames": 42,
  "geohash_final": "dr5reg000",
  "challenge_id": "uuid"
}

Servidor → Cliente: final_result (veredicto contractual)

{
  "type": "final_result",
  "contractual_verdict": true,
  "decision": "ALLOW",
  "decision_layer": "sovereign",
  "result": "PASS",
  "message": "Identidad verificada",
  "reason_code": null,
  "jwt_token": "eyJ...",
  "subject_id": "uuid",
  "pad_status": "LIVE",
  "chain_hash": "...",
  "jitter_class": "LOW"
}

Otros mensajes WS

17. Formato de trama binaria (audio forense)

Cada trama se envía como mensaje binario por WebSocket, típicamente cada 250 ms.

Layout PCM (audio_layout)

Tamaño esperado por trama: 16 000 bytes PCM (8 000 muestras × 2 ramas × 2 bytes) a 16 kHz. Con un solo micrófono, duplique la misma señal en A y B.

// Pseudocódigo construcción de trama
buffer.writeUInt32BE(sequence, 0);
buffer.writeBigUInt64BE(BigInt(timestamp_ms), 4);
buffer.write(geohash.padEnd(9, '\0'), 12, 'ascii');
buffer.write(pcm_int16_le_dual_block, 21);

18. Códigos de error frecuentes

Autenticación HTTP

Sesión y ambiente

WebSocket y streaming

Enrollment

19. Checklist de certificación integrador

• API Key sandbox recibida y probada en GET /api/v1/health
• POST /api/session/init con hw_id estable
• POST /api/environment sin voz humana (~300–800 ms)
• WebSocket: ACK ready → ClientHello → ACK ok
• Tramas binarias con secuencia 0,1,2… y intervalo ~250 ms
• Prefonación: silencio real del micrófono (no ceros sintéticos)
• end_of_stream enviado al terminar captura
• final_result recibido con decision
• [Enrollment] POST /api/enroll/confirm tras ALLOW
• GET /api/v1/audit/auth-logs?session_id=... muestra el intento
• Entendido: WAV estático REST ≠ producto de voz viva en producción

20. Seguridad y buenas prácticas

• No incluya API Keys en repositorios, URLs ni logs de cliente.
• Use wss:// y TLS en producción.
• Rote keys periódicamente con DELETE /api/v1/admin/api-keys/{client_id}.
• Configure HEARTHINGX_REQUIRE_API_KEY=1 en entornos expuestos.
• El pipeline PAD, Punto Cero e identidad no se desactiva por tener API Key.
• Mantenga hw_id estable por usuario/dispositivo; no genere uno nuevo en cada verify.

HearthingX API — Documentación de consumo para integradores B2B. Generado para partners sandbox y producción.