¿Cómo crear un nuevo Cliente OAuth2 en nuby para consumo de la API?

Un Cliente OAuth2 es un registro en nuby que representa a una aplicación o sistema externo que desea acceder a la información de tu inmobiliaria a través de la API. Al crear un cliente, nuby genera automáticamente un par de credenciales de seguridad que esa aplicación necesita para identificarse y obtener autorización de acceso.

🔹 ¿Para qué sirve?

• Conectar sistemas externos → Permite que aplicaciones de terceros (portales web, aplicaciones móviles, sistemas contables, etc.) se comuniquen con nuby de forma segura.
• Controlar el acceso → Puedes definir qué tipo de operaciones puede realizar cada aplicación: solo consultar datos, crear registros, actualizar información o eliminar datos.
• Garantizar la seguridad → Cada aplicación se identifica con credenciales únicas, lo que permite rastrear y auditar quién accede a la información.

🔹 Credenciales generadas automáticamente

Al crear un Cliente OAuth2, nuby genera automáticamente:

• Client ID → Un identificador único que representa a la aplicación. Se usa como “usuario” al autenticarse en la API.
• Client Secret → Una clave secreta cifrada que, junto con el Client ID, permite a la aplicación autenticarse. Solo se muestra una vez en el momento de creación y no puede recuperarse después.

Importante: El Client Secret se muestra únicamente al momento de crear el cliente. Una vez que cierres esa pantalla, el valor no podrá visualizarse de nuevo. Cópialo inmediatamente y guárdalo en un lugar seguro.

🔹 ¿Para quién es útil esta guía?

• Administradores del sistema → Para crear y gestionar las credenciales de acceso a la API.
• Equipos técnicos → Para obtener las credenciales necesarias para desarrollar integraciones con nuby.
• Gerencia → Para comprender cómo funciona el acceso de aplicaciones externas a la información de la inmobiliaria.

Antes de crear un Cliente OAuth2, verifica que cuentas con lo siguiente:

📌 Requisito 1. Permisos de administrador

Necesitas tener permisos de administrador o acceso al módulo de Configuraciones en nuby. Solo los usuarios con el rol adecuado pueden crear, editar o eliminar clientes OAuth2.

Tip: Si no tienes acceso al módulo de Configuraciones, solicita al usuario administrador de tu sistema que te otorgue los permisos necesarios.

📌 Requisito 2. Identificar la aplicación que se conectará

Ten claro qué aplicación o sistema externo utilizará estas credenciales. Esto te ayudará a asignar un nombre descriptivo al cliente y definir los permisos adecuados.

• Ejemplo → “Portal Web Mi Inmobiliaria”, “App Móvil Clientes”, “Sistema Contable XYZ”.

📌 Requisito 3. Definir los permisos necesarios

Determina qué tipo de acceso necesita la aplicación externa:

Recomendación de seguridad: Asigna únicamente los permisos que la aplicación realmente necesita. Si la aplicación solo necesita consultar datos, no le otorgues permisos de crear, actualizar o eliminar. Esto reduce riesgos de seguridad.

🔐 Paso 1. Inicia sesión en nuby

Ingresa a nuby con tu usuario y contraseña habituales.

📂 Paso 2. Dirígete a Configuraciones

1. En el menú principal (barra superior), ubica el ícono de engranaje ⚙️ o busca la opción de “Configuraciones” entre los menús disponibles.
2. Al ingresar, verás una pantalla con múltiples tarjetas de configuración organizadas en categorías.

📌 Paso 3. Selecciona “API nuby”

Dentro de la pantalla de Configuraciones, busca la tarjeta llamada “API nuby”. Haz clic sobre esta tarjeta para ingresar al módulo de gestión de clientes OAuth2.

📄 Paso 4. Visualiza los clientes existentes

Al ingresar al módulo verás:

• Panel lateral izquierdo → Información explicativa sobre qué es un Cliente OAuth2 y qué es una API, más un enlace a la documentación técnica.
• Panel derecho (“Clientes OAuth2”) → Cuadrícula de tarjetas con todos los clientes OAuth2 creados. Cada tarjeta muestra el Client ID (copiable), el Client Secret (siempre enmascarado como ●●●●●●●●), los Permisos como etiquetas de color y el Tipo de Autenticación.
• Botón “Crear Cliente” → Ubicado en la parte superior, abre el formulario de creación.

