Alcance y límites

Reglas de alcance

Antes de diseñar (y cotizar) tu integración, tené en cuenta estas reglas del alcance actual:

• Los pedidos y ventas que enviás se registran siempre en el depósito y el punto de venta configurados en tu integración.
• Por defecto, el stock que recibís es el de ese depósito. Leer varios depósitos con la misma integración es posible a pedido (ver Varios depósitos o locales).
• La autenticación se realiza por token.
• La lectura de datos históricos y los movimientos de stock quedan acotados a las sucursales habilitadas para la integración (ver abajo).

Varios depósitos, a pedido

Si tu proyecto necesita leer el stock de más de un depósito, no hace falta una integración por cada uno: se habilita a pedido sobre la misma integración. Es una función experimental, disponible desde el plan Empresa. Escribinos por el Chat de Ayuda.

Sucursales habilitadas

El token identifica a tu integración, pero no le da acceso a todo el ERP. El administrador del tenant define desde Configuración › Canales › tu integración qué sucursales puede consultar y escribir.

Lectura — exportar/ventaitems, exportar/ventaitems/paginado, exportar/saldos/*, exportar/stock, saldos/* y POST /stock/movimiento: si no hay sucursales habilitadas, responden 403. No alcanza a exportar/clientes (los clientes no tienen sucursal) ni al catálogo (GetData / GetDataCurva), que se resuelve por el depósito configurado del canal.

Alta de comprobantes — POST /pedido, /venta, /notacredito y /facturar: se valida que el punto de venta con el que se emite caiga en una sucursal habilitada, pero no cortan si no hay lista cargada. En ese caso se toma la sucursal de los depósitos o del punto de venta ya configurados en el canal, así que una integración que hoy funciona sigue funcionando.

GET /depositos sigue la misma lógica indulgente: sin sucursales habilitadas devuelve los depósitos configurados en tu canal en vez de 403.

Sin sucursales habilitadas no se exporta nada

Es el comportamiento por defecto: una integración recién creada no tiene sucursales habilitadas y esos endpoints responden 403 hasta que el administrador las cargue. Pedíselo como parte del alta.

Consultá las tuyas en GET /integraciones/terceros/config → sucursalesExportacion.

Límites de frecuencia

Operación	Límite	Si lo superás
GetData / GetDataCurva (catálogo)	mínimo 10 min entre consultas	403 Forbidden
exportar/* (exportaciones)	10 min en producción (3 min en test), bucket compartido	403 Forbidden
exportar/*/paginado (ventaitems, ventatotales, compraitems, compratotales, gastos)	30 s en producción (3 s en test), un bucket compartido entre los cinco	403 Forbidden
stock/movimiento	3 s entre requests	403 Forbidden
Endpoints de parámetros (config, config/depositos, depositos, medios-pago, empleados, puntos-venta)	60 s en producción (10 s en test)	403 Forbidden
comprobante/{id}	10 s en producción (3 s en test)	403 Forbidden
venta	anti-duplicados 30 s por ordenId	rechazo
facturar	anti-duplicados 30 s por facturaId	rechazo

No existe "stock en tiempo real" por polling

La frecuencia mínima de catálogo es de 10 minutos. Para acercarte a tiempo real usá webhooks (push) + caché local, no polling agresivo.

comprobante/{id} tiene su propia ventana

No comparte la ventana de 60 segundos de los endpoints de parámetros: su uso natural es consultar el estado de un comprobante recién creado, y con esa ventana sería inservible.

Bucket compartido de exportaciones

Las exportaciones (exportar/clientes, exportar/ventaitems, exportar/stock, exportar/saldos/*) comparten la misma ventana de rate limit por tenant: solo se puede ejecutar una exportación dentro de la ventana. Planificá las corridas para no pisarte.

Los paginados de comprobante tienen su propia ventana corta, también compartida entre ellos: no podés recorrer ventas, compras y gastos en paralelo. Ver Exportaciones.

Varios depósitos o locales

Una integración puede administrar varios depósitos sin necesidad de un token por cada uno. Es una función experimental: los depósitos adicionales los configura NinoxNet en el canal, a pedido, desde el plan Empresa.

Qué querés	Cómo se hace
Recibir el stock de todos tus depósitos en cada cambio	modo multidepósito informativo: el webhook agrega stockDepositos (Webhooks). Lo activa NinoxNet en el canal, a pedido
Consultar el catálogo con el stock de un depósito puntual	depositoId en GetData / GetDataCurva (Catálogo)
Reconciliar el stock completo de un depósito	exportar/stock con depositoId

El catálogo no se pagina ni se desagrega

GetData / GetDataCurva devuelven el catálogo entero de una y no aceptan paginado, así que recorrerlo depósito por depósito es caro en tenants grandes. Para stock multidepósito el camino recomendado son los webhooks (push, todos los depósitos en un solo evento) y exportar/stock para la reconciliación periódica.

Los depósitos de tu integración los lista GET /integraciones/terceros/config/depositos, y siguen sujetos a las sucursales habilitadas.

Qué conviene definir antes de desarrollar

• Si tu caso necesita solo lectura o también pedidos/ventas.
• Si vas a trabajar con stock por caché + webhooks o por polling respetando los 10 min.
• Si tu modelo debe contemplar variantes (talle/color).
• Dónde vas a guardar el token (siempre backend).
• Cómo vas a persistir catálogo, stock, logs e idempotencia de pedidos.