Guía completa: Usar el Web API

¿Qué es el Web API y para qué sirve?

El Web API de AdmCloud es un API REST que expone, sobre HTTPS y en formato JSON, casi todo lo que puedes hacer desde la pantalla web: consultar y crear clientes, proveedores, artículos, cuentas contables, facturas, cotizaciones, pedidos, órdenes de compra, recepciones, depósitos, asientos contables, nómina y mucho más. Así, un sistema externo puede leer y registrar información en tu empresa sin que una persona tenga que entrar a la aplicación.

La dirección base del API en producción es https://api.admcloud.net/api/, y cada objeto tiene su propia ruta. Por ejemplo, listar clientes es:

GET https://api.admcloud.net/api/Customers?skip=0&company=MiEmpresaDB&role=Administradores&appid=00000000-0000-0000-0000-000000000000

Antes de empezar: lo que necesitas a mano

• Un plan que incluya el API: Basic o superior (no está disponible en Billing ni Start).
• El permiso de Personalización en tu grupo de usuarios, para poder crear la Integración.
• Un usuario y contraseña reales de AdmCloud: el API no tiene "llaves" independientes; siempre se autentica como un usuario de la empresa.
• El nombre de la base de datos de tu empresa (el parámetro company). Lo ves en la pantalla de Integraciones con Web Services, en el campo Nombre de Base de Datos.
• El nombre del grupo de usuarios con el que se ejecutarán las llamadas (el parámetro role; por ejemplo Administradores).
• El ID de la Integración (el parámetro appid), que obtienes en el paso 1.

Paso 1: crear la Integración que autoriza el uso del API

Antes de la primera llamada hay que autorizar en el sistema al programa que va a consumir el API. Eso se hace creando una Integración: AdmCloud le asigna un identificador único (el appid) que viaja en cada llamada, de modo que cada sistema conectado quede identificado y puedas desactivarlo de forma independiente cuando quieras.

1. Entra a Integraciones con Web Services (menú de Personalización / Administración del Sistema) y pulsa Nueva Integración.
2. Escribe un Nombre descriptivo que identifique al sistema que la va a usar (por ejemplo, "Página web de pedidos" o "Integración con el punto de venta de la sucursal"). El nombre es obligatorio y no puede repetirse.
3. Decide si la integración debe Ejecutar como Administrador (ver la advertencia más abajo) y agrega en Notas para qué se usa y quién la solicitó.
4. Guarda. AdmCloud genera el ID de Integración (el appid), que ya no se puede cambiar.
5. Entra al detalle de la integración recién creada. Ahí encuentras el appid, el nombre de la base de datos y una lista de URL de ejemplo ya armadas para los objetos más usados (Clientes, Proveedores, Artículos, Cuentas, Facturas, Órdenes de Compra, Depósitos, Asientos Contables, etc.). Es la forma más rápida de probar: copias una URL y la abres en el navegador.

Paso 2: autenticación básica (la forma más simple)

La Autenticación básica (Basic Authentication, el estándar de HTTP) es la manera más directa de llamar al API: en cada llamada envías el correo y la contraseña del usuario en el encabezado Authorization, y los datos de contexto (empresa, grupo e integración) como parámetros de la dirección.

• Encabezado: Authorization: Basic <correo:contraseña en Base64>. Casi todas las herramientas y librerías lo arman por ti: solo escribes usuario y contraseña.
• Parámetro company: el nombre de la base de datos de la empresa. Es lo que le dice al API en qué empresa trabajar.
• Parámetro role: el nombre del grupo de usuarios con el que se ejecuta la llamada (o roleid si prefieres enviar su identificador).
• Parámetro appid: el ID de la Integración creada en el paso 1.

Una llamada completa se ve así:

GET https://api.admcloud.net/api/Customers?skip=0&company=MiEmpresaDB&role=Administradores&appid=8f3c1e42-...-9b21
Authorization: Basic dXN1YXJpb0BlbXByZXNhLmNvbTpNaUNsYXZl

