Ir al contenido

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.
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.

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
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"
}
}'

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.

Cada código tiene su explicación en Errores.