# Listar Facturas

Permite obtener la lista paginada de todas las facturas registradas en el sistema. Cada elemento incluye el número de factura, resolución, fechas, valor total, saldo pendiente, tercero facturado, estado, información DIAN y datos de auditoría.

<p class="callout info">**¿Para qué sirve este servicio?**  
Úsalo para sincronizar la información de facturación con tu sistema externo, generar reportes de cartera, alimentar dashboards con indicadores de facturación, validar el estado de cobro de los contratos o exportar la información a Excel y Power BI.</p>

---

#### **1. El Endpoint (La dirección web)**

Apunta tu sistema a la siguiente dirección. Recuerda reemplazar <span style="color: rgb(241, 196, 15);">**{{instancia}}**</span> por la dirección web completa que utilizas para ingresar a tu plataforma.

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

<p class="callout info">**¿Qué debes 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` o `inmobiliaria.arrendasoft.co` en tu navegador, esa será exactamente tu instancia. Solo asegúrate de no incluir el "https://" ni barras diagonales ("/") al final.</p>

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

Este servicio no requiere cuerpo en la petición. Envía los encabezados requeridos y opcionalmente los parámetros de paginación en la URL:

<table border="1" id="bkmrk-m%C3%A9todo-get-content-t" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 20%;"></col><col style="width: 80%;"></col></colgroup><tbody><tr><td>**Método**</td><td>GET</td></tr><tr><td>**Content-Type**</td><td>application/json</td></tr><tr><td>**Authorization**</td><td>**Bearer token**, Token obtenido al consumir el servicio [Login](https://docs.nuby.ai/books/api-nuby-v2/page/login "Login")</td></tr></tbody></table>

<p class="callout warning">**¿Aún no tienes tu Token de acceso?**  
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de [Login](https://docs.nuby.ai/books/api-nuby-v2/page/login) para aprender cómo obtenerlo.</p>

**Parámetros de consulta (query string):**

<table border="1" id="bkmrk-par%C3%A1metro-tipo-reque" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 16%;"></col><col style="width: 10%;"></col><col style="width: 10%;"></col><col style="width: 14%;"></col><col style="width: 50%;"></col></colgroup><thead><tr><th>Parámetro</th><th>Tipo</th><th>Requerido</th><th>Por defecto</th><th>Descripción</th></tr></thead><tbody><tr><td>`page`</td><td>integer</td><td>No</td><td>1</td><td>Número de página de resultados que se desea recuperar. Debe ser un número positivo.</td></tr><tr><td>`page_size`</td><td>integer</td><td>No</td><td>10</td><td>Número máximo de facturas por página. Debe ser un número positivo. Valor máximo permitido: **1000**.</td></tr></tbody></table>

**Ejemplos de petición:**

```http
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=2
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page_size=50
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=3&page_size=100
```

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

Si tu Token es válido, el sistema te devolverá un objeto JSON con el estado de la respuesta, el listado de facturas y la información de paginación. Los resultados están ordenados por fecha de factura descendente (más recientes primero). La respuesta se verá similar a esta:

```json
{
    "status": 200,
    "message": null,
    "body": [
        {
            "factura_id": 15230,
            "factura_numero": 8745,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-04-01",
            "fecha_vencimiento": "2025-04-06",
            "valor_total": "2850000.00",
            "saldo": "2850000.00",
            "documento_tercero": "80213654",
            "nombre_tercero": "CARLOS EDUARDO PINEDA VARGAS",
            "estado": "Facturada",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": "Recibida",
            "notas": 0,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-04-01 08:30:15",
            "fecha_creacion": "2025-04-01 07:45:22"
        },
        {
            "factura_id": 15229,
            "factura_numero": 8744,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-04-01",
            "fecha_vencimiento": "2025-04-06",
            "valor_total": "4500000.00",
            "saldo": "0.00",
            "documento_tercero": "1098745231",
            "nombre_tercero": "JULIANA PATRICIA RÍOS MENDOZA",
            "estado": "Pagada",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": "Recibida",
            "notas": 0,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-04-01 08:31:02",
            "fecha_creacion": "2025-04-01 07:46:10"
        },
        {
            "factura_id": 15210,
            "factura_numero": 8730,
            "resolucion": "0 - 18764000002851",
            "fecha_factura": "2025-03-01",
            "fecha_vencimiento": "2025-03-06",
            "valor_total": "1200000.00",
            "saldo": "1200000.00",
            "documento_tercero": "43876123",
            "nombre_tercero": "DIANA MARCELA OSPINA VELÁSQUEZ",
            "estado": "Facturada",
            "estado_dian": null,
            "estado_cliente_dian": null,
            "notas": 1,
            "creado_por": "Administrador",
            "fecha_envio_dian": null,
            "fecha_creacion": "2025-03-01 09:12:33"
        },
        {
            "factura_id": 14850,
            "factura_numero": 8520,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-02-01",
            "fecha_vencimiento": "2025-02-06",
            "valor_total": "3950000.00",
            "saldo": "3950000.00",
            "documento_tercero": "900456789",
            "nombre_tercero": "INVERSIONES HORIZONTE S.A.S.",
            "estado": "Anulada por NC",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": null,
            "notas": 1,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-02-01 10:05:44",
            "fecha_creacion": "2025-02-01 08:20:15"
        }
    ],
    "pagination": {
        "total_records": 15230,
        "total_pages": 305,
        "current_page": 1,
        "page_size": 50,
        "current_page_records": 4,
        "has_next_page": true,
        "has_previous_page": false
    }
}
```

##### **Estructura principal de la respuesta**

<table border="1" id="bkmrk-campo-tipo-descripci" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 16%;"></col><col style="width: 14%;"></col><col style="width: 70%;"></col></colgroup><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`status`</td><td>integer</td><td>Código del estado de la respuesta. `200` para exitoso, `400` para error de validación, `500` para error interno.</td></tr><tr><td>`message`</td><td>string | null</td><td>Cuando la respuesta es exitosa vale `null`. Si no se encuentran facturas, contiene el mensaje informativo. Si hay error, describe el problema.</td></tr><tr><td>`body`</td><td>array | null</td><td>Listado de facturas devueltas. Arreglo vacío `[]` si no hay resultados. `null` en caso de error.</td></tr><tr><td>`pagination`</td><td>object | null</td><td>Información de paginación para recorrer los resultados. `null` en caso de error.</td></tr></tbody></table>

##### **Campos de cada factura (body)**

Cada elemento dentro del arreglo `body` contiene las siguientes claves:

<table border="1" id="bkmrk-campo-tipo-descripci-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 20%;"></col><col style="width: 14%;"></col><col style="width: 66%;"></col></colgroup><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`factura_id`</td><td>integer</td><td>Identificador único de la factura en el sistema.</td></tr><tr><td>`factura_numero`</td><td>integer</td><td>Número consecutivo de la factura.</td></tr><tr><td>`resolucion`</td><td>string</td><td>Prefijo y número de la resolución de facturación en formato `PREFIJO - NÚMERO` (ej. `"FECO - 18764000002851"`).</td></tr><tr><td>`fecha_factura`</td><td>string</td><td>Fecha de emisión de la factura en formato `YYYY-MM-DD`.</td></tr><tr><td>`fecha_vencimiento`</td><td>string</td><td>Fecha de vencimiento de la factura en formato `YYYY-MM-DD`.</td></tr><tr><td>`valor_total`</td><td>string</td><td>Valor total de la factura con decimales (ej. `"2850000.00"`).</td></tr><tr><td>`saldo`</td><td>string</td><td>Saldo pendiente de pago de la factura con decimales (ej. `"0.00"` cuando está pagada).</td></tr><tr><td>`documento_tercero`</td><td>string</td><td>Número de documento de identidad del tercero/cliente facturado.</td></tr><tr><td>`nombre_tercero`</td><td>string</td><td>Nombre completo del tercero/cliente facturado.</td></tr><tr><td>`estado`</td><td>string</td><td>Estado textual de la factura. Valores posibles: `Facturada`, `Anulada`, `Pagada`, `Borrador`, `Anulada por NC`, `Contabilizada`.</td></tr><tr><td>`estado_dian`</td><td>string | null</td><td>Estado de la factura en la DIAN cuando es factura electrónica (ej. `"Aceptada"`). `null` si no aplica o no se ha enviado.</td></tr><tr><td>`estado_cliente_dian`</td><td>string | null</td><td>Estado de aceptación/rechazo del cliente ante la DIAN cuando es factura electrónica. `null` si no aplica.</td></tr><tr><td>`notas`</td><td>integer</td><td>Cantidad de notas débito o crédito asociadas a la factura.</td></tr><tr><td>`creado_por`</td><td>string</td><td>Nombre del usuario que creó la factura en el sistema.</td></tr><tr><td>`fecha_envio_dian`</td><td>string | null</td><td>Fecha y hora de envío de la factura a la DIAN en formato `YYYY-MM-DD HH:MM:SS`. `null` si no se ha enviado.</td></tr><tr><td>`fecha_creacion`</td><td>string</td><td>Fecha y hora de creación del registro en formato `YYYY-MM-DD HH:MM:SS`.</td></tr></tbody></table>

##### **Campos de paginación (pagination)**

El objeto `pagination` contiene las siguientes claves:

<table border="1" id="bkmrk-campo-tipo-descripci-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 22%;"></col><col style="width: 14%;"></col><col style="width: 64%;"></col></colgroup><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`total_records`</td><td>integer</td><td>Total de facturas registradas en el sistema.</td></tr><tr><td>`total_pages`</td><td>integer</td><td>Cantidad total de páginas disponibles (total de registros dividido por el tamaño de página).</td></tr><tr><td>`current_page`</td><td>integer</td><td>Número de la página actual consultada.</td></tr><tr><td>`page_size`</td><td>integer</td><td>Tamaño de la página (cantidad de registros solicitados por consulta).</td></tr><tr><td>`current_page_records`</td><td>integer</td><td>Cantidad de registros efectivamente devueltos en la página actual.</td></tr><tr><td>`has_next_page`</td><td>boolean</td><td>`true` si existen páginas posteriores que se pueden consultar.</td></tr><tr><td>`has_previous_page`</td><td>boolean</td><td>`true` si existen páginas anteriores que se pueden consultar.</td></tr></tbody></table>

<p class="callout info">**Nota sobre facturas sin resultados**  
Si no existen facturas registradas en el sistema, la respuesta tendrá HTTP `200` con `body` vacío (`[]`), un `message` informativo: `"No se encontraron facturas en el sistema."` y los valores de paginación en cero.</p>

---

#### **4. Seguridad y Posibles Errores**

<p class="callout danger">**¡Tu pase tiene fecha de caducidad!**</p>

Por medidas de seguridad, el `token` que te entregamos **solo dura 1 hora**. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error `401`. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de [Login](https://docs.nuby.ai/books/api-nuby-v2/page/login) para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

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

Si alguno de los parámetros de paginación no cumple con las validaciones, el sistema devolverá un error `400`. Por ejemplo:

```json
{
    "status": 400,
    "message": "El parámetro \"page_size\" debe ser un número positivo.",
    "body": null,
    "pagination": null
}
```

Posibles errores:

<table border="1" id="bkmrk-c%C3%B3digo-http-descripc" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 12%;"></col><col style="width: 88%;"></col></colgroup><thead><tr><th>Código HTTP</th><th>Descripción</th></tr></thead><tbody><tr><td>**400**</td><td>**Token faltante o inválido.** Posibles causas:  
— No se envió el encabezado `Authorization`. Mensaje: `"JWT Token required."`  
— El encabezado no tiene el formato `Bearer {token}`. Mensaje: `"JWT Token not send."`  
— El token no fue encontrado en el sistema. Mensaje: `"JWT Token not found."`  
  
**Parámetros inválidos.** Posibles causas:  
— `page` no es numérico o no es positivo. Mensaje: `"El parámetro \"page\" debe ser un número positivo."`  
— `page_size` no es numérico o no es positivo. Mensaje: `"El parámetro \"page_size\" debe ser un número positivo."`</td></tr><tr><td>**401**</td><td>El token ha expirado. Debes generar uno nuevo consumiendo el servicio de **Login**. Mensaje: `"JWT Token expired."`</td></tr><tr><td>**403**</td><td>El cliente OAuth no tiene el scope necesario para esta operación. Para endpoints GET se requiere el scope `read`. Mensaje: `"Insufficient scope. Required: 'read', granted: '{scope_actual}'."`</td></tr><tr><td>**500**</td><td>Error interno del servidor al procesar la consulta de facturas. Mensaje: `"Error interno del servidor al obtener las facturas."`</td></tr></tbody></table>

---

#### **5. Ejemplos de integración**

Aquí tienes ejemplos de código listos para que tus desarrolladores los adapten a tu plataforma:

<details id="bkmrk-curl-%23-listar-factur"><summary>cURL</summary>

```bash
# Listar facturas con paginación por defecto
curl -X GET "https://{{instancia}}/service/v2/public/invoices/list" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Listar facturas página 3 con 100 registros por página
curl -X GET "https://{{instancia}}/service/v2/public/invoices/list?page=3&page_size=100" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"
```

</details><details id="bkmrk-php-%3C%3Fphp-%24instance-"><summary>PHP</summary>

```php
<?php