Al recibir la llamada, AdmCloud valida en este orden:

1. Que el correo y la contraseña sean correctos y la cuenta no esté bloqueada.
2. Que ese usuario exista en la empresa indicada en company.
3. Que el grupo de usuarios indicado en role (o roleid) esté realmente asignado a ese usuario.
4. Que la Integración del appid exista y no esté marcada como Deshabilitada.
5. Que el usuario tenga el privilegio necesario para la operación... salvo que la integración esté marcada como Ejecutar como Administrador, en cuyo caso este paso se omite.

Paso 3: autenticación con token

La alternativa es autenticarse una vez y luego usar un token. El token es una cadena firmada que ya lleva dentro el contexto de la sesión (usuario, empresa, grupo, sucursal y ubicación), así que en las llamadas siguientes no vuelves a enviar la contraseña: basta el parámetro token. Es la opción recomendada cuando tu sistema hace muchas llamadas seguidas o cuando no quieres que la contraseña viaje en cada solicitud.

1. (Opcional) Averigua las empresas del usuario. Llama con Autenticación básica y sin el parámetro company a POST /api/Login/GetCompanies. Devuelve las empresas del usuario, ordenadas por su último inicio de sesión, con su identificador y el nombre de su base de datos.
2. Averigua el identificador del grupo de usuarios (RoleID). Puedes obtenerlo llamando a POST /api/Login/SelectCompany?CompanyID=..., que devuelve los grupos disponibles del usuario en esa empresa; o tomarlo del identificador que aparece en la dirección al abrir el grupo en Grupos de Usuarios dentro de la aplicación.
3. Genera el token con Autenticación básica:

   POST https://api.admcloud.net/api/Token?Company=MiEmpresaDB&RoleID=1c9a...&appid=8f3c1e42-...-9b21
   Authorization: Basic dXN1YXJpb0BlbXByZXNhLmNvbTpNaUNsYXZl

   La respuesta trae el token en el campo data.
4. Usa el token en las demás llamadas, como parámetro token y sin encabezado de autenticación:

   GET https://api.admcloud.net/api/Customers?skip=0&token=eyJhbGciOi...

Paso 4: hacer la primera llamada con Swagger u otra herramienta

No necesitas escribir código para probar el API. La forma recomendada es Swagger, la documentación interactiva que además ejecuta las llamadas:

1. Abre https://api.admcloud.net/ApiDocumentation/ (dentro de la aplicación, el mismo enlace está en el aviso informativo de la pantalla de Integraciones).
2. Arriba encontrarás un selector de módulos. Como el API expone cerca de mil operaciones, la documentación está dividida en un documento por módulo (General, Accounts Payable, Accounts Receivable, Banking, General Ledger, Inventory, Payroll, Point of Sale, System Administration, etc.). Elige el módulo del objeto que buscas.
3. Despliega la operación que quieres probar (por ejemplo GET /api/Customers) y pulsa Try it out.
4. Llena los parámetros: skip en 0, company con el nombre de tu base de datos, role con el nombre de tu grupo de usuarios y appid con el ID de la integración. Ejecuta.
5. La primera vez el navegador te pedirá usuario y contraseña (es el cuadro estándar de Autenticación básica que aparece al recibir el 401). Escribe tu correo y contraseña de AdmCloud; el navegador los reutilizará en las llamadas siguientes.
6. Revisa el cuerpo de la respuesta. Si success es true, ya estás consumiendo el API correctamente.

Otras herramientas igual de válidas:

• El navegador, sin más: copia una de las URL de ejemplo del detalle de tu Integración y ábrela. El navegador pedirá usuario y contraseña y te mostrará el JSON.
• El Explorador de API (apiexplorer.admcloud.net): una interfaz propia para explorar los objetos disponibles y sus parámetros.
• Postman, Insomnia o similares: crea la solicitud, en la pestaña de autorización elige Basic Auth y escribe tu correo y contraseña; agrega company, role y appid como parámetros de consulta.
• curl, desde una terminal (ver el ejemplo más abajo).

