Integración de Alegra con WhatsApp y agentes de IA, a medida

Qué puede hacer el agente de IA conectado a Alegra

La API de Alegra expone los mismos recursos que usas en la aplicación. Con ellos, el agente puede:

• Buscar un producto por nombre o referencia en los ítems (recurso items, parámetro query) y responder con su precio, la cantidad disponible (availableQuantity) y las bodegas asociadas.
• Dar el precio de la lista que le corresponde al cliente, porque cada ítem trae sus listas de precios (priceList).
• Buscar al cliente por nombre o número de identificación en los contactos (contacts) y crearlo si no existe.
• Crear una cotización (estimates) con los ítems y cantidades acordados en el chat. Alegra exige cliente, ítems, fecha y fecha de vencimiento, y permite enviarla por correo.
• Consultar las facturas de venta (invoices) de un cliente por su identificación y su estado, por ejemplo las que siguen abiertas.
• Guardar en el CRM de SoyAgentia el número de la cotización creada en Alegra, para que tu equipo la encuentre desde la conversación.

Cómo se conecta: la API REST de Alegra

Alegra publica una API basada en REST que recibe y devuelve JSON, solo por HTTPS, en https://api.alegra.com/api/v1. Usa los métodos GET, POST, PUT y PATCH. La autenticación es Basic Access: en el encabezado Authorization van el correo y el token del usuario, separados por dos puntos y codificados en base64. El token se genera en Alegra, en Configuración, dentro de «API - Integraciones con otros sistemas». Si las credenciales fallan, la API responde 401. El detalle está en la autenticación de Alegra.

El límite actual es de 150 peticiones por minuto por usuario. Si se supera, la API responde 429 y hay que esperar a que termine el minuto. Cada respuesta trae las cabeceras X-Rate-Limit-Remaining y X-Rate-Limit-Reset para saber cuánto margen queda (límite de request). Por eso el conector pide a Alegra solo lo necesario en cada conversación. Como Alegra funciona en la nube, no hace falta VPN ni abrir puertos en tu red.

Alegra maneja catálogos de parámetros por país en su API (Colombia, Costa Rica, España, México y Panamá). Los campos de una cotización o una factura cambian según el país de tu cuenta, y el conector se arma con los de la tuya. La referencia general está en la información general de la API.

Lo que necesitas tener en Alegra

Antes de empezar, revisa estos puntos en tu cuenta:

• Un plan de Alegra que incluya «Integración con otras aplicaciones». Según los términos de Alegra, el uso de la API no tiene costo adicional al valor de ese plan.
• Un usuario dedicado a la integración, con los permisos mínimos que tu cuenta permita, para que el correo y el token que usa el agente no sean los de una persona de tu equipo.
• Una forma de probar sin tocar tu operación. Alegra no documenta un sandbox aparte y advierte que las peticiones cambian datos reales, así que acordamos una cuenta de prueba o empezar solo con consultas y cotizaciones.
• Ítems con precio, listas de precios y bodegas al día, porque el agente responde con lo que esté en Alegra.
• La numeración de documentos que usará el agente, ya configurada.

Cómo trabajamos la integración a medida

El proyecto sigue cinco pasos:

• Diagnóstico: definimos qué consulta el agente en Alegra (ítems, precios, existencias, facturas), qué registra (contactos y cotizaciones) y en qué canales.
• Acceso: tu equipo crea el usuario de integración, genera su token en «API - Integraciones con otros sistemas» y nos lo comparte por un canal seguro.
• Desarrollo: construimos el conector y las reglas del agente: qué lista de precios usa, de qué bodegas informa, cuándo crea una cotización y cuándo pasa la conversación a una persona.
• Pruebas: validamos con conversaciones reales en la cuenta de prueba acordada, revisando que las cotizaciones queden como las crea tu equipo y que el consumo quede lejos del límite por minuto.
• Puesta en marcha: activamos el agente con tu cuenta de Alegra en producción, empezando por WhatsApp, y revisamos contigo las primeras cotizaciones.

Límites y decisiones de diseño

Para que no haya sorpresas:

• No es un conector listo: se desarrolla para tu cuenta de Alegra y se cotiza aparte del plan del agente. SoyAgentia no es partner de Alegra.
• La API no busca contactos por teléfono, solo por nombre o identificación. Por eso el agente pide la cédula o el NIT cuando necesita encontrar al cliente.
• La API permite emitir la factura electrónica desde una integración (en Colombia, con el objeto stamp), pero si la emisión falla Alegra deja la factura en borrador y responde con error 400. Solo lo incluimos si tu proceso lo permite; la opción más simple es que el agente cree la cotización y tu equipo facture.
• El agente no registra pagos, notas crédito ni comprobantes contables, salvo que se defina expresamente en el alcance.
• Alegra es una marca de Soluciones Alegra S.A.S. SoyAgentia no está afiliada a Soluciones Alegra S.A.S.

Integraciones disponibles

• Alegra (API REST de Alegra)
• WhatsApp Business API (Cloud API)
• Instagram, Messenger, TikTok, WordPress y Shopify, según el alcance

Sigue leyendo

• Integraciones con ERP a medida
• Todas las integraciones
• Agentes de IA para WhatsApp
• Integración nativa de Siigo con WhatsApp
• Cotizar una integración a medida

Preguntas frecuentes