Si desea conocer en detalle los servicios disponibles en la API y cómo utilizarlos, consulte la guía API nuby V2

A continuación te explicamos cómo crear un nuevo Cliente OAuth2 desde el módulo de API.

📝 Paso 1. Abrir el formulario de creación

Desde la pantalla principal del módulo de API, haz clic en el botón “Crear Cliente” ubicado en la parte superior. Se abrirá una ventana emergente con el formulario “Nuevo Cliente OAuth2”.

✏️ Paso 2. Completar el Nombre del Cliente

En el campo “Nombre del Cliente”, escribe un nombre descriptivo que identifique a la aplicación que usará estas credenciales.

• Campo obligatorio → No se puede crear el cliente sin un nombre.
• Debe ser único → No puede existir otro cliente con el mismo nombre en el sistema.
• Máximo 255 caracteres.
• Ejemplos → “Portal Web Corporativo”, “App Móvil Clientes”, “Integración ERP Contable”.

Importante: Escoge un nombre claro y descriptivo. Esto facilitará identificar a qué aplicación corresponde cada cliente cuando tengas varios registrados.

🔑 Paso 3. Definir los Permisos (Scopes)

En el campo “Permisos (Scopes)”, selecciona los permisos que la aplicación tendrá al consumir la API. Este es un campo de selección múltiple.

Para seleccionar varios permisos, mantén presionada la tecla Ctrl (o Cmd en Mac) mientras haces clic en cada opción que desees.

Atención: Otorga solo los permisos estrictamente necesarios. Si la aplicación solo requiere consultar datos, selecciona únicamente “Consultar”. Esto protege la integridad de tu información.

📄 Paso 4. Escribir la Descripción

En el campo “Descripción”, escribe una descripción clara del propósito de este cliente.

• Campo obligatorio → El sistema requiere una descripción para crear el cliente.
• Máximo 500 caracteres.
• Utilidad → Ayuda a recordar para qué se creó el cliente y quién lo utiliza.
• Ejemplos → “Credenciales API para la integración con el portal web corporativo de la inmobiliaria”, “Acceso API para la aplicación móvil de gestión de propiedades”.

💾 Paso 5. Crear el Cliente

Haz clic en el botón “Crear Cliente”.

Si todo está correcto:

• Se creará el cliente y se generarán automáticamente el Client ID y el Client Secret.
• El formulario mostrará una pantalla de confirmación con las credenciales generadas (ver Paso 6).

Si hay algún error:

• Si el Nombre del Cliente ya existe, el sistema te notificará que el nombre debe ser único.
• Si falta algún campo obligatorio, el sistema te indicará cuál campo necesitas completar.

🔐 Paso 6. Copiar las credenciales (paso crítico)

Inmediatamente después de crear el cliente, la pantalla mostrará una tarjeta titulada “Cliente OAuth2 Creado Exitosamente” con las credenciales generadas. Esta es la única vez en que podrás ver el Client Secret.

• Client ID → El identificador del cliente. Tiene un botón de copia rápida.
• Client Secret → La clave secreta. Aparece resaltada en amarillo con un botón de copia rápida. No se almacena en texto plano y no podrá recuperarse.

¡Copia el Client Secret ahora! Una vez que cierres esta pantalla (al hacer clic en “Entendido, ya copí las credenciales”), el Client Secret no volverá a mostrarse. Si lo pierdes, deberás regenerar una nueva contraseña desde la tarjeta del cliente.

Después de copiar las credenciales, haz clic en “Entendido, ya copí las credenciales” para cerrar la ventana y volver a la lista de clientes.

Al crear un Cliente OAuth2, nuby genera automáticamente dos credenciales que la aplicación externa necesita para autenticarse:

📋 Datos del Cliente

