Saltar al contenido principal

Asistente de implementación

Planificá tu integración paso a paso. Elegí un escenario y recorré la guía adaptada a tu caso de uso.

Starters listos para usar

Hay dos repositorios públicos que ya resuelven esta guía y están preparados para que una IA te ayude a arrancar: una app de gestión y una tienda online. Elegí el tuyo y copiá el prompt en Ejemplos.

Antes de empezar​

Necesitás un token activo, acceso al entorno de pruebas y un caso de uso definido. Si todavía no tenés token, podés arrancar con las respuestas de ejemplo del repo starter. El detalle del alta está en Onboarding.

Elegí tu escenario​

Cada escenario tiene pasos adaptados. Elegí el que más se acerque a tu caso:

Publicar catálogo y enviar pedidos desde un canal propio.

Necesitás: lectura de catálogo + pedidos + sincronización.

Paso 1​

Definir alcance

Confirmá que la integración cubre un único depósito y un único punto de venta para esta app.

Entregable: una definición simple de catálogo, stock y flujo de pedido.

Checklist:

  • Acordar si necesitás solo lectura o también pedidos.
  • Validar el depósito y punto de venta asociados al token.
  • Tener presente que la integración tiene un costo adicional.
Varios depósitos, a pedido

Los pedidos van contra el depósito y el punto de venta de tu integración. Si necesitás leer el stock de más de un depósito, no hace falta una integración separada: se habilita a pedido (experimental). Ver Alcance y límites.

Paso 2​

Traer catálogo

Consumí el catálogo completo y validá cómo llegan artículos y variantes.

GET/integraciones/Terceros/GetData

Entregable: un primer snapshot local del catálogo.

Checklist:

  • Guardar artículo, variante, precio y stock.
  • Respetar la frecuencia mínima de 10 minutos.
  • No exponer el token en frontend.

Primer request de prueba:

curl -s https://api.test-ninox.com.ar/integraciones/Terceros/GetData \
  -H "X-NX-TOKEN: TU_TOKEN" \
  -H "Content-Type: application/json"

Si usás el starter kit con Node.js:

git clone https://github.com/banhaia/ninox-integration-starters.git
cd ninox-integration-starters
npm install
npm run dev
# Abrí http://localhost:5173, creá tu usuario y cargá el token en Configuración
Frecuencia mínima

Los endpoints de lectura tienen una ventana mínima de 10 minutos entre consultas. Si consultás antes, la API responde 403 Forbidden.

Paso 3​

Normalizar datos

Convertí la respuesta de Ninox al modelo que usa tu ecommerce.

Entregable: productos y variantes listos para publicación.

Checklist:

  • Separar producto base de variante.
  • Mapear categorías y etiquetas.
  • Registrar bajas lógicas con el campo eliminado.

El detalle completo de tipos y contratos está en Esquema de datos. En el starter kit, server/src/modules/catalog/mapper.ts y server/src/ninox/types.ts muestran un ejemplo de normalización.

Paso 4​

Sincronizar cambios

Definí cómo vas a reconciliar el snapshot completo que entrega Ninox con tu modelo local.

GET/integraciones/Terceros/GetData y lógica propia de reconciliación

Entregable: una estrategia operativa para refrescar catálogo, stock y bajas.

Checklist:

  • Tomar a Ninox como snapshot completo del depósito asociado a la app.
  • Resolver qué artículos o variantes dejaron de llegar para marcarlos como eliminados, o reemplazar todo el set local en cada corrida.
  • Mantener logs de sincronización y errores.
Artículos eliminados

Cada respuesta de GetData es el set completo vigente. Si un artículo deja de aparecer, tu sistema debe marcarlo como eliminado o reemplazar el catálogo local completo.

Opcionalmente, podés usar Webhooks para recibir cambios incrementales sin polling. En el starter kit, server/src/modules/catalog/sync-service.ts implementa este flujo con reemplazo completo sobre SQLite y bajas lógicas.

Paso 5​

Enviar pedidos

Conectá el checkout o la reserva de compra con Ninox.

POST/integraciones/Terceros/Pedido

Entregable: pedidos enviados con validación e idempotencia.

Checklist:

  • Validar totales antes de enviar.
  • Evitar duplicados por reintentos.
  • Persistir la referencia local y la respuesta de Ninox.
Validación de totales

El campo total debe coincidir con la fórmula subtotal + envio + recargo - descuento.

En el starter kit, server/src/modules/orders/service.ts implementa el flujo completo con ordenId idempotente, reintento y cancelación. Ver Pedidos para el detalle de creación y cancelación.

Recursos​

Siguiente paso​

Si ya definiste tu alcance y tenés el token listo, arrancá por consumir GetData, validá la estructura y avanzá paso a paso. Considerá que esta integración tiene un costo adicional (ninoxnet.com/integraciones/terceros).

¿Necesitás ayuda o querés coordinar tu caso de uso? Completá el formulario en ninoxnet.com/integraciones/terceros.