**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](https://docs.nuby.ai/ver-detalle-factura.html).
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.
```json
{
"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:
```json
"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.
**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`.
- `El parámetro "page_size" debe ser un número positivo.`
- `El parámetro "page" debe ser un número positivo.`
- `El parámetro "estado" debe ser uno de los siguientes valores: 1 (Facturada), 2 (Anulada), 3 (Pagada), 5 (Borrador), 6 (Anulada por NC).`
- `El parámetro "resolucion_id" debe contener solo IDs numéricos enteros positivos separados por coma (ej: 1,2,3).`
- `El parámetro "resolucion_id" no contiene IDs válidos.`
- `Ninguna de las resoluciones enviadas existe en el sistema.`
**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`.
cURL
```bash
# 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
```php
$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";
}
```
Python
```python
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
```
JavaScript (Fetch API)
```javascript
// 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}`
);
});
});
```
Power Query M (Excel / Power BI)
```m
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.
- **Usa `documento` y `estado` para acotar.** Son los filtros que más reducen el volumen de la respuesta.
- **No pidas `page_size=1000` "por si acaso".** Pagina con un tamaño razonable y recorre con `page` hasta `total_pages`.
- **Guarda el `factura_id`, no el número.** El identificador es la llave para el detalle y para el PDF; el número de factura depende de la resolución con la que se numeró el documento.
- **Recorre la paginación con `has_next_page`.** Es más robusto que comparar `current_page` con `total_pages`, porque no depende del tamaño de página que hayas pedido.
- **Interpreta `warnings[]` como información, no como falla.** Si aparece `FACTURAS_CONTRATO_EXCLUIDAS`, el listado simplemente descartó documentos de contrato.
- **Comprueba `total_records` antes de asumir un vacío.** Una lista vacía con `total_records: 0` significa que no hubo coincidencias; con `total_records > 0`, significa que pediste una página fuera de rango.
- **Convierte los importes explícitamente.** Si tu cliente recibe `"1190000.00"` como texto, conviértelo antes de sumar o comparar.
- **Solo lista facturas de venta.** Las facturas de contrato quedan fuera por diseño y se informan en `warnings[]`.
- **No es `GET /invoices/list`.** Ese endpoint es legacy, quedó congelado y puede devolver facturas de contrato.
- **El tamaño máximo por página es 1000.** Un valor mayor se ajusta a `1000`, no se rechaza.
- **No devuelve CUFE.** El código único de factura electrónica solo está en el [detalle](https://docs.nuby.ai/ver-detalle-factura.html).
- **Los ítems del listado no están normalizados.** Su contrato estable es el de `items` en el [detalle](https://docs.nuby.ai/ver-detalle-factura.html), donde los valores llegan convertidos a número.
- **El `pdf_link` vence a los 30 días.** Si vas a guardar el enlace, revisa su fecha de generación o pídelo de nuevo con el servicio de [PDF](https://docs.nuby.ai/obtener-pdf-factura.html).
- **No filtra por rango de fechas.** El endpoint no acepta fechas: si necesitas un periodo, recorre las páginas y filtra en tu sistema con `fecha_factura`.
- **No ordena por otro criterio.** El orden es fijo (fecha descendente, identificador descendente) y no se puede cambiar con parámetros.
**Siguiente paso:** cuando ya tengas el `factura_id`, consulta el [**detalle de la factura**](https://docs.nuby.ai/ver-detalle-factura.html) para obtener el CUFE, el estado DIAN y los ítems, o pide directamente el [**enlace del PDF**](https://docs.nuby.ai/obtener-pdf-factura.html).