Endpoints adicionales BETA

Esta seccion documenta endpoints experimentales que extienden la integracion de terceros. Se van incorporando a medida que se completan las pruebas internas y, una vez validados, pasan a formar parte de la documentacion publica general.

Endpoints en beta

Estos endpoints estan disponibles para uso anticipado pero pueden cambiar de contrato, comportamiento o ser retirados antes de su release definitivo. No se garantiza estabilidad de interfaz hasta que salgan de beta.

Ventas

Venta directa

Permite crear una FACTURA_VENTA en forma directa, sin pasar antes por preventa.

POSTBETA/integraciones/terceros/venta

Headers

X-NX-TOKEN: tu_token
Content-Type: application/json

Request

export interface VentaTerceros extends PedidoTerceros {
  medioPago: MedioPagoTerceros;
  puntoVentaId?: number;      // si no viene o es 0, usa el configurado en el canal
}

export interface PedidoTerceros {
  ordenId: number;
  numero: number;
  detalle?: string;
  listaPrecioId?: number;     // si no viene o es 0, usa la configurada en el canal
  direccionEnvio?: DireccionTerceros;
  direccionFacturacion?: DireccionTerceros;
  usuario: UsuarioTerceros;
  productos: ArticuloExterno[];
  subtotal: number;
  descuento: number;
  recargo: number;
  envio: number;
  total: number;
}

export interface MedioPagoTerceros {
  tipo: TipoMedio;
  cuentaBancariaId?: number;  // requerido si tipo = DEPOSITO_BANCO
  tarjetaId?: number;         // requerido si tipo = TARJETA
  externalId?: string;        // requerido si tipo = VIRTUAL
}

Tipos de medio de pago

export enum TipoMedio {
  EFECTIVO = 1,
  TARJETA = 5,
  CUENTA_CORRIENTE = 6,
  DEPOSITO_BANCO = 9,
  VIRTUAL = 11,
}

Soporte real en venta

Aunque el DTO admite varios tipos, hoy POST /venta aplica el medio con el helper interno de integraciones, que solo soporta EFECTIVO, DEPOSITO_BANCO y VIRTUAL. Si se envia otro tipo, la operacion puede fallar con "El medio de pago no es compatible".

Respuesta

ajFacturaResult

Validaciones

Regla	Error
Body invalido o sin productos	`"Los datos de venta son invalidos"`
`medioPago` ausente	`"El medio de pago es requerido"`
Request duplicada dentro de 30 segundos para el mismo `ordenId`	`"La solicitud ya se esta procesando"`
Medio de pago no soportado por el helper	`"El medio de pago no es compatible"`

Notas operativas

si puntoVentaId no viene o es 0, toma el configurado en la app/canal
si listaPrecioId no viene o es 0, toma la configurada en la app/canal
el endpoint usa una ventana anti-duplicados de 30 segundos por ordenId
internamente asigna numero = ordenId

Ejemplo

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/venta \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ordenId": 12345,
    "numero": 12345,
    "detalle": "Venta directa desde sistema externo",
    "puntoVentaId": 1,
    "listaPrecioId": 3,
    "usuario": {
      "nombre": "Juan Perez",
      "email": "juan@example.com",
      "dni": "12345678",
      "telefono": "1122334455",
      "condicion": 1
    },
    "productos": [
      {
        "articuloId": 100,
        "precio": 1500.5,
        "cantidad": 2
      }
    ],
    "subtotal": 3001,
    "descuento": 0,
    "recargo": 0,
    "envio": 500,
    "total": 3501,
    "medioPago": {
      "tipo": 1
    }
  }'

Facturar preventa

Convierte una preventa existente en FACTURA_VENTA.

POSTBETA/integraciones/terceros/facturar

Headers

X-NX-TOKEN: tu_token
Content-Type: application/json

Request

export interface FacturarTerceros {
  facturaId: number;          // id de la preventa existente
  puntoVentaId: number;
  electronica: boolean;
  medioPago: MedioPagoTerceros;
}

Respuesta

ajFacturaResult

Validaciones

Regla	Error
Body invalido o `facturaId <= 0`	`"El facturaId es requerido"`
`medioPago` ausente	`"El medio de pago es requerido"`
`puntoVentaId <= 0`	`"El puntoVentaId es requerido"`
Request duplicada dentro de 30 segundos para la misma `facturaId`	`"La solicitud ya se esta procesando"`

Notas operativas

