Asistente de implementación

Planificá tu integración paso a paso. Elegí un escenario y recorré la guía de implementación 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

Cloná el repo, abrilo con tu herramienta favorita y seguí los pasos de esta página.

Antes de empezar

Para usar la integración de terceros necesitás:

1. Token activo — se obtiene al contratar la integración. Si no lo tenés, contactá a dev@banhaia.com o revisá el proceso de contratación.
2. Entorno de pruebas — https://api.test-ninox.com.ar para validar antes de producción.
3. Un caso de uso definido — ecommerce, chatbot, sincronización con sistema externo, etc.

Si todavía no tenés token, podés arrancar igual. El starter kit incluye respuestas de ejemplo (shared/sample-responses/) para desarrollar offline.

Elegí tu escenario

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

Ecommerce propio

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

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

Chatbot con stock

Consultar catálogo, precios, variantes y disponibilidad.

Necesitás: lectura de catálogo + búsqueda + caché.

Sistema externo

Sincronizar Ninox con CRM, middleware o procesos internos.

Necesitás: lectura de catálogo + normalización + sync periódico.

---

Paso 1

Ecommerce propio

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.

Referencia: definición funcional y comercial inicial.

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.

Chatbot con stock

Definir preguntas

Determiná qué consultas debe responder el bot y con qué nivel de precisión.

Entregable: una lista corta de intents y campos necesarios.

Checklist:

• Buscar por nombre, código, categoría o etiqueta.
• Decidir si el bot solo informa o también inicia un pedido.
• Tener presente el costo adicional del servicio.

Sistema externo

Definir integración

Alineá el objetivo técnico con el alcance real del token entregado por Ninox.

Entregable: un contrato interno de qué lee y qué escribe tu sistema.

Checklist:

• Confirmar depósito y punto de venta únicos.
• Definir si habrá lectura, pedidos o ambos.
• Considerar el costo adicional en la implementación.

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.

---

Paso 2

Ecommerce propio

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.

Chatbot con stock

Traer catálogo

Descargá el catálogo en formato fácil de indexar.

GET/integraciones/Terceros/GetData

Entregable: un índice local para búsquedas del bot.

Checklist:

• Indexar texto visible y variantes.
• Guardar stock por variante.
• Respetar la ventana mínima de consulta.

Sistema externo

Importar datos

Traé artículos y variantes para construir la base maestra local.

GET/integraciones/Terceros/GetData

Entregable: un dataset inicial listo para mapear.

Checklist:

• Guardar ids de Ninox sin modificarlos.
• Normalizar precios y stock.
• Respetar la ventana mínima entre consultas.

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

Ecommerce propio

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.

Chatbot con stock

Preparar búsqueda

Construí una capa simple para responder preguntas frecuentes.

Entregable: reglas o funciones de búsqueda para el agente.

Checklist:

• Resolver coincidencias por código y nombre.
• Usar categorías y etiquetas como filtros.
• Definir qué hacer cuando no hay stock.

Sistema externo

Mapear entidades

Adaptá el catálogo de Ninox a tus tablas o colecciones internas.

Entregable: mapeos de producto, variante y clasificación.

Checklist:

• Separar datos externos de datos enriquecidos locales.
• Mantener trazabilidad entre ids.
• Preparar compatibilidad con futuros endpoints.

Los campos principales que vas a encontrar en cada artículo:

Campo	Descripción
Código	Identificador interno del artículo
Descripción	Nombre y descripción extendida
Categorías	Clasificación jerárquica (array)
Etiquetas	Tags planos (array)
Precios	Precio principal y precios adicionales
Variantes	Combinaciones de talle/color con stock individual
Stock	Disponible por artículo o variante, según el depósito

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

Ecommerce propio

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 en tu sistema 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.

Chatbot con stock

Actualizar datos

Mantener el índice alineado con el snapshot completo que expone Ninox.

GET/integraciones/Terceros/GetData y reconciliación local

Entregable: un esquema de actualización que contemple altas, cambios y faltantes.

Checklist:

