Listar Facturas de Venta [BETA]

Funcionalidad en desarrollo y pruebas: este servicio está disponible en el ambiente de pruebas y todavía no debe usarse en producción. El funcionamiento, los campos y los mensajes de error pueden cambiar antes del despliegue definitivo.

Este servicio devuelve una lista paginada de las facturas de venta registradas en nuby. Cada elemento incluye el número de factura, la resolución, las fechas, el valor total, el saldo pendiente, el tercero facturado, el estado del documento, la información de la DIAN, los datos de auditoría y el enlace seguro de su PDF.

Es el listado del ciclo administrativo: aplica el predicado que excluye las facturas de contrato y avisa cuántas descartó. Si ya tienes el identificador de una factura y necesitas todos sus datos, usa el detalle; si solo necesitas el enlace de impresión, usa el de PDF.

¿Para qué sirve este servicio?
Úsalo para sincronizar la información de facturación con tu sistema externo y para alimentar cualquier proceso que necesite recorrer las facturas de venta de la inmobiliaria. Los casos de uso más frecuentes son:

1. El Endpoint (La dirección web)

Método y dirección

GET https://{{instancia}}/service/v2/public/invoices/sales/list

¿Qué debo colocar en {{instancia}}?

Es muy sencillo: corresponde a la dirección web principal que utilizas a diario para ingresar a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co. Por ejemplo, si para entrar a tu sistema escribes inmobiliaria.nuby.app en el navegador, esa será exactamente tu instancia.

Importante: no incluyas https:// ni barras diagonales (/) al final. La dirección se compone así: https:// + tu instancia + /service/v2/public/invoices/sales/list.

Encabezados requeridos

Permiso requerido (scope): catalogs:read

Este servicio es de solo lectura y exige el permiso catalogs:read en el cliente OAuth que consume la API. Si el token es válido pero al cliente le falta el permiso, la respuesta es 403 con el código RECURSO_NO_AUTORIZADO.

¿Por qué catalogs:read y no un permiso de facturas? El libro publicado de la API documenta el permiso genérico read para los endpoints de consulta anteriores (los que ya existían, como GET /invoices/list). Los endpoints nuevos del ciclo administrativo usan el permiso por recurso, y en tu cliente OAuth los permisos de consulta disponibles son catalogs:read, invoices:create, invoices:update, notes:create y third-parties:create. Como no existe un permiso de lectura propio de facturas, leer facturas se autoriza con catalogs:read: es el permiso de consulta con el que ya cuentas. Exigir uno que no está provisionado dejaría la consulta inutilizable.

Si aún no tienes un token, consulta la página Login del libro API nuby V2.

No uses GET /invoices/list para este propósito. Ese endpoint es el listado legacy y quedó congelado: conserva el comportamiento anterior y puede devolver facturas de contrato. No es la superficie de solo venta. Usa siempre GET /invoices/sales/list, que nunca incluye facturas de contrato y además te avisa cuántas descartó. El endpoint legacy sigue documentado en el libro (página Listar Facturas), pero su contrato ya no evoluciona.

2. La Petición (¿Qué debes enviarnos?)

Este servicio no requiere cuerpo en la petición. Envía el encabezado de autorización y, opcionalmente, los parámetros de consulta en la dirección (query string).

Parámetros de consulta (query string)

Todos los parámetros son opcionales. Si no envías ninguno, recibes la primera página con 10 facturas de venta.

Importante: page y page_size deben ser números positivos. Un valor en cero, negativo o con letras produce 400; no se corrige automáticamente. El servicio valida primero page_size y después page, así que si envías los dos inválidos, el mensaje será el de page_size.

Reglas de validación y mensajes exactos

Cómo se combinan los filtros

Ejemplos de petición

GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?page=2
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?page=3&page_size=100
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?estado=1
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?documento=900123456&pendientes=true
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?pendientes=true&incluir_borrador=true
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/sales/list?resolucion_id=1,2

Encabezados de una petición completa

GET /service/v2/public/invoices/sales/list?estado=1&page=1&page_size=50 HTTP/1.1
Host: mi-inmobiliaria.nuby.app
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

3. La Respuesta (¿Qué te entregaremos?)

Si tu token es válido, el sistema devuelve un objeto JSON con el estado de la respuesta, el listado de facturas en body, la información de paginación en pagination y los filtros usados en filters_applied. Los resultados están ordenados por fecha de la factura descendente (más recientes primero).

