Exportar venta BETA

Endpoints en beta

Pueden cambiar de contrato, comportamiento o ser retirados antes de su release definitivo.

Exportan los ítems de ventas realizadas en un período. Útiles para sincronizar movimientos de venta hacia un sistema de BI, contabilidad o ERP externo.

Hay tres variantes:

Exportar ventas paginado — una fila por ítem, recomendado para automatizaciones y meses completos.
Exportar ventas totales — una fila por comprobante, sin el detalle de ítems, para quien solo necesita los totales de cabecera.
Exportar ventas — endpoint no paginado, útil para días o rangos cortos explorados interactivamente.

Exportar ventas paginado Recomendado

Trae los ítems de a páginas chicas (OFFSET/FETCH) para evitar timeouts por volumen. Usá este endpoint para automatizaciones y batches desatendidos.

GETBETA/integraciones/terceros/exportar/ventaitems/paginado

Query parameters

Parámetro	Tipo	Requerido	Descripción
`sucursalId`	`number`	Sí	ID de la sucursal a exportar. Debe ser una de las sucursales habilitadas para tu integración; si no, responde `403`
`desde` + `hasta`	`string`	Uno de los tres grupos	Rango de fechas en formato `YYYY-MM-DD`. Máximo 30 días entre `desde` y `hasta`
`fecha`	`string`	Uno de los tres grupos	Fecha específica `YYYY-MM-DD` (equivale a `desde=fecha&hasta=fecha`)
`anio` + `mes`	`string`	Uno de los tres grupos	Año `YYYY` y mes `MM`. Exporta el mes completo sin límite de 30 días
`incluirMediosPago`	`boolean`	No	Si es `true`, incluye detalle de medios de pago (resuelto sobre los FacturaIds de la página). Omitir equivale a `false`
`page`	`number`	No	Número de página base `1`. Default `1`
`pageSize`	`number`	No	Tamaño de página. Default `25`, máximo `500` (valores mayores se recortan a 500)

Se requiere exactamente uno de los tres grupos de período, además de sucursalId. Precedencia cuando se envían varios: desde+hasta > fecha > anio+mes.

Límite de 30 días para el rango desde/hasta

Si enviás desde y hasta, el rango no puede superar los 30 días. Para períodos mayores, usá anio+mes (que exporta el mes completo) o paginá en ventanas de 30 días.

Respuesta

export interface VentaItemsPaginadoResult {
  items: VentaItem[];
  totalRegistros: number;  // total de ítems del período (una fila por ítem de comprobante)
  totalPaginas: number;
  paginaActual: number;
  pageSize: number;
}

Para recorrer todo el período: pedí page=1, leé totalPaginas en la respuesta y continuá con page=2, 3, … hasta completar. El orden es estable entre páginas (sin solapamiento).

Rate limiting

Bucket corto y compartido con los otros tres endpoints paginados de comprobante (ventatotales/paginado, compraitems/paginado, compratotales/paginado), separado del de exportaciones masivas: 30 segundos en producción (3 segundos en test). Pensado para poder recorrer todas las páginas de corrido sin chocar con la ventana de 10 minutos del resto de exportaciones. Como el bucket es compartido, no se puede paginar ventaitems en paralelo con los otros tres — ver la nota de Exportaciones.

Ejemplos

# Primera página (50 ítems) de un mes completo, con medios de pago
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=1&anio=2026&mes=04&page=1&pageSize=50&incluirMediosPago=true' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Página siguiente
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=1&anio=2026&mes=04&page=2&pageSize=50' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Rango de 15 días (desde/hasta), primera página
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=1&desde=2026-06-01&hasta=2026-06-15&page=1&pageSize=100' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Exportar ventas totales

Igual que el endpoint de arriba, pero una fila por comprobante (sin el detalle de ítems): trae los totales de cabecera. Útil cuando no necesitás el desglose por artículo — el volumen de datos es mucho menor para el mismo período (totalRegistros de este endpoint es menor o igual al de ventaitems/paginado, ya que un comprobante puede tener varios ítems).