• Entender que el endpoint devuelve una foto completa del depósito asociado.
• Definir si tu bot hace replace completo del catálogo o si detecta qué dejó de llegar para marcarlo como eliminado.
• Registrar fecha de última sincronización y resultado de la corrida.

Sistema externo

Operar sincronización

Definí una rutina segura para procesar snapshots completos y reconciliar tu fuente local.

GET/integraciones/Terceros/GetData

Entregable: un proceso repetible y auditable para altas, cambios y bajas lógicas.

Checklist:

• Usar una persistencia local que te permita comparar corridas.
• Decidir si Ninox será fuente de verdad con replace completo o si vas a calcular diferencias.
• Registrar errores, reintentos y elementos que dejaron de estar presentes en el snapshot.

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

Ecommerce propio

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.

Chatbot con stock

Escalar a pedido

Si el bot debe cerrar ventas, prepará el salto al flujo de pedidos.

POST/integraciones/Terceros/Pedido

Entregable: un flujo listo para evolucionar a reserva o venta asistida.

Checklist:

• Confirmar datos del cliente antes de enviar.
• Validar precios y disponibilidad.
• Registrar intentos y respuestas para soporte.

Sistema externo

Integrar pedidos

Si aplica, conectá la emisión de pedidos desde el sistema externo.

POST/integraciones/Terceros/Pedido

Entregable: un flujo transaccional con control de duplicados.

Checklist:

• Validar totales y datos fiscales.
• Persistir correlación entre orden local y pedido enviado.
• Implementar idempotencia.

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. Para cancelar un pedido: POST /integraciones/Terceros/Pedido/cancelar con facturaid.

---

Usar con un agente AI

El starter kit está preparado para funcionar con agentes AI. Incluye un archivo CLAUDE.md en la raíz del repositorio con instrucciones que los agentes leen automáticamente.

Cómo arrancar

1. Cloná el repositorio.
2. Abrilo en tu herramienta preferida (Claude Cowork, Claude Code, Cursor, etc.).
3. Decile al agente algo como:

"Quiero crear una integración con Ninox. Mi caso de uso es ecommerce. Mi stack es React + Express. tengo token."

"Quiero crear una integración con Ninox. Mi caso de uso es chatbot. Elegi el mejor stack para mi. No tengo token."

El agente va a seguir la metodología de 5 pasos, usar el repo como referencia de patrones y crear tu app en un directorio nuevo.

Qué incluye el starter kit

Recurso	Para qué sirve
templates/node-typescript/	Cliente HTTP base, tipos, normalización
examples/chatbot-stock/	Búsqueda de productos por texto
examples/ecommerce-sync/	Mapeo de catálogo para storefronts
examples/create-order/	Placeholder de creación de pedido
examples/stock-dashboard-app/	App full-stack de referencia (React + Express)
shared/sample-responses/	Respuestas mock para desarrollo sin token
shared/postman/	Colección Postman para testing manual

No es obligatorio usar Node.js

Los ejemplos están en Node.js/TypeScript, pero la API de Ninox es REST estándar. Un agente AI puede generar código en cualquier lenguaje usando los ejemplos como referencia de patrones y el CLAUDE.md como guía de implementación.

Si no tenés un agente AI

También podés copiar los prompts sugeridos del archivo data/ninox_getting_started_integracion_terceros.md en el repo y pegarlos en cualquier chat de AI (ChatGPT, Claude, etc.) para obtener ayuda con la implementación.

Errores comunes

Código	Causa	Qué revisar
401	Token inválido o expirado	Header X-NX-TOKEN
403	Consulta antes de los 10 minutos	Esperar y reintentar
400	Request mal formada	Formato del payload
422	Error de validación	Totales del pedido, campos requeridos
500	Error interno	Reintentar con backoff

Siguiente paso

Si ya definiste tu alcance y tenés el token listo, arrancá por consumir GetData, validar la estructura y avanzar paso a paso.

Considerá que esta integración tiene un costo adicional. Más información en ninoxnet.com/integraciones/terceros.

Si necesitás ayuda o querés coordinar tu caso de uso con el equipo técnico: dev@banhaia.com.