{
  "status": 200,
  "message": "",
  "body": [
    {
      "factura_id": 10231,
      "factura_numero": 1534,
      "resolucion": "FE - 18764001234567",
      "fecha_factura": "2026-10-21",
      "fecha_vencimiento": "2026-11-20",
      "valor_total": "1190000.00",
      "saldo": "1190000.00",
      "tercero_id": 4821,
      "documento_tercero": "900123456",
      "nombre_tercero": "ACME SAS",
      "tipo_documento_tercero": "NIT",
      "estado_id": 1,
      "estado": "Facturada",
      "estado_dian": "Aprobado",
      "estado_cliente_dian": "Recibida",
      "observaciones": "Factura de administración octubre 2026",
      "notas": 0,
      "creado_por": "Sandra",
      "fecha_envio_dian": "2026-10-21 08:30:15",
      "fecha_creacion": "2026-10-21 07:45:22",
      "pdf_link": "https://<dominio-publico-pdf>?hash=...",
      "detalles": [
        {
          "detalle_id": 55231,
          "producto": "ADMINISTRACION",
          "producto_tipo": null,
          "descripcion": "Administración octubre 2026",
          "contrato_id": null,
          "contrato_numero": null,
          "fecha_inicio_periodo": null,
          "fecha_fin_periodo": null,
          "cantidad": "1",
          "valor_unitario": "1000000.00",
          "iva": "190000.00",
          "por_iva": "19.00",
          "retencion": "0.00",
          "por_retencion": "0.00",
          "reteiva": "0.00",
          "por_reteiva": "0.00",
          "reteica": "0.00",
          "por_reteica": "0.00",
          "descuento": "0.00",
          "por_descuento": "0.00"
        }
      ]
    },
    {
      "factura_id": 10230,
      "factura_numero": 1533,
      "resolucion": "FE - 18764001234567",
      "fecha_factura": "2026-10-20",
      "fecha_vencimiento": "2026-11-19",
      "valor_total": "4500000.00",
      "saldo": "0.00",
      "tercero_id": 5117,
      "documento_tercero": "1098745231",
      "nombre_tercero": "JULIANA PATRICIA RÍOS MENDOZA",
      "tipo_documento_tercero": "CC",
      "estado_id": 3,
      "estado": "Pagada",
      "estado_dian": "Aprobado",
      "estado_cliente_dian": null,
      "observaciones": "",
      "notas": 1,
      "creado_por": "Sandra",
      "fecha_envio_dian": "2026-10-20 09:12:40",
      "fecha_creacion": "2026-10-20 08:03:11",
      "pdf_link": "https://<dominio-publico-pdf>?hash=...",
      "detalles": []
    }
  ],
  "pagination": {
    "total_records": 15230,
    "total_pages": 305,
    "current_page": 1,
    "page_size": 50,
    "current_page_records": 2,
    "has_next_page": true,
    "has_previous_page": false
  },
  "filters_applied": { "estado": 1 },
  "warnings": [
    {
      "code": "FACTURAS_CONTRATO_EXCLUIDAS",
      "message": "Se excluyeron 2 facturas de contrato. Esta API solo lista facturas de venta.",
      "count": 2
    }
  ]
}

Estructura principal de la respuesta

Campos de cada factura (body[])

Cada elemento del arreglo body contiene las siguientes claves:

Sobre los tipos numéricos. Los importes (valor_total, saldo) y los contadores pueden llegar como texto decimal (por ejemplo "1190000.00") o como número, según cómo esté configurada la conexión del servicio. Conviértelos explícitamente antes de sumar o comparar: no asumas que saldo es siempre un número JSON.

Campos de cada ítem (detalles[])

El listado incluye el detalle de los ítems de cada factura. Para el contrato normalizado de ítems, con los valores convertidos a número, usa el detalle de la factura.

Campos de paginación (pagination)

El objeto pagination contiene las siguientes claves:

Nota sobre facturas sin resultados

Cuando ninguna factura coincide con los filtros, el servicio responde 200 con body: [], la paginación en cero y el mensaje informativo. Una lista vacía no es un error: revisa pagination.total_records para confirmar que no hay coincidencias.

{
  "status": 200,
  "message": "No se encontraron facturas con los criterios especificados.",
  "body": [],
  "pagination": {
    "total_records": 0,
    "total_pages": 0,
    "current_page": 1,
    "page_size": 10,
    "current_page_records": 0,
    "has_next_page": false,
    "has_previous_page": false
  },
  "filters_applied": { "estado": 1 }
}

Observa que current_page y page_size conservan lo que solicitaste; lo que queda en cero es total_records, total_pages y current_page_records.

Orden de los resultados

Las facturas se devuelven ordenadas por fecha de la factura de forma descendente y, cuando dos facturas comparten fecha, por identificador descendente. Es decir: primero las más recientes y, entre las de la misma fecha, la que se registró después. La misma consulta repetida devuelve el mismo orden, así que puedes recorrer el listado con un criterio estable.

No ordenes por tu cuenta los resultados de una página para "reconstruir" el listado. La paginación se calcula con ese orden en el servidor; si reordenas en tu sistema, las páginas dejan de ser comparables. Y si los datos cambian mientras recorres las páginas (por ejemplo, porque se factura un documento nuevo), puedes ver corrimientos: recorre el listado en una ventana corta y vuelve a empezar si necesitas el corte exacto.