GETBETA/integraciones/terceros/exportar/ventatotales/paginado

Query parameters

Idénticos a exportar/ventaitems/paginado (mismos criterios de período, sucursalId, incluirMediosPago, page y pageSize).

Respuesta

export interface VentaTotalesPaginadoResult {
  items: VentaTotal[];
  totalRegistros: number;  // total de comprobantes del período (una fila por factura)
  totalPaginas: number;
  paginaActual: number;
  pageSize: number;
}

export interface VentaTotal {
  facturaId: number;
  comprobanteTipo: number;        // enum ComprobanteTipo: 2 = factura venta, 4 = NC venta
  tipoDocumento: number;          // enum TipoDocumento
  fecha: string;
  fechaText: string;              // "YYYY-MM-DD"
  horaText: string;               // "HH:mm:ss"
  numeroFull: string;
  sucursalId: number;
  sucursal: string;
  appId?: number;
  app?: string;                   // solo con incluirApps
  cliente: string;
  vendedor?: string;
  detalle?: string;
  subTotal: number;
  total: number;
  descuento: number;
  recargo: number;
  iva: number;
  impuestosTotal: number;
  cantidad: number;               // suma de cantidades de todos los ítems del comprobante
  formasPagoText?: string;        // solo con incluirMediosPago
  formasPago?: VentaFormaPago[];  // solo con incluirMediosPago
}

Rate limiting

Comparte el mismo bucket corto que ventaitems/paginado, compraitems/paginado y compratotales/paginado: 30 segundos en producción (3 segundos en test). No podés recorrer ítems y totales del mismo período en paralelo — el bucket es único entre los cuatro endpoints paginados de comprobante.

Ejemplos

# Totales de venta de un mes completo
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventatotales/paginado?sucursalId=1&anio=2026&mes=04&page=1&pageSize=100' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Exportar ventas

Descarga todos los ítems del período en un único response JSON. Tiene un tope de 10.000 ítems por request. Para volúmenes mayores o automatizaciones, usá el endpoint paginado de arriba.

GETBETA/integraciones/terceros/exportar/ventaitems

Query parameters

Parámetro	Tipo	Requerido	Descripción
`sucursalId`	`number`	Sí	ID de la sucursal a exportar. Debe ser una de las sucursales habilitadas para tu integración; si no, responde `403`
`desde` + `hasta`	`string`	Uno de los tres grupos	Rango de fechas en formato `YYYY-MM-DD`. Máximo 30 días
`fecha`	`string`	Uno de los tres grupos	Fecha específica `YYYY-MM-DD`
`anio` + `mes`	`string`	Uno de los tres grupos	Año `YYYY` y mes `MM`
`incluirMediosPago`	`boolean`	No	Si es `true`, incluye el detalle de medios de pago por venta. Omitir equivale a `false`

Precedencia cuando se envían varios grupos: desde+hasta > fecha > anio+mes.

Límites de este endpoint

Rango desde/hasta: no puede superar los 30 días (HTTP 400 si se excede).
Tope de registros: el servidor hace un COUNT(*) previo. Si el período supera 10.000 ítems, devuelve HTTP 400 indicando que uses el endpoint paginado. Esta validación no genera alertas internas (no es un error del sistema).

Respuesta

Devuelve un array de VentaItem (una fila por ítem de comprobante; un comprobante con varias líneas genera varias filas).

export interface VentaItem {
  facturaId: number;
  comprobanteTipo: number;        // enum ComprobanteTipo
  tipoDocumento: number;          // enum TipoDocumento
  fecha: string;                  // fecha+hora del comprobante
  fechaText: string;              // "YYYY-MM-DD"
  horaText: string;               // "HH:mm:ss"
  numeroFull: string;             // ej. "0001-00000041"
  sucursalId: number;
  sucursal: string;
  appId?: number;                 // canal/app de origen, si aplica
  app?: string;                   // nombre del canal (solo con incluirApps)
  cliente: string;
  vendedor?: string;
  detalle?: string;               // observación del comprobante
  codigo: string;                 // código del artículo
  descripcion: string;
  talle?: string;
  color?: string;
  cantidad: number;
  costoItem: number;
  costoArticulo: number;
  precioVenta: number;
  precioVentaFinal: number;
  precioLista1: number;
  precioLista2: number;
  formasPagoText?: string;        // solo con incluirMediosPago
  formasPago?: VentaFormaPago[];  // solo con incluirMediosPago
}