• Nombre → El nombre que asignaste al crear el cliente. Aparece como título de la tarjeta en el listado.
• Client ID → El identificador único del cliente. Es una cadena generada automáticamente. Este valor se usa como “usuario” al autenticarse en la API. Siempre visible en la tarjeta del cliente con un botón de copia.
• Client Secret → La clave secreta del cliente. Se usa como “contraseña” al autenticarse en la API. Solo se muestra una vez, justo después de crear el cliente. En el listado, este valor siempre aparece enmascarado como ●●●●●●●●●●●●.
• Permisos (Scopes) → Los permisos asignados al cliente, mostrados como etiquetas de color en la tarjeta (Ej: read, create, update, delete).
• Tipo de Autenticación → Siempre es client_credentials. Se asigna automáticamente y no es configurable.
• Descripción → La descripción que escribiste al crear el cliente.

El Client Secret solo se muestra una vez. Después de crear el cliente y cerrar la pantalla de confirmación, no podrás ver el Client Secret de nuevo. Si no lo copiaste, deberás usar el botón de regenerar contraseña (ver Sección 6).

🔹 ¿Cómo autenticarse en la API con estas credenciales?

La aplicación externa usa el Client ID y el Client Secret para obtener un token de acceso temporal mediante el flujo OAuth2 Client Credentials:

1. Solicitar acceso → La aplicación envía el Client ID y el Client Secret al servicio de autenticación de la API.
2. Recibir token → La API valida las credenciales y devuelve un token temporal (formato JWT) junto con su fecha de expiración.
3. Usar el token → La aplicación incluye este token en la cabecera de autorización (Authorization: Bearer [token]) en cada solicitud a los servicios de la API.
4. Renovar cuando expire → Cuando el token expire, la aplicación debe repetir el paso 1 para obtener uno nuevo.

Para conocer los detalles técnicos del proceso de autenticación, los servicios disponibles y los formatos de solicitud, consulte la documentación de la API en API nuby V2

Desde el módulo de API puedes gestionar los clientes OAuth2 que ya están creados. Cada tarjeta de cliente cuenta con botones de acción.

✏️ Editar un Cliente

1. Ubica el cliente que deseas modificar en la lista.
2. Haz clic en el botón “Editar” de la tarjeta del cliente.
3. Se abrirá un formulario con los datos actuales del cliente.
4. Puedes modificar el Nombre del Cliente, los Permisos (Scopes) y la Descripción.
5. El Client ID y el Tipo de Autenticación se muestran como información de solo lectura.
6. Haz clic en “Actualizar Cliente” para guardar los cambios.

Nota: El Client ID no se puede modificar. El Client Secret tampoco se muestra en el formulario de edición; si necesitas regenerarlo, usa el botón de regenerar contraseña desde la tarjeta del cliente en el listado.

🔄 Regenerar el Client Secret

Si perdiste el Client Secret o necesitas renovarlo por seguridad, puedes generar uno nuevo sin necesidad de eliminar el cliente:

1. En la tarjeta del cliente (listado principal), ubica el campo “Client Secret” (que siempre aparece enmascarado como ●●●●●●●●).
2. Haz clic en el botón de rotación (icono ↻) ubicado junto al campo enmascarado.
3. Se abrirá una ventana titulada “Nueva Contraseña Generada” mostrando el nuevo Client Secret.
4. Copia el nuevo Client Secret inmediatamente usando el botón de copia. Una vez que cierres esta ventana, no podrás ver el valor nuevamente.
5. Actualiza las credenciales en la aplicación que usaba el cliente.

Importante: Al regenerar el Client Secret, el valor anterior queda inválido inmediatamente. Cualquier aplicación que lo usara deberá actualizarse con el nuevo valor para continuar funcionando.

🗑️ Eliminar un Cliente

1. Ubica el cliente que deseas eliminar en la lista.
2. Haz clic en el botón “Eliminar” de la tarjeta del cliente.
3. El sistema te pedirá confirmación antes de proceder.
4. Al confirmar, el cliente y todos sus tokens de acceso serán eliminados permanentemente.

Atención: Al eliminar un cliente, cualquier aplicación que esté usando sus credenciales perderá el acceso inmediatamente a la API. Asegúrate de que ninguna aplicación activa dependa de ese cliente antes de eliminarlo.

Esta tabla resume todos los campos disponibles en el formulario de creación de un Cliente OAuth2:

Una vez creado el Cliente OAuth2, la aplicación externa puede conectarse a la API de nuby siguiendo el flujo OAuth2 Client Credentials:

