FAQ para desarrolladores

Preguntas frecuentes al integrar una app con NinoxNet vía la integración de terceros.

General

¿Necesito ser cliente de NinoxNet para integrarme?

Sí. La integración opera sobre los datos de una cuenta NinoxNet (catálogo, stock, puntos de venta). El alta del token se coordina con tu cuenta.

¿La integración tiene costo?

Sí, es un costo adicional al plan, según el esquema comercial vigente (ninoxnet.com/integraciones/terceros).

¿Cómo empiezo a desarrollar antes de tener todo aprobado?

Cloná el repo starter y revisá la documentación. El desarrollo real necesita un token de pruebas, que se entrega tras el análisis del caso (ver onboarding).

Acceso y tokens

¿Dónde consigo el token X-NX-TOKEN?

Se provisiona como parte del onboarding. El alta y la administración del token se coordinan con Banhaia.

¿Puedo usar el token desde el frontend o una app móvil?

No. El token es de backend exclusivamente. Exponerlo en cliente compromete toda la cuenta. Implementá un backend intermedio que guarde el token y exponga solo lo que tu app necesite. Ver Autenticación.

¿Hay ambiente de pruebas?

Sí: https://api.test-ninox.com.ar. Desarrollá y probá ahí; producción (https://api.ninox.com.ar) es el último paso (go live).

¿El token sirve para varios depósitos o puntos de venta?

Para leer varios depósitos, sí: se habilita a pedido sobre la misma integración. Es una función experimental, disponible desde el plan Empresa. Los pedidos y ventas que enviás van siempre contra el depósito y el punto de venta configurados en tu integración. Ver Alcance y límites.

Catálogo y stock

¿Cómo obtengo el stock actualizado en tiempo real?

No hay tiempo real por polling: GetData tiene una frecuencia mínima de 10 minutos. Para acercarte a tiempo real, configurá webhooks (push de cambios) y mantené un caché local.

¿Cuál es la diferencia entre GetData y GetDataCurva?

GetData devuelve artículos agrupados con su curva (variantes) anidada. GetDataCurva devuelve un registro plano por variante (talle/color). Para storefronts y bots suele ser más cómodo el plano. Ver Catálogo.

¿Cómo detecto productos dados de baja?

Tratá GetData como snapshot completo: lo que ya no viene, se dio de baja. Por webhook, la baja lógica llega como { articuloId, eliminado: true }.

¿Cómo manejo talles y colores?

Mirá talleColor (TipoTalleColor) en el artículo y recorré la curva / ArticuloConCurva por talleId / colorId. Cada combinación tiene su propio unidades (stock). Ver Esquema de datos.

Pedidos y ventas

¿Un pedido genera una venta directamente?

Depende de la configuración: POST /Pedido genera un pedido de venta o una preventa/reserva. Validá siempre total = subtotal + envio + recargo - descuento o vas a recibir un 422. Ver Pedidos.

¿Puedo facturar electrónicamente (AFIP)?

Sí, vía el endpoint BETA POST /terceros/facturar con electronica=true. Está en BETA: confirmá disponibilidad antes de comprometerlo. Ver Ventas (BETA).

¿Cómo evito pedidos/ventas duplicados?

Hay anti-duplicados de 30 s por ordenId (ventas) y por facturaId (facturar). Usá un ordenId único y estable por orden.

¿Puedo leer las ventas o los clientes por la API?

Sí, mediante los endpoints de exportación (BETA): exportar/ventaitems trae ítems de venta por período, exportar/clientes la base de clientes y exportar/saldos los saldos vencidos. Para recorrer clientes de a páginas, usá /entidades.

Webhooks

¿Cómo activo los webhooks?

Se coordinan con Banhaia: informás tu URL HTTPS, headers de auth y formato de payload. Tu endpoint debe responder 200 OK en menos de 10 s. Ver Webhooks.

¿Qué eventos notifican?

Cambios de stock, precios, propiedades, variantes y clasificación de artículos (incluida la baja lógica).

Errores y límites

Me devuelve 403, ¿qué pasó?

Superaste un límite de frecuencia (10 min en catálogo/exportaciones, 3 s en movimientos de stock). Esperá la ventana mínima. Ver Alcance y límites.

Me devuelve 422 al crear un pedido.

Error de validación: revisá que los totales cuadren y que los campos obligatorios estén completos.

Me devuelve 401.

Token inválido o expirado: revisá el header X-NX-TOKEN.

La tabla completa de códigos está en Errores comunes.