$instance = 'tu_instancia'; // Reemplaza con tu instancia real
$token = 'TU_TOKEN_AQUI'; // Token obtenido del servicio Login

// Parámetros de paginación
$page = 1;
$page_size = 50;

$queryParams = http_build_query([
    'page' => $page,
    'page_size' => $page_size
]);

$url = "https://{$instance}/service/v2/public/invoices/list?{$queryParams}";

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

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo "Código de estado HTTP: " . $http_code . "\n";

    $info = json_decode($response, true);
    $body = $info['body'] ?? [];

    if ($http_code === 200 && !empty($body)) {
        $pagination = $info['pagination'];
        echo "Facturas encontradas: {$pagination['total_records']} (página {$pagination['current_page']} de {$pagination['total_pages']})\n";

        foreach ($body as $factura) {
            echo "  Factura #{$factura['factura_numero']} - {$factura['nombre_tercero']} - {$factura['estado']} - Total: \${$factura['valor_total']} - Saldo: \${$factura['saldo']}\n";
        }
    } else {
        echo "Mensaje: " . ($info['message'] ?? 'Sin resultados') . "\n";
    }
}
curl_close($ch);

?>
```

</details><details id="bkmrk-python-import-reques"><summary>Python</summary>

```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 parámetros
url = f"https://{instancia}/service/v2/public/invoices/list"

