Compras / Inventarios Ruka.ai Productivo

Toteat × Ruka.ai — Manual de soporte interno

Documento operativo para el equipo de soporte, implementación y servicio de Toteat. Cubre qué resuelve la integración con Ruka.ai, qué queda fuera, cómo activarla en un cliente nuevo, cómo diagnosticar los fallos más frecuentes y a quién escalar.

Disponible en ✓ Toteat New ✗ Toteat Legacy

Audiencia: Soporte · Implementación · Servicio al cliente Sentido del flujo: Ruka → Toteat Endpoint: POST /purchasemovements Última revisión: Abril 2026

Qué es esta integración

Ruka.ai es una plataforma de gestión de inventario y compras que automatiza la trazabilidad de los productos del restaurante desde la factura del proveedor. Su producto Stock resuelve la captura, validación y control del stock end-to-end del cliente — incluyendo lectura de facturas, conciliación de proveedores y costeo.

La integración con Toteat se da en una dirección puntual: Ruka inyecta las compras procesadas como movimientos de inventario en Toteat. El cliente trabaja sus compras en Ruka (donde tiene la profundidad de gestión que Toteat no entrega), y el resultado — el ingreso de stock — aparece automáticamente en el módulo de Inventario Avanzado de Toteat sin que nadie tenga que volver a digitar.

Origen · Ruka

Gestión de compras + inventario

Ruka procesa las compras del cliente (lectura de facturas, OCR, validación, control de proveedores, alertas) y queda con el documento listo para impactar el stock.

Destino · Toteat

Inventario operativo

Toteat recibe vía API el movimiento de compra y lo registra como ingreso de stock en el módulo de Inventario Avanzado, listo para descontarse al consumirse en venta o producción.

Por qué esto importa al soporte Si un cliente que usa Ruka pregunta "por qué no me aparece esa compra en Toteat", la respuesta corta es: la compra debe procesarse y aprobarse en Ruka primero; al hacerlo, Ruka ejecuta el POST a Toteat y el ingreso aparece en Inventario Avanzado. Si no aparece, el problema está casi siempre del lado de Ruka (compra no aprobada, error en mapeo de SKU, credencial inválida) — antes de mirar Toteat conviene confirmar el estado del documento en Ruka.

Cómo se conectan los sistemas

Es una integración API simple y unidireccional. Ruka es cliente del API público de Toteat y consume el endpoint estándar de movimientos de compra. Toteat no inicia nada — actúa como receptor pasivo.

Fig. 1 — Ruka procesa la compra y la inyecta en Toteat vía POST /purchasemovements. Toteat genera el movimiento de inventario, que junto a la operación interna (ventas, recetas, mermas) construye el stock teórico. Las tomas de inventario en Toteat son las que cierran el círculo comparándolo con el conteo físico real.

Dónde vive cada cosa Ruka aporta el lado de las entradas (compras procesadas y aprobadas). Toteat aporta el lado de las salidas (ventas, recetas, mermas, transferencias) y la verificación (tomas de inventario que comparan teórico vs real). La integración solo conecta el primer pedazo — todo lo demás vive en Toteat y no se sincroniza con Ruka.

Endpoint utilizado

POST https://developers.toteat.com/.../purchasemovements

Documentación oficial: developers.toteat.com — purchasemovements

Lo que SÍ se puede hacer

Capacidades cubiertas hoy. Si un cliente pide algo de esta lista, la respuesta es "sí, esto resuelve la integración con Ruka".

✓

Ingreso automático de stock en Toteat al procesar una compra en Ruka Cada compra aprobada en Ruka dispara un movimiento de inventario en Toteat con sus líneas (ítem, cantidad, costo, bodega).

✓

Trabajar la gestión completa de compras en Ruka Captura de facturas, OCR, conciliación de proveedores, control de costos, alertas, dashboards — todo lo que diferencia a Ruka como producto está disponible para el cliente sin perder la actualización de stock en Toteat.

✓

Eliminar la doble digitación El cliente carga / aprueba la factura en un solo lugar (Ruka). Toteat se entera automáticamente. No hay equipo de operaciones replicando datos en dos sistemas.

✓

Multi-local / multi-bodega Ruka puede dirigir el ingreso a la bodega correcta de Toteat indicando el local en el payload. Cada compra impacta el stock de la sucursal/bodega que corresponde. ⚠ Validar

✓

Detalle de líneas de la compra El movimiento llega a Toteat con cada ítem, cantidad, unidad de medida y costo unitario, no como un total agregado.

✓

Trazabilidad por documento Cada compra de Ruka genera un movimiento identificable en Toteat (por número de documento o referencia externa), útil para auditoría y conciliación.

Lo que NO se puede hacer

Límites conocidos. Si un cliente pide algo de esta lista, la respuesta es "no, no es parte de esta integración" — la columna Dónde se hace indica dónde sí se resuelve.

Toteat no envía datos a Ruka La integración es unidireccional: solo Ruka → Toteat. Las ventas, consumos por receta, mermas o ajustes que ocurren en Toteat no se reflejan en Ruka.

