Saltar al contenido principal

Esquema de datos

Esta página resume los contratos principales de la integración pública de terceros. Los valores de los enums que usan (TipoTalleColor, TipoTag, CondicionIva, ComprobanteTipo, ComprobanteEstado, NxTipoResultado y otros) están en Enums y códigos.

Lectura de artículos​

TipoTalleColor​

Valores en Enums y códigos › TipoTalleColor.

Articulo​

Modelo agrupado por artículo.

export interface Articulo {
  articuloId: number;
  codigo: string;
  descripcion: string;
  descripcionWeb: string;
  nombre: string;
  talleColor: TipoTalleColor;

  precio1: number;
  precio2: number;
  precio3: number;
  precio4: number;
  precio5: number;

  stockTotal: number;
  curva: ArticuloCurva[];
  tags: ArticuloTag[];
}

ArticuloCurva​

Stock por combinación de talle y color.

export interface ArticuloCurva {
  articuloId: number;
  colorId?: number;
  talleId?: number;
  colorNombre: string;
  colorCodigo: string;
  talleNombre: string;
  talleCodigo: string;
  unidades: number;

  // solo en multidepósito informativo — ver Webhooks
  stockDepositos?: StockDeposito[];
}

ArticuloConCurva​

Modelo plano, útil para sincronización y procesamiento masivo.

export interface ArticuloConCurva {
  articuloId: number;
  codigo: string;
  descripcion: string;
  descripcionWeb: string;
  nombre: string;
  talleColor: TipoTalleColor;

  precio1: number;
  precio2: number;
  precio3: number;
  precio4: number;
  precio5: number;

  colorId?: number;
  talleId?: number;
  colorNombre: string;
  colorCodigo: string;
  colorHex: string;
  talleNombre: string;
  talleCodigo: string;

  unidades: number;

  // solo en multidepósito informativo — ver Webhooks
  stockDepositos?: StockDeposito[];

  etiquetasIds: string;
  etiquetasNombres: string;
  categoriasIds: string;
  categoriasNombres: string;
  eliminado: boolean;
}

StockDeposito​

Stock desglosado por depósito. Solo viaja si la integración está en modo multidepósito informativo; ver Webhooks.

export interface StockDeposito {
  depositoId: number;
  unidades: number;
}
aviso

Cuando este campo viene, unidades es el stock del depósito principal, no la suma del array.

Recomendación

Para nuevas integraciones suele ser más simple comenzar con ArticuloConCurva, porque cada variante queda representada como un registro independiente.

Etiquetas y categorías​

TipoTag​

Valores en Enums y códigos › TipoTag.

ArticuloTag​

export interface ArticuloTag {
  articuloId: number;
  articuloTagId: number;
  tipo: TipoTag;
  tagId: number;
  tagNombre: string;
  padreId?: number;
  destacada: boolean;
}
Nota

En NinoxNet, categorías y etiquetas forman parte del mismo sistema de tags. La distinción se hace mediante el campo tipo.

Pedidos​

CondicionIva​

Valores en Enums y códigos › CondicionIva.

PedidoTerceros​

export interface PedidoTerceros {
  ordenId: number;
  numero: number;
  detalle: string;

  direccionEnvio: DireccionTerceros;
  direccionFacturacion: DireccionTerceros;

  productos: ArticuloTerceros[];

  // Requerido salvo que mandes entidadId: identifica o crea al cliente
  // (dni → cuit → email → alta automática).
  usuario?: UsuarioTerceros;

  subtotal: number;
  descuento: number;
  envio: number;
  recargo: number;
  total: number;

  // Lista de precios del pedido. Opcional: si no viene, se usa la de tu integración.
  listaPrecioId?: number;

  // Si el pedido ya está cobrado. Opcional (por defecto false). Con pagado: true y
  // medioPago, el pedido queda en estado PAGADO; si no, queda PENDIENTE.
  // Ver /docs/terceros/pedidos#estado-del-pedido.
  pagado?: boolean;

  // Medio de pago. Opcional. Ver MedioPagoTerceros y TipoMedio en
  // /docs/terceros/ventas-beta#venta-directa.
  medioPago?: MedioPagoTerceros;

  // Vendedor del comprobante: el id de un empleado, obtenido de GET /empleados.
  // Opcional. Pisa al vendedor por defecto de la integración.
  empleadoId?: number;

  // Cliente explícito: el id de una entidad ya existente en NinoxNet, obtenido
  // de GET /entidades. Opcional. Si lo mandás, se usa esa entidad directo y
  // NO se busca por documento/cuit/email ni se crea un cliente nuevo — usuario
  // pasa a ser opcional. Debe ser un cliente activo; un id inválido responde 403.
  entidadId?: number;
}
Uno de los dos es obligatorio

