Saltar al contenido principal

Exportar saldos BETA

Endpoints en beta

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

Cambio de comportamiento en sucursalId

sucursalId era opcional y, si se omitía, el reporte devolvía todas las sucursales del tenant. Ahora los saldos se acotan a las sucursales habilitadas para tu integración:

  • sin sucursales habilitadas → 403;
  • sucursalId de una sucursal no habilitada → 403;
  • sucursalId omitido y una sola sucursal habilitada → se asume esa;
  • sucursalId omitido y varias habilitadas → 403 indicando cuáles.

Si tu integración omitía el parámetro, pasá a enviarlo explícitamente.

Exportar saldos de clientes​

Exporta el reporte paginado de saldos vencidos de clientes, con detalle por tramo de antigüedad (15, 30, 60, 90 y más de 90 días). Útil para sincronizar deuda de clientes hacia un sistema externo de cobranzas, BI o credit scoring.

GETBETA/integraciones/terceros/exportar/saldos/clientes

Query parameters​

ParámetroTipoRequeridoDescripción
monedaIdnumberNoID de la moneda a filtrar. 0 o ausente devuelve todas
tbnbooleanNoSi la cuenta está separada (solo si SepararCuentas está habilitado)
sucursalIdnumberSíID de la sucursal a filtrar. Debe ser una de las sucursales habilitadas. Solo se puede omitir si tenés una sola habilitada (se asume esa); con varias, omitirlo responde 403 listándolas
empleadoIdnumberNoID de un empleado/vendedor específico
empleadosIdstringNoLista de IDs de empleados separados por coma. Ej: 12,34,56
categoriasstringNoLista de IDs de categorías/tags de cliente separados por coma. Si se pasan varias, se exigen todas
searchstringNoTexto libre para buscar por nombre del cliente
pagenumberNoNúmero de página, base 1. Default 1
pageSizenumberNoTamaño de página. Default 25, máximo 100
orderColumnstringNoColumna para ordenar: nombre, saldo, saldo15, saldo30, saldo60, saldo90, saldo90mas. Default nombre
orderDirectionstringNoasc o desc. Default asc

Respuesta​

export interface SaldoVencidoPaginadoResult {
  saldos: SaldoVencidoItem[];
  totalRegistros: number;
  totalFiltrados: number;
  saldoTotal: number;
  saldo15Total: number;
  saldo30Total: number;
  saldo60Total: number;
  saldo90Total: number;
  saldo90MasTotal: number;
}

export interface SaldoVencidoItem {
  entidadId: number;
  nombre: string;
  razonSocial?: string;
  contacto?: string;
  categorias?: string;
  direccion?: string;
  otrosDatos?: string;

  saldo: number;
  cantidadFacturas: number;

  saldo15: number;
  saldo30: number;
  saldo60: number;
  saldo90: number;
  saldo90Mas: number;

  fechaSaldo15?: string;
  fechaSaldo30?: string;
  fechaSaldo60?: string;
  fechaSaldo90?: string;
  fechaSaldo90Mas?: string;

  diasSaldo15?: number;
  diasSaldo30?: number;
  diasSaldo60?: number;
  diasSaldo90?: number;
  diasSaldo90Mas?: number;

  totalUltimoPago: number;
  fechaUltimoPago?: string;
  ultimoPago?: string;
}

Los campos saldoN y saldoNTotal representan el monto pendiente en cada tramo de antigüedad:

  • saldo15 — vencido hace menos de 15 días
  • saldo30 — entre 15 y 30 días
  • saldo60 — entre 30 y 60 días
  • saldo90 — entre 60 y 90 días
  • saldo90Mas — más de 90 días

La respuesta real del servidor puede incluir campos adicionales internos del ERP. Solo los campos listados forman parte del contrato estable; el resto puede cambiar sin aviso.

Rate limiting​

Bucket compartido de exportaciones: 10 minutos en producción (3 minutos en test). El cooldown se comparte con exportar/clientes, exportar/ventaitems, exportar/stock y exportar/saldos/proveedores. Además, el reporte tiene caché interno de 5 minutos por combinación de filtros: dos requests idénticos dentro de la ventana se sirven desde caché.

Ejemplos​

# Saldos vencidos de la primera página ordenados por monto descendente
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/saldos/clientes?pageSize=100&orderColumn=saldo&orderDirection=desc' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Saldos vencidos de una sucursal puntual, filtrados por categoría
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/saldos/clientes?sucursalId=1&categorias=12,34' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Exportar saldos de proveedores​

Mismo contrato que clientes, pero con tipo = COMPRA por defecto.

GETBETA/integraciones/terceros/exportar/saldos/proveedores

Query parameters​

ParámetroTipoRequeridoDescripción
monedaIdnumberNoID de la moneda a filtrar. 0 o ausente devuelve todas
tbnbooleanNoSi la cuenta está separada (solo si SepararCuentas está habilitado)
sucursalIdnumberSíID de la sucursal a filtrar. Debe ser una de las sucursales habilitadas. Solo se puede omitir si tenés una sola habilitada (se asume esa); con varias, omitirlo responde 403 listándolas
categoriasstringNoLista de IDs de categorías/tags de proveedor separados por coma
searchstringNoTexto libre para buscar por nombre del proveedor
pagenumberNoNúmero de página, base 1. Default 1
pageSizenumberNoTamaño de página. Default 25, máximo 100
orderColumnstringNoColumna para ordenar (igual que clientes). Default nombre
orderDirectionstringNoasc o desc. Default asc

Los parámetros empleadoId y empleadosId son aceptados pero no tienen efecto sobre el reporte de proveedores.

Respuesta​

Mismo contrato que exportar saldos de clientes: SaldoVencidoPaginadoResult.

Ejemplos​

# Saldos vencidos a proveedores, top 50 por monto
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/saldos/proveedores?pageSize=50&orderColumn=saldo&orderDirection=desc' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

# Saldos vencidos a proveedores filtrados por moneda
curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/exportar/saldos/proveedores?monedaId=1' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Ver también​