¿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:

• ID del Cliente (Client ID) → Un código numérico único que identifica a la aplicación.

• Clave Secreta (Secret Key) → Una contraseña cifrada que, junto con el ID, permite a la aplicación autenticarse ante la API.

• Token Fijo (opcional) → Un código de acceso permanente con vigencia de 10 años, ideal para integraciones que requieren acceso continuo sin necesidad de renovar credenciales periódicamente.

🔹 ¿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 Arrendasoft"

Dentro de la pantalla de Configuraciones, busca la tarjeta llamada "API Arrendasoft". Su descripción dice: "Controle la información de las Integraciones con Arrendasoft."

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, qué es una API y un enlace a la documentación técnica.

• Panel derecho ("Clientes OAuth2") → Lista de todos los clientes OAuth2 creados actualmente, mostrando sus credenciales y permisos.

• Botones superiores → "Crear Cliente" para agregar uno nuevo y "Volver" para regresar a Configuraciones.

Si desea conocer en detalle los servicios disponibles en la API y cómo utilizarlos, consulte la guía API Arrendasoft 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 "Crear/Editar 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.

• 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 Accesos (Permisos)

En el campo "Accesos", selecciona los permisos que la aplicación tendrá al consumir la API. Este es un campo de selección múltiple donde puedes elegir una o varias opciones:

Para seleccionar varios permisos, haz clic en cada opción que desees agregar. Las opciones seleccionadas aparecerán como etiquetas dentro del campo.

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.

• 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. Decidir si necesitas un Token Fijo

El campo "¿Token Fijo?" es un interruptor que te permite generar un token de acceso permanente junto con el cliente.

Recomendación: Usa "NO" (sin token fijo) siempre que sea posible. Los tokens temporales son más seguros porque expiran automáticamente. Solo activa el Token Fijo si la aplicación realmente lo necesita.

💾 Paso 6. 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 ID, la Clave Secreta y, si lo solicitaste, el Token Fijo.

• La ventana del formulario se cerrará y la pantalla principal se actualizará mostrando el nuevo cliente con sus credenciales.

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 (Nombre o Descripción), el sistema te indicará cuál campo necesitas completar.

Después de crear el cliente, en el panel de "Clientes OAuth2" aparecerá una tarjeta con toda la información del nuevo cliente. A continuación te explicamos cada dato:

📋 Datos del Cliente

• Nombre → El nombre que asignaste al crear el cliente. Aparece como título de la tarjeta.

• ID → El identificador único del cliente. Es un código numérico generado automáticamente. Este valor se usa como "usuario" al autenticarse en la API.

• Secret_Key → La clave secreta cifrada del cliente. Este valor se usa como "contraseña" al autenticarse en la API.

• Token (solo si solicitaste Token Fijo) → El token de acceso permanente. Puede usarse directamente en las solicitudes a la API sin necesidad de autenticarse cada vez. Los tokens fijos se identifican por un sufijo especial.

• Scope → Los permisos asignados al cliente, separados por comas. Ejemplo: read,create,update,delete.

• Descripción → La descripción que escribiste al crear el cliente.

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

La aplicación externa debe usar las credenciales del cliente para obtener un token de acceso. Existen dos formas de hacerlo:

Opción A: Autenticación con ID y Clave Secreta (recomendado)

1. La aplicación envía una solicitud al servicio de autenticación de la API con el ID (como usuario) y la Secret_Key (como contraseña).

2. La API valida las credenciales y devuelve un token temporal (JWT) con una duración limitada.

3. La aplicación usa ese token en las siguientes solicitudes a la API incluyéndolo en la cabecera de autorización.

4. Cuando el token expire, la aplicación debe solicitar uno nuevo repitiendo el paso 1.

Opción B: Uso directo del Token Fijo

Si creaste el cliente con la opción de Token Fijo, la aplicación puede usar directamente este token en todas las solicitudes sin necesidad de autenticarse previamente. Este token tiene una vigencia de 10 años.

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 Arrendasoft V2

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

✏️ Actualizar un Cliente

1. Ubica el cliente que deseas modificar en la lista.

2. Haz clic en el botón "Actualizar" del cliente.

3. Se abrirá el formulario con los datos actuales del cliente.

4. Puedes modificar el Nombre, los Accesos y la Descripción.

5. Haz clic en "Actualizar Cliente" para guardar los cambios.

Nota: El ID y la Clave Secreta no se modifican al actualizar. Si necesitas regenerar la clave secreta, puedes hacerlo desde el botón de generación de nueva contraseña si está disponible en la tarjeta del cliente.

🗑️ Eliminar un Cliente

1. Ubica el cliente que deseas eliminar en la lista.

2. Haz clic en el botón "Eliminar" 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 este flujo:

🔹 Flujo con Token Temporal (recomendado)

1. Solicitar acceso → La aplicación envía el ID (como usuario) y la Secret_Key (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.

🔹 Flujo con Token Fijo

1. Obtener el token → Copia el Token Fijo que aparece en la tarjeta del cliente en el módulo de API.

2. Usar directamente → La aplicación incluye este token en la cabecera de autorización (Authorization: Bearer [token]) en cada solicitud.

3. No requiere renovación frecuente → El Token Fijo tiene una vigencia de 10 años.

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

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 Arrendasoft 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 accesos (permisos) de un cliente existente haciendo clic en el botón "Actualizar" 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 (ID, Clave Secreta).

• Se eliminan todos los tokens de acceso asociados (temporales y fijos).

• Cualquier aplicación que usara esas credenciales perderá el acceso inmediatamente.

¿Puedo regenerar la Clave Secreta sin eliminar el cliente?

Sí. Si la tarjeta del cliente muestra un botón para generar nueva contraseña, puedes usarlo para regenerar la Clave Secreta sin afectar el ID ni los demás datos del cliente. Recuerda que la aplicación que use esas credenciales deberá actualizarse con la nueva clave.

¿Qué diferencia hay entre un Token Temporal y un Token Fijo?

¿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 ID y la Clave Secreta (o el Token Fijo).

¿Las credenciales cambian si actualizo el cliente?

No. Al actualizar un cliente (nombre, descripción o permisos), el ID y la Clave Secreta 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 Arrendasoft.

2. Haz clic en "Crear Cliente".

3. Escribe un Nombre descriptivo y único para el cliente.

4. Selecciona los Accesos (permisos) que la aplicación necesita.

5. Escribe una Descripción del propósito del cliente.

6. Decide si necesitas un Token Fijo (solo si es realmente necesario).

7. Haz clic en "Crear Cliente" → Se generan las credenciales automáticamente.

8. Copia las credenciales (ID, Secret_Key y Token si aplica) y proporciónalas a la aplicación que consumirá la API.

🔹 Reglas clave: