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;
  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 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

• 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
• 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

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

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

Facturación de preventa

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