Ventas BETA

Endpoints para crear ventas y facturar desde un sistema externo.

Endpoints en beta

Estos endpoints están disponibles para uso anticipado pero pueden cambiar de contrato, comportamiento o ser retirados antes de su release definitivo. No los comprometas en producción sin confirmar disponibilidad.

Venta directa

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

POSTBETA/integraciones/terceros/venta

Request

export interface VentaTerceros extends PedidoTerceros {
  medioPago: MedioPagoTerceros;
}

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 envía otro tipo, la operación puede fallar con "El medio de pago no es compatible".

Respuesta

ajFacturaResult

Validaciones

Regla	Error
Body inválido 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

el punto de venta lo toma siempre de la configuración de la integración
si listaPrecioId no viene o es 0, toma la configurada en la app/canal
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",
    "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 }
  }'

Nota de crédito

Crea una NOTACREDITO_VENTA directa. Espeja el flujo de venta: mismo payload de cliente, productos, totales y medioPago (el medio con el que se reintegra), más un campo opcional facturaRefId para vincular la nota de crédito a la venta original. El punto de venta lo toma de la configuración de la integración.

POSTBETA/integraciones/terceros/notacredito

Request

export interface NotaCreditoTerceros extends PedidoTerceros {
  medioPago: MedioPagoTerceros;
  facturaRefId?: number;      // FacturaId de la venta original a acreditar (opcional)
}

Reutiliza las interfaces PedidoTerceros y MedioPagoTerceros definidas en Venta directa.

Respuesta

ajFacturaResult

Validaciones

Regla	Error
Body inválido o sin productos	`"Los datos de la nota de credito 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"`
`facturaRefId` no corresponde a ninguna factura	`"No se encontro la venta original {id} a acreditar"`
Medio de pago no soportado por el helper	`"El medio de pago no es compatible"`

Notas operativas

el punto de venta lo toma siempre de la configuración de la integración
si listaPrecioId no viene o es 0, toma la configurada en la app/canal
facturaRefId es opcional pero recomendado: vincula la nota de crédito a la venta original, lo que habilita el saldado en cuenta corriente (en cascada) y la trazabilidad NC↔Venta
genera un ingreso de stock por los productos devueltos (no reserva stock)
usa una ventana anti-duplicados de 30 segundos por ordenId, independiente de la de venta
al igual que venta, el medio se aplica con el helper interno que hoy soporta EFECTIVO, DEPOSITO_BANCO y VIRTUAL

Ejemplo

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/notacredito \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ordenId": 12345,
    "numero": 12345,
    "detalle": "Nota de credito por devolucion",
    "listaPrecioId": 3,
    "facturaRefId": 456,
    "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

Request

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

Respuesta

ajFacturaResult

Validaciones

Regla	Error
Body inválido 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 esté en estado PENDIENTE
si electronica = true, intenta generar factura electrónica AFIP
usa una ventana anti-duplicados de 30 segundos por facturaId
a diferencia de venta, la facturación 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

Devuelve la configuración de medios habilitados y los catálogos necesarios para obtener ids válidos antes de llamar a venta o facturar.

GETBETA/integraciones/terceros/medios-pago

Respuesta

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 depósito o transferencia
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'

Flujos recomendados

Venta directa

Consultar /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 /venta.
Verificar ajFacturaResult y registrar facturaId, numero, pvNumero y errores.

Facturación de preventa

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

Nota de crédito

Tomar el facturaId de la venta original a acreditar (para facturaRefId).
Consultar /medios-pago si el medio de reintegro requiere ids auxiliares.
Construir el payload con cliente, productos a devolver, totales y medioPago.
Enviar a /notacredito.
Verificar ajFacturaResult y registrar facturaId, numero, pvNumero y errores.

Venta directa​

Request​

Tipos de medio de pago​

Respuesta​

Validaciones​

Notas operativas​

Ejemplo​

Nota de crédito​

Request​

Respuesta​

Validaciones​

Notas operativas​

Ejemplo​

Facturar preventa​

Request​

Respuesta​

Validaciones​

Notas operativas​

Ejemplo​

Medios de pago​

Respuesta​

Uso recomendado​

Ejemplo​

Flujos recomendados​

Venta directa​

Facturación de preventa​

Nota de crédito​

Venta directa

Request

Tipos de medio de pago

Respuesta

Validaciones

Notas operativas

Ejemplo

Nota de crédito

Request

Respuesta

Validaciones

Notas operativas

Ejemplo

Facturar preventa

Request

Respuesta

Validaciones

Notas operativas

Ejemplo

Medios de pago

Respuesta

Uso recomendado

Ejemplo

Flujos recomendados

Venta directa

Facturación de preventa

Nota de crédito