NODRANetwork
Documentación · EN
Volver a Integraciones del Panel Partner

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 rutaPermiso requerido
POST /v1/human-signal/reviewsreviews:create
GET /v1/human-signal/reviews/{reviewId}reviews:read
POST /v1/human-signal/reviews/{reviewId}/signalssignals:create
GET /v1/human-signal/reviews/{reviewId}/consensusconsensus:read
POST /v1/human-signal/reviews/{reviewId}/cancelreviews: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.