Alcance y límites
Reglas de alcance
Antes de diseñar (y cotizar) tu integración, tené en cuenta estas reglas del alcance actual:
- Cada app/token está asociada a un solo depósito.
- Cada app/token está asociada a un solo punto de venta.
- El stock que recibís y los pedidos que enviás se resuelven dentro de esa configuración.
- 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).
Si tu proyecto necesita múltiples depósitos o múltiples puntos de venta, hoy se resuelve con integraciones separadas o coordinando el caso con el equipo.
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.
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 |
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 |
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 ventanaNo 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.
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.
Varios depósitos o locales
Una integración puede administrar varios depósitos sin necesidad de un token por cada uno.
| 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). Requiere plan Corporativo y lo activa NinoxNet en el canal |
| 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 |
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.