Beta privada · apertura 23 de diciembre
Crea una clave con tope y permisos
POST /v1/claves
Crea una clave para un agente, nunca con más permisos, RUC, tope o plazo que la clave que la crea. Siempre espera la aprobación de una persona (202). Ya aprobada, repite la petición con la misma Idempotency-Key: la primera respuesta 201 trae secreto; las siguientes responden ya_registrado (el secreto no se guarda). Si la persona la rechaza o la aprobación vence, responde estado_no_permite.
| Dato | Valor |
|---|---|
| Permiso | claves:administrar |
| Cobro | No cobra. |
Idempotency-Key |
Obligatoria |
| Aprobación humana | Siempre: una persona la aprueba en el panel, sin importar la configuración de la clave. |
| Herramienta MCP | No se ofrece a agentes. |
Parámetros
Sección titulada «Parámetros»| Nombre | En | Requerido | Tipo | Descripción |
|---|---|---|---|---|
Idempotency-Key |
header | Sí | string | Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, idempotencia_en_conflicto. Se guarda 24 horas. |
X-Request-Id |
header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. |
application/json, obligatorio. Los campos anidados van con punto y los de listas con []. No se aceptan campos desconocidos.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
nombre |
string | Sí | Para reconocerla, por ejemplo «Agente de facturación». |
permisos |
“datos:leer” | “emisores:administrar” | “comprobantes:emitir” | “comprobantes:leer” | “comprobantes:anular” | “guias:emitir” | “sire:leer” | “conecta:leer” | “conecta:enviar” | “conecta:administrar” | “webhooks:administrar” | “cuenta:leer” | “cuenta:recargar” | “claves:administrar” | “credenciales:por_llamada”[] | Sí | Solo puedes dar permisos que tu propia clave ya tiene. |
emisores |
string[] | No | Limita la clave a estos RUC (dentro del alcance de tu clave); si no lo envías, hereda el de tu clave. |
tope |
object | Sí | No puede superar el tope de la clave que la crea. |
tope.periodo |
“diario” | “semanal” | “mensual” | “total” | Sí | |
tope.limite |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
confirmacion |
object | No | Al menos tan estricta como la de tu clave. Si no la envías, se usa la de tu cuenta (notas, bajas y montos altos). |
confirmacion.notas |
boolean | No | Notas de crédito (07). |
confirmacion.bajas |
boolean | No | Bajas: comunicación de baja (RA) y resumen diario de anulación (RC). |
confirmacion.mensajes |
boolean | No | Envío de mensajes y comprobantes por Conecta. |
confirmacion.agentes |
boolean | No | Toda emisión o baja que pida un agente con un token OAuth o por MCP, sea cual sea su tipo o monto. |
confirmacion.monto_mayor_a |
string | null | No | Comprobantes cuyo total pasa de este monto (por omisión, “5000.00”); null para no pedirla por monto. |
vence_el |
string (date) | No | Día en que deja de funcionar; no puede ser posterior al de tu clave. |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
curl -X POST "https://api-sandbox.opennexum.com/v1/claves" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "nombre": "texto", "permisos": [ "datos:leer" ], "tope": { "periodo": "diario", "limite": "1250.50" }}'Respuestas
Sección titulada «Respuestas»Clave creada; guarda secreto ahora.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
clave |
object | Sí | Clave de API para un agente o sistema. Se guarda solo su hash. |
clave.id |
string | Sí | Identificador que empieza con clv_. |
clave.nombre |
string | Sí | |
clave.prefijo |
string | Sí | Inicio visible de la clave, para reconocerla. La clave completa solo se muestra al crearla. |
clave.entorno |
“live” | “test” | Sí | live en producción; test en sandbox (SUNAT beta). |
clave.permisos |
“datos:leer” | “emisores:administrar” | “comprobantes:emitir” | “comprobantes:leer” | “comprobantes:anular” | “guias:emitir” | “sire:leer” | “conecta:leer” | “conecta:enviar” | “conecta:administrar” | “webhooks:administrar” | “cuenta:leer” | “cuenta:recargar” | “claves:administrar” | “credenciales:por_llamada”[] | Sí | Puede estar vacía (una clave sin permisos solo autentica). |
clave.emisores |
string[] | null | Sí | RUC a los que puede acceder; null = todos los de tu cuenta. |
clave.tope |
object | null | Sí | |
clave.tope.periodo |
“diario” | “semanal” | “mensual” | “total” | Sí | |
clave.tope.limite |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
clave.confirmacion |
object | Sí | Qué operaciones de esta clave esperan la aprobación de una persona en el panel. Por omisión: notas de crédito, bajas, montos mayores a S/ 5,000.00 y todo lo que pida un agente (token OAuth o MCP). |
clave.confirmacion.notas |
boolean | Sí | Notas de crédito (07). |
clave.confirmacion.bajas |
boolean | Sí | Bajas: comunicación de baja (RA) y resumen diario de anulación (RC). |
clave.confirmacion.mensajes |
boolean | Sí | Envío de mensajes y comprobantes por Conecta. |
clave.confirmacion.agentes |
boolean | Sí | Toda emisión o baja que pida un agente con un token OAuth o por MCP, sea cual sea su tipo o monto. |
clave.confirmacion.monto_mayor_a |
string | null | Sí | Comprobantes cuyo total pasa de este monto (por omisión, “5000.00”); null para no pedirla por monto. |
clave.vence_el |
string (date) | null | Sí | |
clave.ultimo_uso_en |
string (date-time) | null | Sí | |
clave.creada_en |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
clave.revocada_en |
string (date-time) | null | Sí | |
secreto |
string | Sí | La clave completa. Se muestra solo esta vez: guárdala en un gestor de secretos. |
Espera la aprobación de una persona.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
estado |
“requiere_confirmacion” | Sí | |
operacion_id |
string | Sí | Úsalo en GET /v1/confirmaciones/{id} para saber si se aprobó. |
confirmacion_url |
string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. |
consulta_url |
string | Sí | Ruta para consultar el estado. |
expira_en |
string (date-time) | Sí | Antes de esta hora hay que aprobarla Y repetir la petición; si no, vence y no se hace. |
mensaje |
string | Sí | Qué falta, en palabras para una persona. |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 403
permiso_faltante - 409
idempotencia_en_conflicto - 409
solicitud_en_curso - 409
ya_registrado - 409
estado_no_permite - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible