Movimientos de inventario desde un sistema externo

Si tu negocio vende también fuera de Mosce ERP - un punto de venta propio, una tienda en línea de terceros, un sistema de almacén heredado - puedes conectar ese sistema para que informe automáticamente los movimientos de inventario que ya ocurrieron: una venta ya cobrada, una devolución ya recibida, un ajuste ya hecho. Mosce ERP actualiza tu existencia real con cada movimiento, identificando el producto por su código interno.

Tiempo de lectura: ~8 min

Cuándo usar esto

• Vendes en más de un canal (tienda física con su propio punto de venta, marketplace, tienda en línea) y quieres que Mosce ERP refleje tu inventario real sin capturarlo a mano.
• Tienes un sistema de almacén o un ERP externo que ya controla las entradas y salidas físicas, y quieres que Mosce ERP se entere automáticamente.
• Necesitas que la existencia en Mosce ERP no se desactualice cada vez que ocurre un movimiento fuera de la aplicación.

Qué NO es esto

• No es una reserva de inventario. Un movimiento reportado aquí ya ocurrió: el descuento o el ingreso es real, no un apartado para un pedido pendiente. Para reservas al crear un pedido dentro de Mosce ERP, ver Reserva de inventario al crear un pedido.
• No emite comprobantes fiscales. Es integración operativa pura: solo toca tu existencia. No crea, modifica ni anula ningún comprobante ante la DGII.

Antes de empezar

• El acceso a esta integración es parte de los planes Profesional, Empresarial y Corporativo. No está disponible en el plan Inicial.
• Necesitas el permiso tenant:integrations para activar la integración y administrar sus credenciales. Ver Usuarios, roles y permisos para asignarlo a un rol.
• Aunque tu plan incluya la integración, llega apagada por defecto. Debes encenderla explícitamente antes de que cualquier credencial pueda usarse - habilitar por error una escritura contra tu inventario no debería pasar por accidente.

Paso 1 - Activar la integración

1. Ve a Configuración → Acceso a API.
2. Activa el interruptor. Mientras está apagado, cualquier credencial existente es rechazada, aunque sea válida.

Paso 2 - Generar una credencial

1. Haz clic en Nueva credencial y ponle un nombre que identifique el sistema que la va a usar (por ejemplo "Punto de venta - Sucursal Naco", "ERP del almacén").
2. Mosce ERP genera la credencial y la muestra una sola vez. Cópiala de inmediato y guárdala en el gestor de secretos de tu sistema externo.

La credencial no se puede volver a ver después de cerrar el diálogo. Si la perdiste, tu única opción es rotarla (ver Rotar o revocar una credencial) - no existe forma de recuperar el valor original.

Paso 3 - Enviar movimientos

Tu sistema hace peticiones POST a:

https://tu-dominio/api/v1/integrations/inventory/movements

con la credencial en el encabezado Authorization:

Authorization: Bearer hlx_live_...

Cada movimiento identifica el producto por su código interno - el mismo código que ves en tu catálogo de Mosce ERP - y no requiere indicar sucursal ni almacén: se aplica donde ese producto tiene existencia, sin que tu sistema tenga que conocer la estructura interna de sucursales y almacenes de tu cuenta.

{
  "idempotencyKey": "pos-ticket-99841",
  "occurredAt": "2026-09-21T14:32:10Z",
  "movements": [
    { "code": "0142", "quantity": -3, "reason": "sale", "note": "Ticket 99841" },
    { "code": "0311", "quantity": 2, "reason": "return" }
  ]
}

• code - el código interno del producto en tu catálogo.
• quantity - con signo. Negativo descuenta existencia, positivo la aumenta. No se acepta cero.
• reason - el motivo del movimiento: sale (venta), return (devolución), adjustment (ajuste), transfer_out / transfer_in (traslado de salida / entrada), damage (merma o daño) o count (conteo físico). El historial del producto en Mosce ERP queda organizado por este motivo.
• occurredAt - opcional, informativo: cuándo ocurrió realmente el movimiento en tu sistema.
• idempotencyKey - obligatoria y única por tu negocio. Si tu sistema reintenta el envío (por ejemplo, tras un timeout de red), reutilizar la misma clave devuelve la misma respuesta sin volver a aplicar el movimiento. Sin esta clave, un reintento podría descontar la misma venta dos veces. Reutilizar la misma clave con un cuerpo distinto no se trata como un reintento: Mosce ERP la rechaza con 422 en vez de aplicar el nuevo cuerpo - usa una clave nueva para una operación distinta.

Cada envío admite hasta 200 movimientos.

Qué responde Mosce ERP

Cada línea se resuelve por separado, y una línea que no se puede aplicar no impide que las demás sí se apliquen:

{
  "accepted": 1,
  "discarded": 1,
  "results": [
    { "code": "0142", "status": "accepted", "movementId": "..." },
    { "code": "0311", "status": "discarded", "warning": "PRODUCT_HAS_NO_INVENTORY_RECORD" }
  ]
}

Un movimiento se descarta - nunca tumba el envío completo - cuando:

Cada movimiento descartado también queda visible en la pantalla de actividad de la integración, con su motivo, para que puedas corregirlo sin tener que revisar los registros de tu propio sistema.

Revisar qué se envió