Advertencia FACTURAS_CONTRATO_EXCLUIDAS

El listado excluye las facturas de contrato. Cuando descarta alguna, agrega una advertencia con la cantidad para que sepas que el resultado no está incompleto por un error:

"warnings": [
  {
    "code": "FACTURAS_CONTRATO_EXCLUIDAS",
    "message": "Se excluyeron 2 facturas de contrato. Esta API solo lista facturas de venta.",
    "count": 2
  }
]

Si la clave warnings no aparece, no había facturas de contrato en el rango consultado. Su ausencia nunca significa que el filtro falló: significa que no hubo nada que descartar.

filters_applied solo publica tus filtros. El filtro que excluye las facturas de contrato es un detalle interno del alcance del endpoint y no aparece en filters_applied. Si no enviaste filtros, verás una lista vacía []; si enviaste alguno, verás un objeto con los que se aplicaron.

4. Seguridad y Posibles Errores

Tu pase tiene fecha de caducidad

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expira y el sistema te bloquea el acceso con un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que devuelve el sistema cuando el token expiró o es inválido. Esta respuesta la produce el middleware de autenticación heredado (el mismo de toda la API) y no el contrato de la operación:

{
  "statusCode": 401,
  "error": {
    "type": "SERVER_ERROR",
    "description": "JWT Token expired."
  }
}

Ojo con la forma: los errores del middleware usan statusCode y error.description, no success ni error_code. No intentes leerlos con el mismo parser de los errores de negocio. El valor de type depende del manejador de errores de la versión desplegada (el libro publicado muestra SERVER_ERROR y el manejador actual responde UNAUTHENTICATED); lo estable es statusCode y la description.

Errores del contrato de la operación

Los errores que produce la operación misma (parámetros, permisos del cliente, fallo interno) traen siempre success: false, el código HTTP, un message legible y un error_code estable:

{
  "success": false,
  "status": 400,
  "message": "El parámetro \"page\" debe ser un número positivo.",
  "error_code": "VALIDATION_ERROR"
}

Mensajes exactos de 400 VALIDATION_ERROR

La advertencia FACTURAS_CONTRATO_EXCLUIDAS no es un error: llega con 200 en warnings[] y solo informa cuántas facturas de contrato quedaron fuera del listado.

Buenas prácticas de seguridad: el token viaja en el encabezado Authorization, nunca en la dirección (query string), porque las direcciones quedan en logs y proxies. No incluyas el token en tus URLs ni en tus capturas de pantalla, y no registres datos personales de los terceros en tus logs: para trazar la consulta te basta con el factura_id.

5. Ejemplos de integración

Aquí tienes ejemplos listos para que tus desarrolladores los adapten a tu plataforma. Todos consultan el listado de solo venta y recorren la paginación.

# Sin filtros: primera página, 10 facturas
curl "https://{{instancia}}/service/v2/public/invoices/sales/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_TOKEN_AQUI"

# Página 3 con 100 registros, solo facturas pendientes de un cliente
curl -G "https://{{instancia}}/service/v2/public/invoices/sales/list" \
  --data-urlencode "page=3" \
  --data-urlencode "page_size=100" \
  --data-urlencode "pendientes=true" \
  --data-urlencode "documento=900123456" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_TOKEN_AQUI"

<?php
$instancia = 'mi-inmobiliaria.nuby.app'; // Tu dirección web completa
$token     = 'TU_TOKEN_AQUI';            // Token obtenido del servicio Login

$pagina      = 1;
$porPagina   = 100;
$facturas    = [];
$totalPaginas = 1;

do {
    $url = "https://{$instancia}/service/v2/public/invoices/sales/list?" . http_build_query([
        'page'      => $pagina,
        'page_size' => $porPagina,
        'estado'    => 1,
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        "Authorization: Bearer {$token}",
    ]);

    $respuesta = curl_exec($ch);
    $httpCode  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        echo "Error HTTP {$httpCode}: {$respuesta}\n";
        break;
    }

    $info = json_decode($respuesta, true);

    if (!empty($info['warnings'])) {
        foreach ($info['warnings'] as $advertencia) {
            echo "Aviso {$advertencia['code']}: {$advertencia['message']}\n";
        }
    }

    $facturas     = array_merge($facturas, $info['body'] ?? []);
    $totalPaginas = (int) ($info['pagination']['total_pages'] ?? 0);
    $pagina++;
} while ($pagina <= $totalPaginas);

foreach ($facturas as $factura) {
    echo "Factura {$factura['factura_numero']} - {$factura['nombre_tercero']}"
        . " - {$factura['estado']} - Total: {$factura['valor_total']}"
        . " - Saldo: {$factura['saldo']}\n";
}