Paso 5: ejemplo sencillo de código

Los tres ejemplos hacen lo mismo: listar los primeros clientes con Autenticación básica. Cambia el correo, la contraseña, el nombre de la base de datos, el grupo y el appid por los tuyos.

curl

curl -u "usuario@empresa.com:MiClave" \
  "https://api.admcloud.net/api/Customers?skip=0&company=MiEmpresaDB&role=Administradores&appid=8f3c1e42-...-9b21"

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string EMAIL = "usuario@empresa.com";
        const string PASSWORD = "MiClave";
        const string COMPANY = "MiEmpresaDB";
        const string ROLE = "Administradores";
        const string APPID = "8f3c1e42-...-9b21";

        using (var client = new HttpClient())
        {
            var credentials = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(EMAIL + ":" + PASSWORD));

            client.DefaultRequestHeaders.Authorization =
                new AuthenticationHeaderValue("Basic", credentials);

            var url = "https://api.admcloud.net/api/Customers"
                + "?skip=0"
                + "&company=" + COMPANY
                + "&role=" + ROLE
                + "&appid=" + APPID;

            var response = await client.GetAsync(url);
            var json = await response.Content.ReadAsStringAsync();

            Console.WriteLine(json);
        }
    }
}

JavaScript

const EMAIL = "usuario@empresa.com";
const PASSWORD = "MiClave";
const COMPANY = "MiEmpresaDB";
const ROLE = "Administradores";
const APPID = "8f3c1e42-...-9b21";

const url = "https://api.admcloud.net/api/Customers"
    + "?skip=0&company=" + COMPANY + "&role=" + ROLE + "&appid=" + APPID;

const response = await fetch(url, {
    method: "GET",
    headers: {
        "Authorization": "Basic " + btoa(EMAIL + ":" + PASSWORD)
    }
});

const result = await response.json();

if (result.success) {
    console.log(result.data);
} else {
    console.error(result.message);
}

Crear un registro es igual de sencillo: se usa POST a la misma ruta, con el objeto en el cuerpo de la solicitud en JSON. La respuesta trae en data el identificador del registro creado:

curl -u "usuario@empresa.com:MiClave" \
  -H "Content-Type: application/json" \
  -d '{ "Name": "Cliente de prueba", "Customer": true }' \
  "https://api.admcloud.net/api/Customers?company=MiEmpresaDB&role=Administradores&appid=8f3c1e42-...-9b21"

Cómo leer la respuesta y paginar

Todas las operaciones responden con la misma estructura:

{
    "success": true,
    "message": null,
    "data": [ ... ]
}

Los listados están paginados: devuelven como máximo 50 registros por llamada. Para recorrer todo, ve aumentando el parámetro skip (0, 50, 100, ...) hasta que una llamada devuelva un listado vacío.

Dónde está la documentación del API

Todos estos recursos están enlazados en el aviso informativo de la pantalla de Integraciones con Web Services y también en el detalle de cada integración:

Buenas prácticas de seguridad

• Usa un usuario dedicado para el API, no la cuenta personal de una persona. Al crear el usuario puedes marcarlo como Solo para API: así no puede iniciar sesión en la aplicación web ni le caducará la contraseña, lo que evita que una integración deje de funcionar de un día para otro.
• Dale a ese usuario un grupo con los permisos mínimos necesarios y desactiva Ejecutar como Administrador en la integración, para que el API no pueda hacer más de lo que ese grupo permite.
• Una integración por sistema conectado, con notas que expliquen su propósito.
• Deshabilita la integración en cuanto un sistema deje de usarse o notes actividad extraña; es inmediato y reversible, y conserva el historial.
• Guarda las credenciales del lado del servidor, nunca en código que se descargue al navegador del usuario final.
• Llama siempre por HTTPS a las direcciones publicadas del API.

Consejos y errores comunes