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.

Starter kit disponible

Tenemos un repositorio público con templates, ejemplos y documentación pensada para agentes AI: 👉 github.com/banhaia/ninox-integration-starters. Más detalle 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.
Una app = un depósito + un punto de venta

Si necesitás cubrir múltiples depósitos o puntos de venta, cada uno requiere una integración separada. 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
cp templates/node-typescript/.env.example templates/node-typescript/.env
# Editá .env con tu token
node examples/chatbot-stock/run.js "remera"
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, templates/node-typescript/src/services/productService.ts y src/types/product.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, examples/stock-dashboard-app/server/src/services/catalog-sync-service.ts implementa este flujo con snapshot a JSON local.

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, examples/create-order/run.js tiene un placeholder del flujo. 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.