Zoho multiempresa con Magento: integración bidireccional de inventario y pedidos (caso Águila Azteca)

• En Zoho Books y Zoho Inventory, cada negocio se configura como una organización independiente, con su propio ID, moneda base, zona horaria, contactos y reportes.
• Cada llamada a la API debe llevar el parámetro `organization_id`; el OAuth de Zoho usa tokens de acceso que duran una hora.
• Zoho limita las llamadas a 100 por minuto por organización, y a un tope diario que depende del plan.
• Con varias empresas, la clave no es la API: es definir qué empresa vende, qué empresa surte y quién manda en cada dato.

¿Cómo se conecta Magento con Zoho Inventory o Zoho Books con varias empresas?

Con una integración que habla con la API REST de Magento por un lado y con la API de Zoho por el otro, y que sabe a qué organización de Zoho corresponde cada operación. Según la documentación de Zoho, si tienes varios negocios, cada uno se configura como una organización independiente, con su propio ID, moneda base, zona horaria, contactos y reportes.

Eso tiene una consecuencia práctica: no existe un solo «Zoho» al que Magento le manda todo. Existen N organizaciones, y cada pedido, cada cliente y cada ajuste de inventario tiene que caer en la correcta. Por eso un conector pensado para una sola empresa se queda corto en cuanto aparece la segunda razón social.

Las piezas mínimas son estas:

• API de Magento: pedidos, clientes, productos y existencias (la API REST que documenta Adobe).
• API de Zoho: Zoho Books para contabilidad y facturación; Zoho Inventory para existencias, órdenes de venta y compra.
• Capa de integración: el servicio que mapea datos, aplica reglas por empresa, reintenta cuando algo falla y deja bitácora.

¿Qué cambia entre Zoho Books API y Zoho Inventory API?

Son dos APIs con raíces distintas pero con la misma lógica de organización. La de Books vive en `https://www.zohoapis.com/books/v3` y la de Inventory en `https://www.zohoapis.com/inventory/v1`. Zoho aloja las cuentas en varios centros de datos, así que el dominio cambia (.com, .eu, .in, .com.au, entre otros): hay que usar el que corresponde a tu cuenta.

En ambas, el `organization_id` se manda en cada petición y se obtiene con `GET /organizations` o desde el panel de administración. Si tu operación usa Zoho Inventory para existencias y Zoho Books para facturar, lo normal es que la integración hable con las dos y mantenga la relación entre el pedido de Magento, la orden de venta y la factura.

Un detalle útil de Zoho Books: sus scopes de OAuth están separados por módulo (contactos, facturas, órdenes de venta, pagos recibidos, entre otros). Pide solo los que necesitas, por principio de mínimo privilegio y porque así el permiso queda claro para quien lo autoriza.

¿Cómo se autentica la integración con Zoho?

Con OAuth 2.0. La documentación de Zoho Books describe un flujo con client ID y client secret, un código de autorización de un solo uso, un token de acceso y un token de actualización. El token de acceso dura una hora; el de actualización no caduca hasta que alguien lo revoca.

Para una integración que corre en segundo plano, sin pantalla ni redirección, Zoho contempla el tipo de cliente «Self Client». Aun así, hay reglas que conviene respetar:

• Guarda el token de actualización como secreto en el servidor; nunca en código del navegador ni en un repositorio.
• Reutiliza el token de acceso mientras sea válido. Zoho limita cuántos tokens puedes generar a partir de un token de actualización en una ventana de 10 minutos.
• Si la integración pierde el token (por ejemplo, porque alguien lo revocó o cambió contraseñas), debe avisar y no quedarse reintentando en silencio.

¿Qué límites de API tiene Zoho y cómo afectan a una tienda?

Zoho permite hasta 100 peticiones por minuto por organización, y un máximo diario que depende del plan contratado. Según su documentación, el tope diario va de 1,000 en el plan gratuito a 10,000 en los planes más altos. Si lo superas, la API responde con error 429. También hay un límite de llamadas concurrentes: 5 en el plan gratuito y 10 (límite blando) en los de pago.

Para una tienda con muchos SKUs, esto cambia el diseño:

• Sincroniza deltas, no catálogos completos. Mover solo lo que cambió cuida tu cuota diaria.
• Cuenta las llamadas por organización. Cada empresa tiene su propia cuota; una promoción que dispare pedidos en una no debería agotar a la otra.
• Usa una cola. Si Zoho responde 429, la integración espera y reintenta en vez de perder el pedido.
• Revisa tu plan. Un tope de miles de llamadas al día se acaba rápido con un catálogo grande y pedidos frecuentes.

¿Qué flujos se sincronizan en una integración bidireccional?

Casi siempre cuatro: existencias hacia Magento, pedidos hacia Zoho, clientes en ambos sentidos y estatus de regreso a la tienda. Lo que hace «bidireccional» a la integración es que cada dato tiene una dirección definida, no que todo viaje para los dos lados.

¿Cómo decidir a qué empresa va cada pedido?

Esa regla es el corazón de una integración multiempresa y la define el negocio, no la API. Algunos criterios habituales: por canal de venta (mayoreo o menudeo), por tipo de cliente, por almacén que surte, o por la razón social que factura. Lo importante es que sea explícita y que esté escrita antes de programar.

Dos reglas que ahorran problemas: que cada pedido guarde en Magento a qué organización de Zoho se envió (para poder reintentar o corregir sin duplicar), y que los ajustes manuales de inventario se hagan en un solo sistema. Si se editan en los dos lados, tarde o temprano uno pisa al otro.