import requests

# 1. Configura tus datos de acceso
instancia = "mi-inmobiliaria.nuby.app"  # Reemplaza con tu dirección web completa
token = "TU_TOKEN_AQUI"                 # Token obtenido del servicio Login

# 2. Prepara la dirección y los encabezados
url = f"https://{instancia}/service/v2/public/invoices/sales/list"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

# 3. Recorre la paginación
pagina = 1
total_paginas = 1

while pagina <= total_paginas:
    respuesta = requests.get(
        url,
        headers=headers,
        params={"page": pagina, "page_size": 100, "pendientes": "true"},
        timeout=30,
    )

    if respuesta.status_code != 200:
        print(f"Error HTTP {respuesta.status_code}: {respuesta.text}")
        break

    info = respuesta.json()
    pagination = info.get("pagination", {})
    total_paginas = pagination.get("total_pages", 0)

    for advertencia in info.get("warnings", []):
        print(f"Aviso {advertencia['code']}: {advertencia['message']}")

    for factura in info.get("body", []):
        print(
            f"#{factura['factura_numero']} - {factura['nombre_tercero']}"
            f" - {factura['estado']} - Total: {factura['valor_total']}"
            f" - Saldo: {factura['saldo']}"
        )

    pagina += 1

// 1. Configura tus datos de acceso
const instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa
const token = 'TU_TOKEN_AQUI';                // Token obtenido del servicio Login

// 2. Función que recorre todas las páginas
async function listarFacturasDeVenta() {
  const facturas = [];
  let pagina = 1;
  let totalPaginas = 1;

  while (pagina <= totalPaginas) {
    const params = new URLSearchParams({
      page: pagina,
      page_size: 100,
      estado: 1,
    });

    const url = `https://${instancia}/service/v2/public/invoices/sales/list?${params}`;

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
      },
    });

    if (!response.ok) {
      console.error(`Error HTTP ${response.status}:`, await response.text());
      return facturas;
    }

    const info = await response.json();
    totalPaginas = info.pagination?.total_pages ?? 0;

    (info.warnings ?? []).forEach((advertencia) => {
      console.warn(`Aviso ${advertencia.code}: ${advertencia.message}`);
    });

    facturas.push(...(info.body ?? []));
    pagina += 1;
  }

  return facturas;
}

// 3. Consume el listado
listarFacturasDeVenta().then((facturas) => {
  facturas.forEach((factura) => {
    console.log(
      `#${factura.factura_numero} - ${factura.nombre_tercero}` +
      ` - ${factura.estado} - Total: ${factura.valor_total} - Saldo: ${factura.saldo}`
    );
  });
});

let
    // 1. Configura tus datos de acceso
    instancia = "mi-inmobiliaria.nuby.app", // Reemplaza con tu dirección web completa
    token = "TU_TOKEN_AQUI",                // Token obtenido del servicio Login

    // 2. Prepara la dirección de la petición (máximo 1000 por página)
    url = "https://" & instancia & "/service/v2/public/invoices/sales/list?page=1&page_size=1000",

    // 3. Envía la petición GET
    response = Web.Contents(url, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ]
    ]),

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],
    pagination = jsonResponse[pagination],

    // 5. Convierte el listado en tabla
    tabla = Table.FromList(body, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"factura_id", "factura_numero", "resolucion", "fecha_factura", "fecha_vencimiento",
         "valor_total", "saldo", "tercero_id", "documento_tercero", "nombre_tercero",
         "estado", "estado_dian", "notas", "creado_por", "fecha_creacion", "pdf_link"},
        {"FacturaID", "Numero", "Resolucion", "FechaFactura", "FechaVencimiento",
         "ValorTotal", "Saldo", "TerceroID", "DocumentoTercero", "NombreTercero",
         "Estado", "EstadoDian", "Notas", "CreadoPor", "FechaCreacion", "PdfLink"}),
    tipos = Table.TransformColumnTypes(expandido, {
        {"FacturaID", Int64.Type},
        {"Numero", Int64.Type},
        {"FechaFactura", type date},
        {"FechaVencimiento", type date},
        {"ValorTotal", type number},
        {"Saldo", type number}
    }),
    // 6. El total de páginas queda disponible para repetir la consulta con page=2, page=3, ...
    totalPaginas = pagination[total_pages]
in
    tipos

Sobre Power Query M: una consulta Web.Contents devuelve una sola página. El paso anterior lee pagination.total_pages, así que puedes parametrizar el número de página en la función y combinar los resultados con Table.Combine para traer todas.

6. Buenas prácticas y límites conocidos

Recomendaciones

Límites de este servicio

Siguiente paso: cuando ya tengas el factura_id, consulta el detalle de la factura para obtener el CUFE, el estado DIAN y los ítems, o pide directamente el enlace del PDF.