🔹 Flujo de autenticación (recomendado)

1. Solicitar acceso → La aplicación envía el Client ID (como usuario) y el Client Secret (como contraseña) al servicio de autenticación de la API.
2. Recibir token → La API valida las credenciales y devuelve un token temporal (formato JWT) junto con su fecha de expiración.
3. Usar el token → La aplicación incluye este token en la cabecera de autorización (Authorization: Bearer [token]) en cada solicitud a los servicios de la API.
4. Renovar cuando expire → Cuando el token expire, la aplicación debe repetir el paso 1 para obtener uno nuevo.

🔹 Seguridad de las credenciales

• Las credenciales del cliente son exclusivas para la aplicación que las utiliza.
• Cada solicitud a la API es validada verificando que el token sea legítimo y no haya expirado.
• Los permisos asignados al cliente determinan qué operaciones puede realizar la aplicación.
• El Client Secret no se almacena en texto plano en nuby. Solo se guarda su hash. Si se pierde, debes regenerarlo.

Para información técnica completa sobre los servicios disponibles en la API (propiedades, contratos, terceros, facturas, contabilidad y más), consulte la documentación en API nuby V2

¿Puedo crear varios Clientes OAuth2?

Sí. Puedes crear tantos clientes como necesites. Cada uno tendrá sus propias credenciales y permisos independientes. Es recomendable crear un cliente diferente para cada aplicación o integración.

¿Puedo modificar los permisos de un cliente ya creado?

Sí. Puedes actualizar los permisos (Scopes) de un cliente existente haciendo clic en el botón “Editar” de la tarjeta del cliente. Los cambios aplican para las nuevas solicitudes que se realicen.

¿Qué pasa si elimino un Cliente OAuth2?

Al eliminar un cliente:

• Se eliminan todas las credenciales (Client ID, Client Secret).
• Se eliminan todos los tokens de acceso asociados.
• Cualquier aplicación que usara esas credenciales perderá el acceso inmediatamente.

¿Puedo ver el Client Secret después de crear el cliente?

No. El Client Secret solo se muestra una vez, justo después de crear el cliente. Después de eso, siempre aparece enmascarado (●●●●●●●●) en el listado y no puede recuperarse. Si lo perdiste, usa el botón de regenerar contraseña (icono ↻) en la tarjeta del cliente.

¿Puedo regenerar el Client Secret sin eliminar el cliente?

Sí. Haz clic en el botón de rotación (↻) en la tarjeta del cliente. Se abrirá una ventana con el nuevo Client Secret. Recuerda copiarlo de inmediato y actualizar las credenciales en la aplicación que las usaba.

¿El nombre del cliente afecta su funcionamiento?

No. El nombre es solo una etiqueta para identificar al cliente. Lo que importa para la autenticación son el Client ID y el Client Secret.

¿Las credenciales cambian si edito el cliente?

No. Al editar un cliente (nombre, descripción o permisos), el Client ID y el Client Secret se mantienen. Solo se modifican los datos que cambies en el formulario.

¿Qué servicios están disponibles en la API?

La API de nuby ofrece servicios para gestionar:

• Autenticación → Obtener tokens de acceso.
• Maestras → Consultar datos base del sistema.
• Propiedades → Gestionar el catálogo de propiedades.
• Asesores → Consultar información de asesores.
• Facturas → Consultar y gestionar facturas.
• Contabilidad → Consultar información contable.
• Contratos → Gestionar contratos de arrendamiento.

Para crear un nuevo Cliente OAuth2 en nuby, sigue estos pasos:

1. Ve a Configuraciones > API nuby.
2. Haz clic en “Crear Cliente”.
3. Escribe un Nombre descriptivo y único para el cliente.
4. Selecciona los Permisos (Scopes) que la aplicación necesita (Ctrl+Clic para seleccionar varios).
5. Escribe una Descripción del propósito del cliente.
6. Haz clic en “Crear Cliente” → Se generan las credenciales automáticamente.
7. Copia el Client ID y el Client Secret inmediatamente. El Client Secret no podrá visualizarse de nuevo después de cerrar esta pantalla.
8. Haz clic en “Entendido, ya copí las credenciales” para finalizar.

🔹 Reglas clave: