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. Los endpoints paginados también exportan preventas (pedidos todavía sin facturar) si las pedís con comprobanteTipo: ver Preventas y estado.

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`
`comprobanteTipo`	`string`	No	Uno o más `ComprobanteTipo` separados por coma: `2` (factura de venta), `4` (nota de crédito de venta) y `33` (preventa). Omitir equivale a `2,4`: las preventas solo salen si las pedís. Un valor no numérico o fuera de esos tres responde `400`
`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

Cada fila es un VentaItem, el mismo contrato que devuelve Exportar ventas (no paginado).

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 endpoints paginados de comprobante (ventatotales/paginado, compraitems/paginado, compratotales/paginado y gastos/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 — 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}'

# Solo los ítems de las preventas sin facturar del mes
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventaitems/paginado?sucursalId=1&anio=2026&mes=06&comprobanteTipo=33&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, comprobanteTipo, 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, 33 = preventa
  estado: number;                 // enum ComprobanteEstado: 1 pendiente, 2 facturado, 3 anulado, …
  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, compratotales/paginado y gastos/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 todos los 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}'

# Ventas, notas de crédito y preventas sin facturar, todo junto
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/ventatotales/paginado?sucursalId=1&anio=2026&mes=04&comprobanteTipo=2,4,33&page=1&pageSize=100' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Preventas y estado

Preventas

Con comprobanteTipo=33, ventaitems/paginado y ventatotales/paginado devuelven las preventas todavía sin facturar de la sucursal: los pedidos creados con POST /pedido y también los de otros canales o del punto de venta. La fecha de una preventa es la fecha del pedido.

Al facturarse, la preventa cambia de tipo

Cuando una preventa se factura, la misma fila pasa a ser una factura de venta (comprobanteTipo: 2) con el mismo facturaId y la fecha de facturación. Deja de salir con comprobanteTipo=33 y aparece entre las ventas, posiblemente en otro día.

Usá facturaId como clave en tu sistema. Si pedís 2,33 juntos para un período ya sincronizado, una venta que antes viste como preventa la vas a ver de nuevo como venta: no la sumes dos veces. Por eso las preventas no entran si no las pedís.

Estado del comprobante

Cada fila trae estado (ComprobanteEstado):

`estado`	Significa
`1`	Pendiente: la venta tiene saldo pendiente (cuenta corriente), o la preventa espera facturarse
`2`	Facturado: la venta está saldada
`3`	Anulado: la venta fue anulada, o la preventa cancelada
`100`	Procesando: preventa con un pago en curso (canales de e-commerce)
`101`	Pagado: preventa con el pago confirmado

Una venta anulada sigue saliendo en la exportación con estado: 3, así que podés detectar la anulación y revertir lo que hayas procesado. Una venta eliminada se borra del ERP y deja de aparecer: si necesitás detectarla, volvé a consultar el período y compará contra lo que ya procesaste. Una factura electrónica no se anula: se emite una nota de crédito (comprobanteTipo: 4).

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: 2 = factura venta, 4 = NC venta, 33 = preventa
  estado: number;                 // enum ComprobanteEstado (ver Preventas y estado)
  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
  articuloId: number;             // id del artículo del renglón (usalo para cruzar con tu catálogo en vez del código)
  codigo: string;                 // código del artículo
  descripcion: string;
  colorId?: number;               // id del color; solo si el artículo tiene curva (si no, llega null)
  talleId?: number;               // id del talle; solo si el artículo tiene curva (si no, llega null)
  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.
Exportar gastos — el reporte del módulo Gastos, paginado.
Listado paginado de clientes — recorrer clientes de a páginas.
Enums y códigos — ComprobanteTipo, ComprobanteEstado, TipoDocumento, TipoMedio.
Esquema de datos — contratos completos.

Exportar ventas paginado Recomendado​

Query parameters​

Respuesta​

Rate limiting​

Ejemplos​

Exportar ventas totales​

Query parameters​

Respuesta​

Rate limiting​

Ejemplos​

Preventas y estado​

Preventas​

Estado del comprobante​

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

Preventas y estado

Preventas

Estado del comprobante

Exportar ventas

Query parameters

Respuesta

Rate limiting

Ejemplos

Automatización con cron

Ver también