Integración Genérica RFID - Especificación Técnica

REST API

v1.0

Introducción

Documento técnico que describe el flujo de integración RFID con Ninox: modelo de datos, endpoints, webhooks y consideraciones operativas.

Base URLs (Test / Producción)

Usa la base apropiada según el entorno de tu integración:

Pruebas: https://api.test-ninox.com.ar
Producción: https://api.ninox.com.ar

Todos los endpoints mostrados en esta página son relativos a la base anterior. Por ejemplo:

POST https://api.ninox.com.ar/integraciones/rfid/lectura
POST https://api.test-ninox.com.ar/integraciones/rfid/lectura

Modelo de Datos Genérico

Estructura de Lectura RFID

interface RFIDReading {
  id: string;                    // ID único de la integración externa
  evento: RFIDEvento;            // Tipo de operación (number)
  deviceId: string;              // ID del dispositivo como string
  clientId: number;              // ID del cliente/empresa
  depositoId?: number;            // ID del depósito de Ninox (numérico)
  timestamp: string;             // ISO 8601
  notes?: string;                // Observaciones opcionales
  items: RFIDItem[];             // Array de items leídos
  transaccionId?: number;        // ID de transacción interna (para confirmaciones)
}

interface RFIDItem {
  sku: string;                   // SKU del producto (clave principal)
  descripcion?: string;          // Descripción del producto
  epc: string;                   // Electronic Product Code
  tid: string;                   // Tag Identifier
  quantity: number;              // Cantidad
  assetId?: string;              // ID del activo como string
}

enum RFIDEvento {
  COMPRA_PROVEEDOR = 1,          // Compra a proveedor
  INGRESO_MANUAL = 2,            // Ingreso manual de stock
  FABRICA_A_SUCURSAL = 3,        // Fábrica → Sucursal
  FABRICA_A_TALLER = 4,          // Fábrica → Taller
  TALLER_A_FABRICA = 5,          // Taller → Fábrica
  VENTA = 6,                     // Venta
  EGRESO_MANUAL = 7              // Egreso manual
}

enum RFIDStatus {
  ERROR = 0,                     // Error en procesamiento
  OK = 1,                        // Procesado correctamente
  VALIDACION = 2                 // En proceso de validación
}

Flujo de Integración

1. Lectura Borrador (RFID → ERP)

// POST /integraciones/rfid/lectura
{
  "id": "rfid_001_20250814_1234",
  "evento": 6,                   // VENTA
  "deviceId": "POS_001",
  "clientId": 1,
  "depositoId": 15,              // Numérico
  "timestamp": "2025-08-14T15:30:00Z",
  "items": [
    {
      "sku": "PROD001",
      "descripcion": "Remera Básica Blanca",
      "epc": "1B000A00000000000000000011",
      "tid": "E280116020006092A4CD0B36",
      "quantity": 1,
      "assetId": "ASSET_123"
    }
  ]
}

2. Webhook de Confirmación (Ninox → Integración)

// POST {endpoint_personalizado_por_integracion}
// Headers personalizables por integración
{
  "id": "rfid_001_20250814_1234",        // ID original
  "evento": 6,                           // VENTA
  "transaccionId": 789456123,            // ID transacción interna (number)
  "timestamp": "2025-08-14T15:35:00Z",
  "status": 1                            // OK
}

Casos de Uso por Módulo

Módulo	Evento	Código	Origen	Destino	Flujo
Compras	COMPRA_PROVEEDOR	1	Proveedor	Almacén	Lectura → Confirmación → Actualizar stock
Stock Manual	INGRESO_MANUAL	2	-	Almacén	Lectura → Confirmación → Incrementar stock
Fábrica-Sucursal	FABRICA_A_SUCURSAL	3	Fábrica	Sucursal	Lectura → Confirmación → Transferir stock
Fábrica-Taller	FABRICA_A_TALLER	4	Fábrica	Taller	Lectura → Confirmación → WIP
Taller-Fábrica	TALLER_A_FABRICA	5	Taller	Fábrica	Lectura → Confirmación → Producto terminado
Ventas	VENTA	6	Stock	Cliente	Lectura → Precargar POS → Confirmación → Reducir stock
Egresos	EGRESO_MANUAL	7	Almacén	-	Lectura → Confirmación → Reducir stock

Endpoints API

Lecturas RFID

POST   /integraciones/rfid/lectura      // Crear lectura borrador (relativo a la base URL)

Webhooks (Configurables por Integración)

POST   {endpoint_personalizado}         // Confirmación de Ninox
// Headers: Personalizables según integración
// Content-Type: application/json
// Authorization: Bearer {token} (si es requerido)
// X-Custom-Header: {valor} (headers adicionales)

Endpoints en Desarrollo

// Próximamente disponibles:
GET    /integraciones/rfid/articulos    // Sincronizar artículos
GET    /integraciones/rfid/clientes     // Sincronizar clientes  
GET    /integraciones/rfid/depositos    // Sincronizar depósitos

Configuración de Webhooks por Integración

La configuración de webhooks no puede realizarse vía API. Si tu integración requiere recibir confirmaciones desde Ninox, por favor informa al equipo de Ninox o al contacto de soporte la siguiente información:

• URL de destino donde se recibirán los webhooks (endpoint HTTPS).
• Headers personalizados que Ninox deberá incluir en las llamadas (por ejemplo: Authorization, X-Company-Id, Content-Type).

Ninox registrará manualmente esa información en la configuración de la integración y será usada para enviar los webhooks de confirmación. Asegúrate de que el endpoint acepte requests con Content-Type: application/json y que esté preparado para manejar reintentos y validaciones de idempotencia.

Sincronización Requerida con Ninox

Parámetros que deben estar sincronizados:

1. Artículos con Variantes

   • SKU
   • Descripción
   • Variantes (talle, color, etc.)
   • Estado activo/inactivo

2. Clientes

   • ID del cliente
   • Datos básicos
   • Estado activo

3. Depósitos

   • ID del depósito de Ninox (numérico)
   • Nombre y ubicación
   • Estado activo

Importante: Sin esta sincronización previa, las lecturas RFID no podrán ser procesadas correctamente.

Consideraciones Técnicas

• Idempotencia: Usar ID único para evitar duplicados
• Timeout: Lecturas sin confirmar expiran en 30 minutos
• Validación: SKU debe existir en catálogo antes de procesar
• Headers Personalizados: Cada integración puede configurar sus propios headers para webhooks