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:

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.

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
incluirAppsbooleanNoSi es true, completa app con el nombre del canal de origen. Omitir equivale a false
appIdnumberNoFiltra 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
comprobanteTipostringNoAcota 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
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
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).

GETBETA/integraciones/terceros/exportar/compratotales/paginado

Query 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"
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​