HUMAN SIGNAL / NODRA PROTOCOL
Integrar revisión humana en un agente de IA mediante API
Rutas verificadas de Human Signal, autenticación Partner, consultas de estado y webhooks.
Actualizado · NODRA Network
Un agente, chatbot o copilot interno utiliza el mismo límite de integración: tu backend llama a Human Signal cuando tu política requiere criterio humano. Las credenciales permanecen en el servidor. El Partner gestiona la interfaz de revisión y autoriza a los revisores.
Acceso y autenticación
Solicita a NODRA una URL base aprobada y una credencial Partner. Usa x-nodra-api-key o Authorization: Bearer …. Tenant, Client, entorno y permisos quedan vinculados a la credencial. Una API key no concede acceso al dashboard administrativo. Las credenciales de sandbox y producción son distintas.
Rutas Partner implementadas
| Método y ruta | Permiso requerido |
|---|---|
| POST /v1/human-signal/reviews | reviews:create |
| GET /v1/human-signal/reviews/{reviewId} | reviews:read |
| POST /v1/human-signal/reviews/{reviewId}/signals | signals:create |
| GET /v1/human-signal/reviews/{reviewId}/consensus | consensus:read |
| POST /v1/human-signal/reviews/{reviewId}/cancel | reviews:cancel |
GET /v1/human-signal/account devuelve información de la cuenta autenticada. Disponibilidad y cuotas dependen de la credencial. Esta referencia describe el límite implementado; no ofrece una API pública anónima.
Crear una revisión
Tras aprobarse el acceso, envía una Idempotency-Key única y datos sintéticos como:
{
"provider": "simulated-ai",
"model": "demo-model",
"title": "Revisión de procedimiento",
"purpose": "Comprobar un borrador antes de usarlo",
"aiResponse": "Borrador que requiere contexto humano.",
"language": "es",
"category": "technology"
}
Conserva el identificador devuelto, muestra el caso solo a revisores autorizados y consulta estado y consenso. Gestiona señales insuficientes, cancelación y tiempo de espera. Los umbrales de cierre se acuerdan para el flujo elegido.
Ejemplo ejecutable
Descargar ejemplo Node.js sin dependencias. Por defecto muestra un recorrido sintético; no contacta a NODRA ni genera votos humanos reales.
node human-signal-client.mjs --mock
# Consulta de cuenta de solo lectura tras aprobar el acceso:
NODRA_BASE_URL='https://TU-ENDPOINT-APROBADO' NODRA_API_KEY='TU-CLAVE-DE-SERVIDOR' node human-signal-client.mjs --account
Respuestas y errores
La respuesta contiene ok, data, error y meta. Gestiona credenciales inválidas (401), permisos o acceso (403), casos no disponibles (404), datos inválidos (400), conflictos de idempotencia (409) y límites de tráfico o cuota (429). Respeta la indicación de reintento y aplica esperas limitadas.
Webhooks
Cuando estén habilitados, utiliza HTTPS, verifica la firma acordada y procesa duplicados de forma idempotente. Consulta el estado canónico cuando corresponda. Un webhook no hace instantánea la revisión humana. No publiques credenciales, secretos ni datos privados de casos.