Beta privada · apertura 23 de diciembre
Inicio rápido
En esta guía usas el sandbox (https://api-sandbox.opennexum.com) con una clave onx_test_…. Consultas un RUC, el tipo de cambio y tu saldo. No necesitas certificado ni usuario SOL.
1. Guarda tu clave
Sección titulada «1. Guarda tu clave»Una clave de prueba empieza con onx_test_. Guárdala en una variable de entorno; no la escribas en el código ni la pegues en un chat.
export ONX_CLAVE="onx_test_…"2. Consulta un RUC
Sección titulada «2. Consulta un RUC»GET /v1/ruc/{ruc} devuelve los datos públicos del padrón reducido de SUNAT. Pide el permiso datos:leer.
curl "https://api-sandbox.opennexum.com/v1/ruc/20000000001" \ -H "Authorization: Bearer $ONX_CLAVE"Ejemplo ilustrativo de la respuesta:
{ "ruc": "20000000001", "razon_social": "EMPRESA DE EJEMPLO S.A.C.", "estado": "ACTIVO", "condicion": "HABIDO", "ubigeo": "150101", "direccion": "AV. EJEMPLO 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "LIMA", "padron_actualizado_al": "2026-11-14"}Validamos el dígito verificador: un RUC mal escrito responde validacion y uno que no existe, no_encontrado. Todos los campos están en la referencia de ruc_consultar.
3. Consulta el tipo de cambio
Sección titulada «3. Consulta el tipo de cambio»GET /v1/tipo-cambio devuelve el tipo de cambio oficial del BCRP. Si no envías fecha, usa hoy en Lima.
curl "https://api-sandbox.opennexum.com/v1/tipo-cambio?fecha=2026-11-15" \ -H "Authorization: Bearer $ONX_CLAVE"Ejemplo ilustrativo:
{ "fecha": "2026-11-15", "publicado_el": "2026-11-13", "moneda": "USD", "compra": "3.748", "venta": "3.752", "fuente": "BCRP"}En feriados y fines de semana, publicado_el es la última publicación anterior. Los valores son texto con tres decimales: no los conviertas a número flotante para sumar dinero.
4. Mira tu saldo
Sección titulada «4. Mira tu saldo»curl "https://api-sandbox.opennexum.com/v1/cuenta/saldo" \ -H "Authorization: Bearer $ONX_CLAVE"Las consultas de datos son lecturas medidas: cuentan contra tu cupo gratis o tu saldo. Los precios están por confirmar. Si te quedas sin saldo, la API responde saldo_insuficiente; mira Saldo y error 402.
Qué sigue
Sección titulada «Qué sigue»- Autenticación: permisos, topes y alcance por RUC.
- Idempotencia: obligatoria en todo lo que cobra.
- Nexum Comprobantes: emite tu primera boleta en SUNAT beta.
- Para agentes de IA: cómo conectar a Claude Code, Codex u otro agente.