export interface VentaFormaPago {
  facturaId: number;
  tipo: number;        // enum TipoMedio
  tipoText: string;    // ej. "Efectivo", "Cuenta Corriente"
  detalle?: string;
  importe: number;
}

Rate limiting

Bucket compartido de exportaciones: 10 minutos en producción (3 minutos en test).

Ejemplos

# Exportar ventas de un día específico
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems?sucursalId=1&fecha=2026-05-07' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Exportar ventas de un mes completo con medios de pago
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems?sucursalId=1&anio=2026&mes=04&incluirMediosPago=true' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Exportar ventas de un rango de 7 días
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems?sucursalId=1&desde=2026-06-01&hasta=2026-06-07' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Automatización con cron

Para sincronizar ventas de forma periódica sin intervención manual, la estrategia recomendada es un job que corra diariamente y llame al endpoint paginado recorriendo todas las páginas.

#!/bin/bash
# sync-ventas.sh — sincroniza ventas del dia anterior con ventana de 30 s entre páginas

SUCURSAL_ID=1
TOKEN="tu_token_aqui"
BASE_URL="https://api.test-ninox.com.ar"

# Fecha de ayer en YYYY-MM-DD
FECHA=$(date -d "yesterday" +%Y-%m-%d)

PAGE=1
TOTAL_PAGINAS=1

while [ "$PAGE" -le "$TOTAL_PAGINAS" ]; do
  RESPONSE=$(curl --silent --request GET \
    --url "${BASE_URL}/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=${SUCURSAL_ID}&fecha=${FECHA}&page=${PAGE}&pageSize=200" \
    --header "X-NX-TOKEN: ${TOKEN}")

  TOTAL_PAGINAS=$(echo "$RESPONSE" | jq '.totalPaginas')

  echo "Página $PAGE / $TOTAL_PAGINAS procesada"

  # Aquí: parsear $RESPONSE e insertar en tu sistema destino

  PAGE=$((PAGE + 1))

  # Respetar el rate limit: esperar 35 s entre páginas en producción (bucket 30 s)
  if [ "$PAGE" -le "$TOTAL_PAGINAS" ]; then
    sleep 35
  fi
done

echo "Sync de ventas $FECHA completado"

Para meses completos, reemplazá el parámetro fecha por anio y mes:

# Mes completo: anio + mes (sin límite de 30 días, sin tope de 10.000 registros)
ANIO=2026
MES=06
URL="${BASE_URL}/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=${SUCURSAL_ID}&anio=${ANIO}&mes=${MES}&page=..."

Reintento en rate limit (HTTP 403)

Si recibís HTTP 403 con texto "Debe esperar N segundos entre cada solicitud", el job llegó antes de que expire la ventana. Esperá el tiempo indicado y reintentar.

Ver también

Exportar compra — mismo patrón de paginado, del lado de compras.
Listado paginado de clientes — recorrer clientes de a páginas.
Esquema de datos — contratos completos.

Exportar ventas paginado Recomendado​

Query parameters​

Respuesta​

Rate limiting​

Ejemplos​

Exportar ventas totales​

Query parameters​

Respuesta​

Rate limiting​

Ejemplos​

Exportar ventas​

Query parameters​

Respuesta​

Rate limiting​

Ejemplos​

Automatización con cron​

Ver también​

Exportar ventas paginado Recomendado

Query parameters

Respuesta

Rate limiting

Ejemplos

Exportar ventas totales

Query parameters

Respuesta

Rate limiting

Ejemplos

Exportar ventas

Query parameters

Respuesta

Rate limiting

Ejemplos

Automatización con cron

Ver también