Saltar al contenido principal

Exportaciones BETA

Endpoints para exportar datos del ERP hacia sistemas externos. A diferencia de los endpoints de lectura incremental, las exportaciones devuelven volúmenes mayores en un único request y están pensadas para sincronizaciones batch.

Endpoints en beta

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

Bucket compartido de rate limit

Todas las exportaciones (exportar/clientes, exportar/ventaitems, exportar/stock, exportar/saldos/*) comparten la ventana de rate limit por tenant: 10 minutos en producción (3 minutos en test). Solo se puede ejecutar una exportación dentro de la ventana. Ver Alcance y límites.

Excepción: los cuatro endpoints paginados de comprobante — exportar/ventaitems/paginado, exportar/ventatotales/paginado, exportar/compraitems/paginado y exportar/compratotales/paginado — comparten entre sí un único bucket corto (30 s en producción / 3 s en test), separado de la ventana de 10 minutos de las exportaciones masivas. Pegan contra la misma familia de tablas (comprobantes/ítems), así que solo una request de exportación paginada de comprobante — venta o compra, ítems o totales — puede estar "enfriándose" a la vez; no se puede recorrer los cuatro en paralelo.

Sucursales habilitadas

Las exportaciones solo devuelven datos de las sucursales habilitadas para tu integración. Las habilita el administrador del ERP desde Configuración › Canales › tu integración.

Si no hay ninguna habilitada, los endpoints responden 403 Forbidden. Consultá cuáles tenés disponibles en GET /integraciones/terceros/config → sucursalesExportacion, y usá esos sucursalId.

Aplica a exportar/ventaitems, exportar/ventaitems/paginado, exportar/ventatotales/paginado, exportar/compraitems/paginado, exportar/compratotales/paginado, exportar/saldos/*, exportar/stock, los endpoints de saldos/* y POST /stock/movimiento. exportar/clientes no está alcanzado: los clientes no tienen dimensión de sucursal.

GET /depositos también se acota a las sucursales habilitadas, pero no devuelve 403: si no hay ninguna, cae a los depósitos configurados en tu canal para no romper el flujo de pedidos y stock.

En esta sección​

Exportar clientes​

Devuelve la base completa de clientes en un único request. Pensado para sincronización inicial o refresh periódico de la base de clientes hacia un sistema externo.

GETBETA/integraciones/terceros/exportar/clientes

Query parameters​

ParámetroTipoRequeridoDescripción
versionMayornumberNoSolo trae clientes modificados con version mayor a este valor. Útil para sincronización incremental.

Respuesta​

export interface EntidadPage {
  total: number;
  page: number;
  pageSize: number;
  data: Entidad[];
}

El detalle de Entidad está en Esquema de datos.

Límite de registros por plan​

PlanLímite
Comercio6.000 clientes
Empresa7.000 clientes
Corporativo7.000 clientes
Otros5.000 clientes

Si tu base de clientes supera el límite del plan, usá versionMayor para exportar en pasadas incrementales, o combiná con GET /entidades para recorrer la base paginada.

Sincronización incremental con versionMayor​

El campo version de cada entidad crece cada vez que el cliente se modifica. Para sincronizar solo los cambios desde la última exportación:

  1. En la primera exportación, guardar la version más alta del resultado.
  2. En la siguiente llamada, enviar ese valor como versionMayor.
  3. El endpoint devuelve solo los clientes modificados después de esa versión.
# Primera exportación completa
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/clientes' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Exportación incremental — solo modificados desde version 18000
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/clientes?versionMayor=18000' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Rate limiting​

Bucket compartido de exportaciones: 10 minutos en producción, 3 minutos en test. 403 Forbidden si se consulta antes de que pase la ventana.

Ver también​