requiere que la preventa exista y este en estado PENDIENTE
si electronica = true, intenta generar factura electronica AFIP
el endpoint usa una ventana anti-duplicados de 30 segundos por facturaId
a diferencia de venta, la facturacion de preventa soporta el flujo completo de medios (EFECTIVO, TARJETA, CUENTA_CORRIENTE, DEPOSITO_BANCO, VIRTUAL)

Ejemplo

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/facturar \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "facturaId": 456,
    "puntoVentaId": 1,
    "electronica": false,
    "medioPago": {
      "tipo": 9,
      "cuentaBancariaId": 12
    }
  }'

Medios de pago

Configuracion de medios

Devuelve la configuracion de medios habilitados y los catalogos necesarios para obtener ids validos antes de llamar a venta o facturar.

GETBETA/integraciones/terceros/medios-pago

Headers

X-NX-TOKEN: tu_token
Content-Type: application/json

Respuesta

MediosPagoConfigDTO

export interface MediosPagoConfigDTO {
  medios: WMedios;
  tarjetas: TarjetaDTO[];
  tarjetasReglas: TarjetaReglaDTO[];
  cuentasBancarias: CuentaBancariaDTO[];
  bancos: BancoDTO[];
  tarjetaCreditoReglas: boolean;
  botonesRapidos: BotonRapidoConfig[];
  recargoDigitalHabilitado: boolean;
  facturaElectronicaAutomatica: boolean;
  recargosTipoMedio: RecargoTipoMedioConfig[];
}

export interface WMedios {
  efectivo: boolean;
  cuentaCorriente: boolean;
  tarjeta: boolean;
  cheque: boolean;
  tarjetaPropia: boolean;
  chequePropio: boolean;
  chequeCartera: boolean;
  deposito: boolean;
  extraccion: boolean;
  transferencia: boolean;
  virtual: boolean;
}

export interface CuentaBancariaDTO {
  cuentaBancariaId: number;
  descripcion: string;
  bancoId?: number;
  alias?: string;
  cbu?: string;
}

Uso recomendado

consultar este endpoint antes de operar con DEPOSITO_BANCO o TARJETA
tomar tarjetas[].tarjetaId para pagos con tarjeta
tomar cuentasBancarias[].cuentaBancariaId para pagos por deposito o transferencia bancaria
usar medios como capacidad disponible del tenant antes de construir el payload

Ejemplo

curl --request GET \
  --url https://api.test-ninox.com.ar/integraciones/terceros/medios-pago \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json'

Respuesta ejemplo

{
  "medios": {
    "efectivo": true,
    "cuentaCorriente": true,
    "tarjeta": true,
    "cheque": false,
    "deposito": true,
    "virtual": true
  },
  "tarjetas": [
    {
      "tarjetaId": 7,
      "nombre": "Visa"
    }
  ],
  "cuentasBancarias": [
    {
      "cuentaBancariaId": 12,
      "descripcion": "Banco Galicia - Cuenta principal",
      "bancoId": 2
    }
  ],
  "facturaElectronicaAutomatica": false
}

Stock

Movimiento de stock

Permite registrar un movimiento de stock (ingreso, egreso o transferencia) desde un sistema externo.

POSTBETA/integraciones/terceros/stock/movimiento

Headers

X-NX-TOKEN: tu_token
Content-Type: application/json

Rate limiting

Este endpoint tiene un rate limit de 3 segundos entre requests consecutivas. Si se envia una request antes de que pase la ventana, la API responde 403 Forbidden.

Request

export interface StockMovimiento {
  depositoId: number;
  motivoId: number;           // obligatorio — ver endpoint de motivos
  tipo: TipoStockTransaccion;
  fecha?: string;             // ISO 8601 — si no se envia, usa fecha actual
  detalle?: string;
  sref?: string;              // referencia externa

  // solo para transferencias
  depositoDosId?: number;     // deposito destino

  articulos: StockArticulo[];
}

export interface StockArticulo {
  articuloId: number;
  cantidad: number;
  colorId?: number;
  talleId?: number;
  precio?: number;
  detalle?: string;
  sref?: string;              // referencia externa del item
}

Tipos de transaccion

export enum TipoStockTransaccion {
  INGRESO_MANUAL = 4,
  EGRESO_MANUAL = 5,
  INGRESO_STOCK = 6,
  EGRESO_STOCK = 7,
  TRANSFERENCIA = 10,
}

Nota

Los valores mas comunes para integraciones son INGRESO_STOCK (6) y EGRESO_STOCK (7). Para transferencias entre depositos usar TRANSFERENCIA (10) junto con depositoDosId.

Respuesta

NxResultado

Validaciones