Dónde se hace → no aplica — modelo intencional. El detalle de operación vive en Toteat.

Sincronización continua de maestros (productos / proveedores) entre sistemas Cada sistema mantiene su catálogo de forma independiente. Si un ítem existe en Ruka pero no en Toteat (o viceversa), la inyección falla con error controlado y queda pendiente de revisión humana. No hay sincronización bidireccional ni continua de maestros como parte de esta integración.

Dónde se hace → alineación manual de SKU por parte del cliente. Nota operativa: Ruka desarrolló por su cuenta un script para extraer el catálogo inicial de Toteat y precargarlo en Ruka durante el onboarding de su producto — esto acelera la implementación de Ruka, pero no es parte de esta integración: es una herramienta one-shot interna de Ruka, sin sincronización posterior, y no aplica en sentido inverso (Ruka → Toteat).

Propagación bidireccional de anulaciones / correcciones Las anulaciones no se sincronizan en ninguna de las dos direcciones. Si el cliente anula una compra en Ruka, eso no se refleja automáticamente en Toteat. Si anula un movimiento en Toteat, eso tampoco vuelve a Ruka. Cada anulación o corrección debe hacerse en ambos sistemas por separado para mantener la consistencia.

Dónde se hace → manualmente en cada sistema. Importante para el soporte: si un cliente reporta diferencia entre Ruka y Toteat después de una anulación, el primer paso es preguntar dónde la hizo y verificar el otro sistema.

Recetas, mermas, transferencias entre locales Esos movimientos siguen viviendo en Toteat. Ruka cubre las compras (entrada de mercadería), no la operación interna del restaurante.

Dónde se hace → Toteat (módulo Inventario Avanzado).

Tomas de inventario (teórico vs real) Las tomas de inventario son la pieza clave para mantener la salud del stock — comparan el teórico (lo que el sistema dice que hay, calculado a partir de compras menos consumos) contra el real (lo que el equipo cuenta físicamente en bodega) y exponen la diferencia. Esa diferencia es la merma real, el robo, el error de digitación, el mal mapeo de receta. Sin tomas de inventario, el teórico se aleja del real semana a semana.

Dónde se hace → Toteat (módulo Inventario Avanzado). Ruka inyecta el teórico vía compras pero no participa de la conciliación contra el conteo físico — eso es operación interna del restaurante y la fuente de verdad de los conteos vive en Toteat.

Sincronización de pago a proveedores / contabilidad La integración cubre el movimiento de inventario, no el flujo financiero. La conciliación contable y el pago a proveedor son responsabilidad del ERP / Ruka según el setup del cliente.

Dónde se hace → Ruka + ERP del cliente.

⚠ Ítems a validar con integraciones Los puntos marcados con ⚠ Validar son supuestos razonables basados en el patrón estándar del endpoint /purchasemovements, pero conviene confirmarlos con el equipo técnico antes de que este documento se use como respuesta definitiva con cliente. Hoy quedan pendientes: comportamiento exacto en escenarios multi-local / multi-bodega, e idempotencia por número de documento.

Contrato técnico

Resumen del contrato de integración para uso de soporte. La fuente de verdad técnica es la documentación pública de Toteat (developers.toteat.com).

Aspecto	Detalle
Endpoint	`POST /purchasemovements`
Quién lo consume	Ruka (cliente) ↔ Toteat (servidor)
Autenticación	Token API entregado por Toteat al cliente; el cliente comparte con Ruka durante la activación
Cuándo se dispara	Cuando una compra en Ruka pasa a estado "aprobada" / "lista para inventario" (depende de la configuración de Ruka)
Idempotencia	Por número de documento — reenviar la misma compra no duplica el movimiento ⚠ Validar
Errores típicos	SKU no encontrado en Toteat · bodega no válida · token inválido / expirado · payload malformado
Visibilidad en Toteat	Módulo Inventario Avanzado → Movimientos de compra. Cada movimiento queda con su origen identificado.

Activación paso a paso En preparación

Próxima sección: qué se configura en Toteat (token API, habilitación del módulo Inventario Avanzado, mapeo de bodegas), qué se configura en Ruka (credenciales, ID del cliente, mapeo de SKU), cómo se valida el primer ingreso de prueba y cómo se hace el cutover de un cliente que hoy carga compras a mano. Target: que un implementador nuevo pueda activar un cliente sin conocimiento previo.

Fallos & troubleshooting En preparación

Próxima sección: los síntomas más frecuentes — "una compra de Ruka no aparece en Toteat", "el costo aparece distinto en ambos lados", "un SKU se rechaza repetidamente", "el stock no cuadra después de un período" — cada uno con árbol de diagnóstico: qué preguntar al cliente, qué revisar primero, cómo resolver y cuándo escalar a Ruka o a integraciones de Toteat.

Contactos & escalamiento En preparación

Próxima sección: a quién contactar en Toteat según el tipo de incidencia (soporte técnico, integraciones, comercial), a quién contactar en Ruka, canales oficiales, SLAs esperados y formato del escalamiento. Target: cero tiempo perdido buscando a quién escribirle.