Integraciones con Web Services (API)
Una Integración es la "llave" que le entregas a un sistema externo (una página web, una app móvil propia, un middleware, una integración con otro software) para que pueda comunicarse con tu empresa a través del API de AdmCloud. Cada integración tiene su propio identificador (appid), que se envía junto con las credenciales del usuario en cada llamada, de forma que puedas identificar y controlar quién está llamando al API y con qué nivel de acceso.
¿Qué es y para qué sirve?
AdmCloud expone un API REST con el que un sistema externo puede leer y crear información de tu empresa (clientes, artículos, facturas, cuentas, sucursales y muchos otros objetos) sin usar la pantalla web. Para llamar a ese API, cada solicitud debe incluir un appid válido: el identificador de una Integración creada aquí. Así, cada sistema o proyecto que se conecte a tu empresa queda identificado, puede desactivarse de forma independiente si deja de usarse, y puede limitarse a los permisos del usuario real que hace la llamada en vez de tener acceso total.
Crear una Integración no sustituye al usuario y contraseña con el que se autentica la llamada: el appid viaja junto con las credenciales del usuario (usando el estándar Basic Authentication), no en lugar de ellas.
Cómo se usa
- Entra a Integraciones con Web Services y pulsa Nueva Integración.
- Escribe un Nombre descriptivo que identifique al sistema o proyecto que va a usar esta integración (por ejemplo, el nombre de tu página web o de la integración con otro sistema).
- Decide si la integración debe Ejecutar como Administrador (ver más abajo) y agrega cualquier Nota que te ayude a recordar para qué se usa.
- Guarda la integración. AdmCloud le asigna un ID de Integración (un identificador único) que no puede cambiarse después.
- Entra al detalle de la integración recién creada para copiar su ID y ver, ya armados, los ejemplos de URL que puedes usar para llamar al API de cada módulo (Clientes, Proveedores, Artículos, Cuentas, Facturas, Órdenes de Compra, Depósitos, Asientos Contables, etc.).
- En tu sistema externo, configura las llamadas al API usando esas URL de ejemplo como base, autenticándote con Basic Authentication y pasando el appid de la integración y el nombre de tu base de datos (company) como parámetros.
- Consulta la documentación técnica completa (Swagger), el video explicativo, el código de ejemplo en C# y el Explorador de API desde el aviso informativo al inicio del listado, para conocer todos los objetos disponibles y sus parámetros.
Campos clave
| Campo | Para qué se usa |
|---|---|
| Nombre | Identifica la integración en el listado. Debe ser único: no puedes repetir el nombre de una integración ya existente. |
| Deshabilitada | Si la activas, cualquier llamada al API que use el appid de esta integración deja de funcionar de inmediato, sin necesidad de eliminarla. Útil para suspender temporalmente una conexión sospechosa o que ya no usas. |
| Ejecutar como Administrador | Si está activo (es el valor por defecto), las llamadas que usen esta integración se ejecutan con acceso total, sin validar los permisos del usuario que se autenticó. Si lo desactivas, la llamada respeta los permisos reales del usuario y su grupo de seguridad, igual que si hubiera iniciado sesión en la pantalla web. |
| Notas | Texto libre para documentar, por ejemplo, quién solicitó la integración o para qué sistema se usa. Solo lo ven los usuarios internos. |
| ID de Integración | Identificador único (appid) que AdmCloud genera al guardar. Se usa como parámetro en cada llamada al API para identificar esta integración. |
| Nombre de Base de Datos | El identificador de tu empresa (company) que también debes enviar en cada llamada al API, junto con el appid. |
Validaciones al guardar
- El Nombre es obligatorio y debe ser único; si ya existe una integración con el mismo nombre, AdmCloud rechaza el guardado.
- El ID de Integración (appid) lo asigna AdmCloud automáticamente al crearla y no se puede editar.
- Una integración con llamadas activas registradas no impide guardarla; sin embargo, si intentas eliminar una integración que ya tiene historial u otros registros vinculados, AdmCloud bloqueará el borrado para no perder esa trazabilidad.
- Al llamar al API con un appid que no existe, o que corresponde a una integración marcada como Deshabilitada, la llamada se rechaza.
Disponibilidad
- Requiere el permiso de Personalización en tu grupo de usuarios para ver, crear, editar o eliminar Integraciones.
- En el plan Enterprise, la disponibilidad del API no depende de que actives o desactives otros módulos: está incluida en la edición.
Consejos y errores comunes
Crea una integración por sistema, no una sola para todo. Si conectas varios sistemas externos (por ejemplo, tu página web y, por separado, una integración con otro software), crea una Integración distinta para cada uno. Así puedes desactivar o dar seguimiento a cada conexión de forma independiente sin afectar a las demás.
Usa "Ejecutar como Administrador" con cuidado. Al estar activo, cualquier llamada que use ese appid tiene acceso total sin pasar por los permisos del usuario, incluso si ese usuario normalmente tendría acceso limitado. Desactívalo cuando quieras que la integración respete exactamente los mismos permisos que el usuario tendría dentro de la aplicación.
No encuentro el botón de Nueva Integración o la pantalla no está disponible. Revisa que tu plan incluya el API (Basic o superior) y que tu usuario tenga el permiso de Personalización asignado.