Regla	Error
`motivoId` es obligatorio y debe ser mayor a 0	`"El motivoId es obligatorio para movimientos de terceros"`
Body invalido o malformado	`403` con `"Los datos de stock recibidos son incorrectos"`
Request dentro de la ventana de rate limit (3s)	`403 Forbidden`

Ejemplo

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/stock/movimiento \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "depositoId": 1,
    "motivoId": 5,
    "tipo": 6,
    "detalle": "Ingreso desde sistema externo",
    "articulos": [
      {
        "articuloId": 100,
        "cantidad": 10,
        "colorId": 1,
        "talleId": 2
      },
      {
        "articuloId": 200,
        "cantidad": 5
      }
    ]
  }'

Motivos de stock

Devuelve los motivos disponibles para movimientos de stock. El motivoId retornado es el que debe enviarse en el endpoint de movimiento.

GETBETA/integraciones/terceros/motivos

Headers

X-NX-TOKEN: tu_token
Content-Type: application/json

Respuesta

Motivo[]

export interface Motivo {
  motivoId: number;
  nombre: string;
  creado: string;
  modificado: string;
  eliminado: boolean;
  modulos: number[];
}

Ejemplo

curl --request GET \
  --url https://api.test-ninox.com.ar/integraciones/terceros/motivos \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json'

Respuesta ejemplo

[
  {
    "motivoId": 5,
    "nombre": "Ingreso por reposicion",
    "creado": "2025-01-15T10:00:00",
    "modificado": "2025-01-15T10:00:00",
    "eliminado": false,
    "modulos": [1]
  },
  {
    "motivoId": 8,
    "nombre": "Egreso por rotura",
    "creado": "2025-02-01T12:00:00",
    "modificado": "2025-02-01T12:00:00",
    "eliminado": false,
    "modulos": [1]
  }
]

Recomendacion

Consulta este endpoint una vez y cachea los motivos localmente. No cambian con frecuencia.

Flujos recomendados

Venta directa

Consultar /integraciones/terceros/medios-pago para validar el tipo disponible y obtener ids de tarjetas o cuentas bancarias si hacen falta.
Construir el payload de venta con cliente, productos, totales y medioPago.
Enviar a /integraciones/terceros/venta.
Verificar ajFacturaResult y registrar facturaId, numero, pvNumero y errores devueltos si los hubiera.

Facturacion de preventa

Tomar el facturaId de la preventa existente.
Consultar /integraciones/terceros/medios-pago si el medio requiere ids auxiliares.
Enviar a /integraciones/terceros/facturar.
Verificar ajFacturaResult y el estado final de la factura.

Stock

Consultar /integraciones/terceros/motivos para obtener los motivos disponibles.
Elegir el motivoId que corresponda a la operacion.
Armar el payload con el deposito, tipo de transaccion, motivo y articulos.
Enviar a /integraciones/terceros/stock/movimiento.
Verificar la respuesta NxResultado; si tipo es 1 (OK), el movimiento se registro correctamente.

Nota operativa

La integracion de terceros continua en desarrollo y es esperable que en el corto plazo se sumen nuevos endpoints. Cuando un endpoint pase a ser publico, conviene mover su contrato a la documentacion principal y revisar consistencia con:

Endpoints adicionales BETA

Ventas​

Venta directa​

Headers​

Request​

Tipos de medio de pago​

Respuesta​

Validaciones​

Notas operativas​

Ejemplo​

Facturar preventa​

Headers​

Request​

Respuesta​

Validaciones​

Notas operativas​

Ejemplo​

Medios de pago​

Configuracion de medios​

Headers​

Respuesta​

Uso recomendado​

Ejemplo​

Respuesta ejemplo​

Stock​

Movimiento de stock​

Headers​

Rate limiting​

Request​

Tipos de transaccion​

Respuesta​

Validaciones​

Ejemplo​

Motivos de stock​

Headers​

Respuesta​

Ejemplo​

Respuesta ejemplo​

Flujos recomendados​

Venta directa​

Facturacion de preventa​

Stock​

Nota operativa​

Ventas

Venta directa

Headers

Request

Tipos de medio de pago

Respuesta

Validaciones

Notas operativas

Ejemplo

Facturar preventa

Headers

Request

Respuesta

Validaciones

Notas operativas

Ejemplo

Medios de pago

Configuracion de medios

Headers

Respuesta

Uso recomendado

Ejemplo

Respuesta ejemplo

Stock

Movimiento de stock

Headers

Rate limiting

Request

Tipos de transaccion

Respuesta

Validaciones

Ejemplo

Motivos de stock

Headers

Respuesta

Ejemplo

Respuesta ejemplo

Flujos recomendados

Venta directa

Facturacion de preventa

Stock

Nota operativa