params = {
    "page": 1,
    "page_size": 50
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

# 3. Envía la petición GET y procesa la respuesta
try:
    response = requests.get(url, params=params, headers=headers)

    print(f"Código de estado HTTP: {response.status_code}")

    if response.status_code == 200:
        info = response.json()
        body = info.get('body', [])
        pagination = info.get('pagination', {})

        if body:
            print(f"Facturas: {pagination['total_records']} total (página {pagination['current_page']} de {pagination['total_pages']})")
            for factura in body:
                print(f"  #{factura['factura_numero']} - {factura['nombre_tercero']} - {factura['estado']} - Total: ${factura['valor_total']} - Saldo: ${factura['saldo']}")
        else:
            print(f"Mensaje: {info.get('message', 'Sin resultados')}")
    else:
        print("Error al consultar las facturas.")
        print(f"Detalle del error: {response.text}")

except Exception as e:
    print(f"Ocurrió un error de conexión: {e}")

```

</details><details id="bkmrk-javascript-%2F%2F-1.-con"><summary>JavaScript</summary>

```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. Prepara la dirección con parámetros
const params = new URLSearchParams({
    page: 1,
    page_size: 50
});

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

// 3. Función para consultar las facturas
async function consultarFacturas() {
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            }
        });

        console.log(`Código de estado HTTP: ${response.status}`);

        if (response.ok) {
            const info = await response.json();
            const body = info.body || [];
            const pagination = info.pagination || {};

            if (body.length > 0) {
                console.log(`Facturas: ${pagination.total_records} total (página ${pagination.current_page} de ${pagination.total_pages})`);
                body.forEach(factura => {
                    console.log(`  #${factura.factura_numero} - ${factura.nombre_tercero} - ${factura.estado} - Total: $${factura.valor_total} - Saldo: $${factura.saldo}`);
                });
            } else {
                console.log(`Mensaje: ${info.message || 'Sin resultados'}`);
            }
        } else {
            console.log('Error al consultar las facturas.');
            const errorData = await response.text();
            console.log(`Detalle del error: ${errorData}`);
        }
    } catch (error) {
        console.error(`Ocurrió un error de conexión: ${error}`);
    }
}

// 4. Ejecutamos la función
consultarFacturas();

```

</details><details id="bkmrk-power-query-m-%28excel"><summary>Power Query M (Excel / Power BI)</summary>

```powerquery
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 con parámetros
    url = "https://" & instancia & "/service/v2/public/invoices/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],

    // 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", "documento_tercero", "nombre_tercero", "estado", "estado_dian", "notas", "creado_por", "fecha_creacion"},
        {"FacturaID", "Numero", "Resolucion", "FechaFactura", "FechaVencimiento", "ValorTotal", "Saldo", "DocTercero", "NombreTercero", "Estado", "EstadoDian", "Notas", "CreadoPor", "FechaCreacion"})
in
    expandido
```

</details>