Adm Cloud permite integrar tu sistema con aplicaciones externas mediante Web Services, facilitando el intercambio de información y la automatización de procesos.
A través de estas integraciones puedes consultar, crear y actualizar datos dentro del sistema de forma controlada y segura.
Índice
Cómo crear una integración con Web Services
¿Qué es un API en Adm Cloud?
¿Cómo funciona una API en Adm Cloud?
Flujo de una solicitud
Documentación en Swagger
Logueo / Autenticación / Token
Autenticación básica
Autenticación por Token (recomendada)
Tipos de respuestas / Manejo de errores básico
¿Qué son los códigos de estado HTTP?
Códigos más comunes
Buenas prácticas para el manejo de errores
Cómo crear una integración con Web Services
Para acceder a esta funcionalidad, dirígete a Configuración > Personalización > Integraciones con Web Services. Desde esta sección podrás visualizar el listado de integraciones existentes junto con su descripción.
Para crear o editar una integración, sigue estos pasos:
- Haz clic en Editar para modificar una integración existente o en Nueva para crear una nueva.
- Completa la información del formulario:
🔹Descripción: nombre que identificará la integración.
🔹Observaciones: información adicional sobre su uso o propósito.
🔹Deshabilitada: actívala si no deseas que la integración esté disponible temporalmente.
🔹Ejecutar como Administradores: desmárcala si los usuarios que utilizarán la integración no pertenecen al grupo de administradores. - Haz clic en Grabar para guardar los cambios.
| 💡 Importante: Una vez configures una integración, podrás utilizar el API de Adm Cloud para conectar aplicaciones externas y automatizar el intercambio de información con el sistema. |
¿Qué es un API en Adm Cloud?
Un API (Interfaz de Programación de Aplicaciones) es un conjunto de servicios que permite la comunicación entre diferentes sistemas.
En Adm Cloud, el API está disponible a través de Web Services, los cuales puedes consumir desde aplicaciones externas para interactuar con la información del sistema.
Esto te permite:
🔹Consultar información en tiempo real
🔹Registrar transacciones automáticamente
🔹Integrar procesos entre plataformas
¿Cómo funciona una API en Adm Cloud?
El funcionamiento de una API sigue este flujo básico:
Esto significa que tu aplicación envía una solicitud, el sistema la procesa y luego devuelve una respuesta.
Flujo de una solicitud
1. Realizas una solicitud (request) que incluye:🔹Una dirección (endpoint)
🔹Un método (GET, POST, entre otros)
🔹Credenciales o datos requeridos
Ejemplo:GET https://api.admcloud.net/api/Customers
|
💡Métodos más comunes: ■ GET: obtener información |
2. La API valida la solicitud:
🔹Verifica permisos
🔹Revisa que la información esté correctamente estructurada
🔹Si hay un problema, devuelve un error
3. El servidor procesa la solicitud:
🔹Consulta la base de datos o ejecuta lógica interna
🔹Ejemplo: buscar clientes
Documentación en Swagger
Adm Cloud dispone de documentación en Swagger para facilitar el uso de sus Web Services.
Desde esta herramienta puedes:
🔹Consultar los endpoints disponibles: haciendo clic sobre los nombres del listado llegarás a a la lista de endpoints en donde podrás identificar [ Método / API ]
🔹Ver la estructura de cada servicio: haciendo clic al nombre del endpoint podrás conocer los parámetros necesarios para la llamada.
🔹Probar solicitudes directamente
🔹Revisar ejemplos de request y response
Esto te permite validar tus integraciones antes de implementarlas en tu sistema.
Logueo / Autenticación / Token
Para consumir los Web Services, primero debes autenticarte en el sistema.
El API de Adm Cloud soporta dos formas de autenticación:
🔹Autenticación Básica
🔹Autenticación por Token (recomendada)
Autenticación básica
La autenticación básica consiste en utilizar los valores de Company, Role y AppID para iniciar sesión en el API de Adm Cloud y poder consumir sus servicios.
Sigue estos pasos:
- Abre el endpoint de Login.
- Completa los siguientes datos:
■ Company: corresponde al ID de la empresa configurada en la integración creada previamente.
■ AppID: corresponde al ID de la integración creada previamente.
■ Role: es el ID del rol de usuario que tienes asignado. Para obtenerlo, dirígete a Configuracion > Seguridad > Grupos de Usuarios, abre tu grupo de usuario y copia el nombre que tiene asignado. - Haz clic en el botón Try it out!
- El sistema mostrará un mensaje emergente para que ingreses tus credenciales de usuario de Adm Cloud.
- Si el proceso es exitoso, verás una respuesta con el resultado de la autenticación.
- En caso de error, Swagger te solicitará nuevamente ingresar las credenciales indicadas en el paso 4.
Autenticación por Token (recomendada)
Este método consiste en utilizar tu Token o clave digital para identificarte y darte acceso a un sistema o API, permitiéndote:
🔹Mayor seguridad en las integraciones
🔹Evitar el envío constante de usuario y contraseña
🔹Controlar el acceso de forma más eficiente
Sigue estos pasos:
- Abre el endpoint de Login.
- Completa los siguientes datos:
■ Company: corresponde al ID de la empresa configurada en la integración creada previamente.
■ AppID: corresponde al ID de la integración creada previamente.
■ Role: es la descripción del rol de usuario que tienes asignado. Para obtenerlo, dirígete a Configuracion > Seguridad > Grupos de Usuarios, consulta tu grupo de usuario y copia el nombre que tiene asignado.
■ Role ID: es el ID del rol de usuario que tienes asignado. Para obtenerlo, consulta tu grupo de usuario y copia el Guid. - Haz clic en el botón Try it out!
- El sistema mostrará un mensaje emergente para que ingreses tus credenciales de usuario de Adm Cloud.
- Si el proceso es exitoso, verás una respuesta con el resultado de la autenticación con el token generado.
- En caso de error, Swagger te solicitará nuevamente ingresar las credenciales indicadas en el paso 4.
Tipos de respuestas / Manejo de errores básico
Cada solicitud realizada al API genera una respuesta del sistema en formato JSON indicando el resultado de la operación.
Estas respuestas pueden ser:
🔹Exitosas: cuando la operación se ejecuta correctamente
🔹Con errores: cuando existe un problema en la solicitud o en los datos enviados
💡Cuando una solicitud es exitosa, la API devuelve un código de estado 200 OK junto con los datos.
|
📝 Ejemplos de respuesta exitosa:
📝 Ejemplo de respuesta exitosa en la llamada en Swagger del endpoint de login:
|
¿Qué son los códigos de estado HTTP?
Son códigos numéricos que indican el resultado de la solicitud.
Códigos más comunes
✅ 200 – OK ➜ La solicitud fue exitosa.
🆕 201 – Created ➜ El recurso fue creado correctamente.
⚠️ 400 – Bad Request ➜ La solicitud está mal formada (datos incorrectos o incompletos).
🔐 401 – Unauthorized ➜ No tienes permisos o falta autenticación.
🚫 403 – Forbidden ➜ Tienes credenciales, pero no acceso a ese recurso.
🔍 404 – Not Found ➜ El recurso no existe.
💥 500 – Internal Server Error ➜ Error en el servidor.
Buenas prácticas para el manejo de errores
-
Verifica siempre el código de estado HTTP de la respuesta
-
Revisa el mensaje de error para entender la causa del problema
-
Valida la información antes de enviar la solicitud
-
Implementa manejo de errores en tu integración, asegurándote de:
■ Revisar las credenciales utilizadas (API key, token o usuario)
■ Verificar que el endpoint y el método (GET, POST, etc.) sean correctos
■ Confirmar que los datos enviados tengan el formato esperado
■ Validar permisos y accesos configurados (IP, roles, entre otros)
Puedes conocer en el siguiente artículo, algunos Ejemplos de consumo de endpoints en Adm Cloud API.