Ir al contenido

Beta privada · apertura 23 de diciembre

Para agentes de IA

OpenNexum está hecho para que un agente de IA lo use con seguridad: cada agente tiene su propia clave con tope, el dinero y lo irreversible los decide una persona, y toda la documentación se puede leer en texto plano.

Un agente llama a la API con una clave onx_test_… o onx_live_…, como cualquier cliente. Empieza por Inicio rápido y Autenticación. Dale a cada agente su propia clave, con los permisos mínimos y un tope de gasto.

Recurso Qué es
llms.txt Índice de todo el sitio, con un enlace por página.
llms-full.txt Todo el contenido en un solo archivo de texto.
Versión .md de cada página Añade .md a la dirección: /errores.md, /inicio-rapido.md.
openapi.json El contrato completo de la API (OpenAPI 3.1).

Hay un borrador de skill con cuándo usar OpenNexum, la autenticación, los errores y cómo pedir confirmación humana. Descárgalo a la carpeta de skills de tu agente; en Claude Code:

Ventana de terminal
mkdir -p ~/.claude/skills/opennexum
curl -o ~/.claude/skills/opennexum/SKILL.md https://docs.opennexum.com/skill/opennexum/SKILL.md

Cuando existan, cada herramienta MCP se llamará como el operationId de la referencia: por ejemplo, ruc_consultar o comprobante_emitir. Las rutas que no conviene exponer a un agente (crear claves, guardar credenciales, crear webhooks) no tendrán herramienta.

Lo irreversible o delicado espera a una persona. Según la configuración de la clave, notas, bajas, mensajes y comprobantes desde cierto monto responden 202 con estado: requiere_confirmacion (ejemplo ilustrativo):

{
"estado": "requiere_confirmacion",
"operacion_id": "op_8f2c1a7d9e",
"confirmacion_url": "https://app.opennexum.com/confirmar/op_8f2c1a7d9e",
"consulta_url": "/v1/confirmaciones/op_8f2c1a7d9e",
"expira_en": "2026-11-15T17:30:00-05:00",
"mensaje": "Falta que una persona apruebe esta nota de crédito."
}

Lo que debe hacer el agente:

  1. No repetir la operación ni intentar aprobarla: el «sí» nunca viaja como argumento de la API. Nada se cobró todavía.
  2. Decirle a la persona qué se va a hacer (con el campo mensaje) y pasarle confirmacion_url tal cual.
  3. Consultar confirmacion_ver con el operacion_id hasta que el estado sea ejecutada, rechazada o vencida.
  4. Si se rechazó o venció, no insistir sin que la persona lo pida.

Algunas rutas siempre piden aprobación, sin importar la clave: crear una clave y registrar un webhook.

  • Saldo: ante un 402, el agente le pasa recarga_url a una persona y espera. No recarga ni sube su propio tope.
  • Límites: ante un 429, espera Retry-After.
  • Idempotencia: guarda la Idempotency-Key de cada operación y reutilízala al reintentar. Mira Idempotencia.
  • Secretos: la clave, el certificado y el usuario SOL no se escriben en el chat, en archivos del repositorio ni en registros.
  • Errores: programa contra el codigo, no contra el mensaje. Cada código está en Errores.