Saltar al contenido principal

Exportar compra BETA

Endpoints en beta

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

Exportan los comprobantes de compra (facturas y notas de crédito de compra) de un período. Útiles para sincronizar costos y recepciones hacia un sistema de BI, contabilidad o ERP externo.

Hay dos variantes, y ambas son paginadas — a diferencia de venta, compra no tiene una variante no paginada:

Exportar compra ítems​

Trae los ítems de a páginas chicas (OFFSET/FETCH) para evitar timeouts por volumen.

GETBETA/integraciones/terceros/exportar/compraitems/paginado

Query parameters​

ParámetroTipoRequeridoDescripción
sucursalIdnumberSíID de la sucursal a exportar. Debe ser una de las sucursales habilitadas para tu integración; si no, responde 403
desde + hastastringUno de los tres gruposRango de fechas en formato YYYY-MM-DD. Máximo 30 días entre desde y hasta
fechastringUno de los tres gruposFecha específica YYYY-MM-DD (equivale a desde=fecha&hasta=fecha)
anio + messtringUno de los tres gruposAño YYYY y mes MM. Exporta el mes completo sin límite de 30 días
incluirMediosPagobooleanNoSi es true, incluye detalle de medios de pago (resuelto sobre los FacturaIds de la página). Omitir equivale a false
pagenumberNoNúmero de página base 1. Default 1
pageSizenumberNoTamañ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 CompraItemsPaginadoResult {
  items: CompraItem[];
  totalRegistros: number;  // total de ítems del período (una fila por ítem de comprobante)
  totalPaginas: number;
  paginaActual: number;
  pageSize: number;
}

export interface CompraItem {
  facturaId: number;
  comprobanteTipo: number;        // enum ComprobanteTipo: 1 = factura compra, 3 = NC compra
  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;
  depositoId?: number;
  appId?: number;                 // canal/app de origen, si aplica
  app?: string;                   // nombre del canal (solo con incluirApps)
  proveedor: string;
  empleado?: string;
  detalle?: string;               // observación del comprobante
  codigo: string;                 // código del artículo
  descripcion: string;
  talle?: string;
  color?: string;
  lote?: string;
  cantidad: number;
  costoItem: number;
  costoArticulo: number;
  precioCompra: number;
  precioCompraFinal: number;
  formasPagoText?: string;        // solo con incluirMediosPago
  formasPago?: CompraFormaPago[]; // solo con incluirMediosPago
}

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

Rate limiting​

Bucket corto y compartido con los otros tres endpoints paginados de comprobante (ventaitems/paginado, ventatotales/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 compraitems en paralelo con los otros tres.

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/compraitems/paginado?sucursalId=1&anio=2026&mes=04&page=1&pageSize=50&incluirMediosPago=true' \
  --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/compraitems/paginado?sucursalId=1&desde=2026-06-01&hasta=2026-06-15&page=1&pageSize=100' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Exportar compra 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 compraitems/paginado, ya que un comprobante puede tener varios ítems).

GETBETA/integraciones/terceros/exportar/compratotales/paginado

Query parameters​

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

Respuesta​

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

export interface CompraTotal {
  facturaId: number;
  comprobanteTipo: number;        // enum ComprobanteTipo: 1 = factura compra, 3 = NC compra
  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
  proveedor: string;
  empleado?: 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?: CompraFormaPago[]; // solo con incluirMediosPago
}

Rate limiting​

Comparte el mismo bucket corto que compraitems/paginado, ventaitems/paginado y ventatotales/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 compra de un mes completo
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/compratotales/paginado?sucursalId=1&anio=2026&mes=04&page=1&pageSize=100' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Automatización con cron​

Misma estrategia que en exportar venta: un job diario que recorra todas las páginas del endpoint paginado, respetando la ventana de rate limit entre páginas.

#!/bin/bash
# sync-compras.sh — sincroniza compras 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=$(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/compraitems/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))

  if [ "$PAGE" -le "$TOTAL_PAGINAS" ]; then
    sleep 35
  fi
done

echo "Sync de compras $FECHA completado"
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 reintentá.

Ver también​