Tenés que mandar entidadId o usuario con al menos uno de dni, cuit o email. Sin ninguno de los dos, la API responde 400.

DireccionTerceros​

export interface DireccionTerceros {
  provincia: string;
  localidad: string;
  direccion: string;
  codigoPostal: string;
}

UsuarioTerceros​

export interface UsuarioTerceros {
  nombre: string;
  email: string;
  dni: string;
  cuit: string;
  telefono: string;
  condicion: CondicionIva;
}

ArticuloTerceros​

export interface ArticuloTerceros {
  articuloId: number;
  precio: number;
  talleId?: number;
  colorId?: number;
  cantidad: number;
}
Comportamiento operativo

Un pedido enviado por integración queda siempre dentro de la configuración del token asociado: se registra en el depósito y el punto de venta configurados en tu integración.

Respuestas​

PedidoResultado​

export interface PedidoResultado {
  facturaId: number;
  numero: number;
  pVNumero: number;
  sref: string;
  estado: number;               // en el alta y la actualización de un pedido viene en 0;
                                // el estado real sale de GET /comprobante/{id}

  datos: { [key: string]: string };

  electronica: boolean;
  cae: string;
  caevencimiento: string;
  resultado: string;
  observaciones: string;
  errorFE: string;

  saldo?: number;
  errores: boolean;
}

NxResultado​

// NxTipoResultado: ver Enums y códigos (0 = ERROR, 1 = OK, 2 = VALIDACION)
export class NxResultado {
  tipo: NxTipoResultado;
  id: number;
  data: object;
  valores: string[];
  mensajes: string[];
  errores: string[];
}

Comprobante​

Lo que devuelve GET /comprobante/{id}.

comprobanteTipo es 2 (venta), 4 (nota de crédito) o 33 (preventa), y estado es un ComprobanteEstado. Valores en Enums y códigos.

export interface Comprobante {
  facturaId: number;
  ordenId: string;              // el ordenId con el que lo creaste
  comprobanteTipo: ComprobanteTipo;
  estado: ComprobanteEstado;

  numero: number;
  pVNumero: number;
  fecha?: string;

  sucursalId: number;
  puntoVentaId: number;
  empleadoId?: number;

  sref: string;                 // CAE, si es electrónica

  cliente: ComprobanteCliente;
  totales: ComprobanteTotales;
  items: ComprobanteItem[];
  mediosPago: ComprobanteMedioPago[];
}
Estados del comprobante

ComprobanteEstado lista los estados que podés provocar desde la API (ver Estado del pedido). Un comprobante que además se gestiona dentro de NinoxNet puede mostrar otros valores numéricos.

export interface ComprobanteCliente {
  entidadId: number;
  nombre: string;
  razonSocial: string;          // razón social fiscal, si difiere del nombre
  dni: string;
  cuit: string;
  email: string;
  condicionIva: CondicionIva;
}
Los datos salen de la ficha viva del cliente

El bloque cliente se arma leyendo la ficha de la entidad en el momento de la consulta, no una copia congelada al momento de emitir el comprobante. Si alguien corrige el CUIT o el mail del cliente en el ERP, la próxima consulta del mismo comprobante ya devuelve el dato corregido.

Un comprobante viejo sigue mostrando su cliente aunque después lo hayan dado de baja en el ERP.

export interface ComprobanteItem {
  articuloId: number;
  descripcion: string;
  talleId?: number;
  colorId?: number;
  cantidad: number;
  precio: number;
  subtotal: number;
}
export interface ComprobanteTotales {
  subTotal: number;
  descuento: number;
  recargo: number;
  envio: number;
  total: number;
  pagado: number;
  saldo: number;                // pendiente del comprobante
}
export interface ComprobanteMedioPago {
  tipo: TipoMedio;
  importe: number;
  tarjetaId?: number;
  cuentaBancariaId?: number;
}

Empleado​

Lo que devuelve GET /empleados.

export interface Empleado {
  empleadoId: number;           // id de la entidad; es el que va en empleadoId del body
  nombre: string;
}

PuntoVenta​

Lo que devuelve GET /puntos-venta.

export interface PuntoVenta {
  puntoVentaId: number;
  descripcion: string;
  numero: number;
  cajaId: number;
  depositoId: number;
  sucursalId: number;
  default: boolean;             // true = el configurado en tu integración
}

Recomendaciones de modelado​

Si vas a construir tu propia app o middleware, lo más práctico es mapear internamente:

  • una entidad de producto base
  • una entidad de variante
  • stock por variante
  • categorías y etiquetas normalizadas
  • una tabla o colección de sincronizaciones
  • una tabla o colección de pedidos enviados con clave idempotente

Esto te deja preparado para la evolución del contrato a medida que se agreguen nuevos endpoints.