Si tu equipo te dice "os mandamos la venta y no aparece", no hace falta adivinar qué pasó: Mosce ERP guarda cada petición que llega con el cuerpo exacto que tu sistema envió y la respuesta exacta que le devolvió, ambos en formato JSON.

1. Ve a Configuración → Acceso a API y abre la tarjeta Peticiones recibidas - es una lista aparte de la de actividad reciente, dedicada solo al registro de cada llamada.
2. Recorre la lista con los botones Anterior / Siguiente - ordenada de la más reciente a la más antigua - hasta encontrar la petición que te interesa, y ábrela.
3. El detalle muestra los dos JSON, uno junto al otro, con un botón de copiar en cada uno, para que puedas compararlos contra lo que tu sistema externo cree haber enviado.

Si tu sistema reintentó el envío reutilizando la misma clave de idempotencia, esa petición aparece marcada como repetición. Es la explicación más común de "lo reenvié y no pasó nada": Mosce ERP no volvió a aplicar el movimiento porque ya lo había aplicado la primera vez, y devolvió la misma respuesta sin tocar tu existencia de nuevo.

Límite de envío

Esta integración protege la plataforma con dos límites independientes, ninguno de los cuales depende de tu plan - aplican igual a todas las cuentas con la integración activa:

• Un límite de ráfaga: hasta 60 peticiones cada 10 segundos.
• Un límite sostenido sobre el volumen de datos: hasta 6.000 líneas de movimiento por minuto, no peticiones. Un solo envío con 200 movimientos consume 200 unidades de este presupuesto, no 1.

Cada respuesta incluye cabeceras que reflejan el límite sostenido, el de líneas de movimiento:

Si excedes cualquiera de los dos límites, Mosce ERP responde 429 con una cabecera Retry-After indicando cuánto esperar antes de reintentar. Diseña tu sistema para leer estas cabeceras contando líneas de movimiento, no peticiones - confundir las dos unidades te hace sobrestimar tu presupuesto real hasta por un factor de 200.

Rotar o revocar una credencial

• Rotar: genera una credencial nueva mientras la anterior sigue funcionando durante 24 horas. Usa esta opción para actualizar tu sistema externo sin interrumpir el envío de movimientos.
• Rotar de urgencia: genera una credencial nueva e invalida la anterior en el acto, sin ventana de solapamiento. Usa esta opción solo cuando sospechas que una credencial se filtró.
• Revocar: desactiva la credencial de forma permanente. Las credenciales no se pueden eliminar - revocar es su estado final, precisamente para que el historial de movimientos siga explicando quién hizo qué incluso después de que dejes de usar esa credencial.

Cuánto se conserva

No todo lo que toca esta integración se conserva por el mismo tiempo. Son tres reglas distintas:

• El registro de cada petición - el cuerpo que llegó y la respuesta que se dio - se conserva 90 días, un plazo fijo e igual en todos los planes.
• El detalle de una línea descartada - por qué no se pudo aplicar un movimiento - sigue la retención del registro de auditoría de tu cuenta, que depende de tu plan y puede ser menor a 90 días. La pantalla de actividad de la integración te muestra el número exacto de días que aplica a tu cuenta, para que no tengas que adivinarlo.
• El efecto de un movimiento aceptado sobre tu existencia no caduca nunca. Es tu historial de inventario y se conserva de forma permanente.

En otras palabras: pasado ese plazo, de una petición ya aplicada queda para siempre lo que le pasó a tu existencia, pero el detalle exacto de qué se envió - y por qué se descartó una línea en particular - puede dejar de estar disponible. Si necesitas conservar ese detalle más allá de su plazo, guárdalo también en tu propio sistema.

Errores comunes

Preguntas frecuentes

¿Puedo indicar en qué sucursal o almacén ocurrió el movimiento?

No. El código de producto es único en toda tu cuenta, así que el movimiento se aplica donde ese producto tiene existencia, sin que tu sistema tenga que conocer la estructura interna de sucursales y almacenes de Mosce ERP.

¿Qué pasa si el producto tiene existencia en más de un almacén?

Mosce ERP resuelve automáticamente dónde aplicar el movimiento según la configuración de tu catálogo. Si no puede determinarlo con certeza, el movimiento se descarta con LOCATION_AMBIGUOUS en vez de aplicarse en un lugar equivocado.

¿Esta integración crea comprobantes fiscales?

No. Es integración operativa pura: solo actualiza tu existencia. No emite, modifica ni anula ningún comprobante ante la DGII.

¿Cuántas credenciales puedo tener activas a la vez?

El tope depende de tu plan. La pantalla Configuración → Acceso a API muestra el número real de tu cuenta y cuántas ya tienes en uso. Si llegaste al tope y necesitas una nueva, revoca primero alguna credencial que no uses, o cambia a un plan con más cupo.

¿Por cuánto tiempo puedo revisar el detalle de una petición ya enviada?

El registro de cada petición - el cuerpo que llegó y la respuesta que se dio - se conserva 90 días, igual en todos los planes. El efecto sobre tu existencia no se pierde nunca, aunque el registro de la petición ya haya expirado. Ver Cuánto se conserva para las tres reglas completas.

Relacionados

• Inventario y existencia
• Ajustes de inventario
• Usuarios, roles y permisos
• Página de precios

Última actualización: 2026-09-21