Exportar compra 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: una fila por ítem de compra (artículo, cantidad, costo).
- Exportar compra totales: una fila por comprobante, sin el detalle de ítems — para quien solo necesita los totales de cabecera.
Cada fila trae el estado del comprobante (ComprobanteEstado):
un comprobante anulado sigue saliendo con estado: 3. Ver
Preventas y estado en la página de venta.
Exportar compra ítems
Trae los ítems de a páginas chicas (OFFSET/FETCH) para evitar timeouts por volumen.
/integraciones/terceros/exportar/compraitems/paginadoQuery 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 |
incluirApps | boolean | No | Si es true, completa app con el nombre del canal de origen. Omitir equivale a false |
appId | number | No | Filtra por canal de origen: el id de un canal, o -1 para traer solo los comprobantes sin canal. Cualquier otro valor responde 400. Ver Canal de origen y costos |
comprobanteTipo | string | No | Acota a uno de los ComprobanteTipo de compra: 1 (factura de compra) o 3 (nota de crédito de compra), o los dos separados por coma. Omitir equivale a 1,3. Otro valor 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.
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
estado: number; // enum ComprobanteEstado: 1 pendiente, 2 facturado, 3 anulado
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 que originó el comprobante; null si se cargó en el ERP
app?: string; // nombre del canal (solo con incluirApps=true)
proveedor: string;
empleado?: 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;
lote?: string;
cantidad: number;
costoItem: number; // costo unitario registrado en el ítem al momento del comprobante
costoArticulo: number; // costo unitario actual del artículo (se lee al consultar)
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 endpoints paginados de comprobante
(ventaitems/paginado, ventatotales/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 compraitems en paralelo con los otros.
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).
/integraciones/terceros/exportar/compratotales/paginadoQuery parameters
Idénticos a exportar/compraitems/paginado (mismos criterios de
período, sucursalId, incluirMediosPago, incluirApps, appId, comprobanteTipo, 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
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; // canal de origen; null si se cargó en el ERP
app?: string; // nombre del canal (solo con incluirApps=true)
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,
ventatotales/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 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"
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
- Exportar venta — mismo patrón de paginado, del lado de ventas.
- Exportar gastos — el reporte del módulo Gastos, paginado.
- Enums y códigos —
ComprobanteTipo,ComprobanteEstado,TipoDocumento,TipoMedio. - Esquema de datos — contratos completos.