El caso de Águila Azteca: Zoho multiempresa que no existía como módulo

Águila Azteca es mayorista y minorista de llantas, con operación B2B y B2C y unos 50,000 SKUs. Venía de un desarrollo a la medida y operaba con Zoho en varias empresas. Para la integración con Magento no había un módulo que cubriera ese esquema, así que construimos la integración bidireccional con Zoho multiempresa.

Lo que nos dejó este proyecto es una regla de trabajo: con un catálogo de ese tamaño, la integración se diseña alrededor de las deltas, las colas y las reglas por empresa, no alrededor de «sincronizar todo». También ayudó que el cliente aceptó revisar su flujo B2B contra las buenas prácticas de la plataforma, en lugar de pedir que Magento copiara el portal anterior.

Errores comunes al integrar Magento con Zoho multiempresa

Estos son los que más se repiten en integraciones con ERP, y en la multiempresa pegan más fuerte:

• Mandar todo a una sola organización. Los pedidos de una empresa terminan facturados por otra, y contabilidad lo descubre al cierre.
• Ignorar el `organization_id`. Un valor por defecto mal puesto manda datos a la organización equivocada.
• Clientes duplicados entre organizaciones. Sin una regla de identificación (correo, RFC o ID externo), cada pedido crea un cliente nuevo.
• Dos sistemas mandando el mismo dato. Existencias o precios que se editan en Magento y en Zoho a la vez.
• Sincronizar el catálogo completo cada vez. Gasta tu cuota diaria, genera timeouts y errores de concurrencia.
• Sin manejo de errores. Sin cola de reintentos, sin bitácora y sin alerta, un día de pedidos se queda en el limbo.

Lo que hemos visto integrando Magento con ERPs

Desde 2011 hemos hecho casi 300 proyectos de ecommerce y hemos integrado Magento con SAP, NetSuite, Zoho, Dynamics, Odoo y desarrollos internos, con y sin documentación de API (los peores son los que no la tienen). El reto mayor casi siempre es el ERP, no Magento.

Los consultores de ERP tienden a adaptar el sistema a la cultura y los procesos del cliente, aunque sean malos. Nuestra postura es aprovechar la integración para llevar al cliente a buenas prácticas, en lugar de pagar siempre la fricción de adaptar la plataforma. Por eso cada proyecto empieza con una auditoría y un mapa de qué dato vive dónde.

Si lo que te interesa es el CRM y no el inventario, lee cómo conectar Magento con Zoho CRM. Para el mismo problema con otros ERPs, mira integrar Magento con Odoo y integrar Magento con NetSuite.

¿Cuándo NO conviene una integración multiempresa a la medida?

No conviene si solo tienes una empresa en Zoho y una operación estándar: ahí probablemente un conector existente cubre lo básico y te sale mejor. Tampoco si vendes pocos pedidos al día o tienes un catálogo de menos de unos 10 productos: capturar a mano puede costar menos que mantener una integración.

Y no conviene integrar un Zoho que todavía está desordenado. Si las existencias, los almacenes o las empresas no cuadran dentro de Zoho, la integración solo va a llevar ese desorden a tu tienda. Primero se ordena el ERP, después se conecta. Y ojo: Magento no hace todo solo; la integración se configura y se prueba.

Hacemos estos proyectos en integraciones de Magento y, si tu tienda corre con Hyvä, en integraciones de Hyvä Commerce. Si quieres saber si tu caso necesita una integración a la medida, agenda un diagnóstico de integración gratis de 30 minutos.

Preguntas frecuentes

¿Existe un módulo para conectar Magento con Zoho Books o Zoho Inventory?

Sí, hay conectores en el mercado. Sirven para operaciones estándar con una sola empresa; si manejas varias organizaciones de Zoho o reglas propias, revisa que cubran tu caso antes de comprarlos.

¿Cómo funciona Zoho con varias empresas?

Según su documentación, cada negocio se configura como una organización independiente, con su propio ID, moneda base, zona horaria, contactos y reportes. Cada petición a la API debe llevar el organization_id correspondiente.

¿Cómo se autentica la API de Zoho Books?

Con OAuth 2.0. El token de acceso es válido por una hora y el token de actualización no caduca hasta que se revoca. Se manda en el encabezado Authorization con el formato Zoho-oauthtoken.

¿Qué límites de API tiene Zoho?

100 peticiones por minuto por organización y un máximo diario según el plan (de 1,000 en el gratuito a 10,000 en los más altos). Al excederlos, la API devuelve el error 429.

¿La integración es en tiempo real?

Depende del flujo. Los pedidos conviene enviarlos casi de inmediato para apartar inventario; las existencias se actualizan con la frecuencia que permita tu cuota de API, siempre por cambios y no por cargas completas.

¿Funciona si mi tienda usa Hyvä?

Sí. La integración trabaja con los datos de Magento, no con el frontend, así que Hyvä no la limita.

Fuentes

• Zoho Books API: introducción (organizaciones, límites de API)
• Zoho Inventory API: introducción (organizaciones, límites de API)
• Zoho Books API: OAuth (tokens, scopes)
• Adobe Commerce: API REST

Transparencia: Panamerik es partner de Cloudways (hosting) y de Hyvä. No obligamos a nadie a usarlos: trabajamos con el hosting y las herramientas que tú prefieras. Los datos de experiencia de este artículo son aproximados y vienen de nuestros proyectos desde 2011.