Listar Facturas

Permite obtener unala lista de elementos, donde cada elemento contiene la informaciónpaginada de cada una detodas las facturas registradas en lael inmobiliaria.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.

Endpoint:¿Para qué sirve este servicio? https://
Ú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.

1. El Endpoint (La dirección web)

Apunta tu sistema a la siguiente dirección. Recuerda reemplazar {{instancia}}.arrendasoft.co/ por la dirección web completa que utilizas para ingresar a tu plataforma.

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

¿Qué debes colocar en {{instancia}}:? Hace
Es referenciamuy sencillo: corresponde a la instanciadirecció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 cadano inmobiliaria.incluir el "https://" ni barras diagonales ("/") al final.

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:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

Parámetros de consulta (query string):

Ejemplos de peticionespetición:

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/invoices/list

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=1

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page_size=100

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=1&page_size=100

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?estado=1

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?documento=1234567890

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?pendientes=true

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?documento=1234567890&pendientes=true&page_size=50

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?pendientes=true&incluir_borrador=true

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?resolucion_id=5

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/list?resolucion_id=1,2,3&pendientes=true&page_size=100

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

ListaSi tu Token es válido, el sistema te devolverá un objeto JSON con el estado de elementos,la donderespuesta, cadael elementolistado contienede facturas y la información de lospaginación. datosLos obtenidos,resultados estado,están mensaje,ordenados listadopor fecha de lasfactura facturas,descendente paginación(más yrecientes filtrosprimero). aplicados.La respuesta se verá similar a esta:

{
    "status": 200,
    "message": null,
    "body": [
        {
            "factura_id": 366,15230,
            "factura_numero": 324,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 - 120000042273"18764000002851",
            "fecha_factura": "2014-08-2025-03-01",
            "fecha_vencimiento": "2014-08-2025-03-06",
            "valor_total": "94992.1200000.00",
            "saldo": "94992.1200000.00",
            "tercero_id": 15,
            "documento_tercero": "1111111"43876123",
            "nombre_tercero": "TERCERODIANA FACTURADO"MARCELA OSPINA VELÁSQUEZ",
            "estado_id": 1,
            "estado": "Facturada",
            "estado_dian": null,
            "estado_cliente_dian": null,
            "observaciones": "CONTRATO 5 - TERCERO FACTURADO Propietario: C.C. 9999999 JUAN PEREZ",
            "notas": 0,1,
            "creado_por": "Administrador",
            "fecha_envio_dian": null,
            "fecha_creacion": "2014-08-082025-03-01 10:50:52",
            "pdf_link": "https://instancia.arrendasoft.co/fpdf/contabilidad_documento.php?hash=abc123def456...",
            "detalles": [
                {
                    "detalle_id": 1,
                    "producto": "Canon De Arrendamiento",
                    "descripcion": "Canon De Arrendamiento De 01-Ago-2014 a 31-Ago-2014",
                    "contrato_id": 5,
                    "contrato_numero": 5,
                    "cantidad": 1,
                    "valor_unitario": 80000,
                    "iva": 0,
                    "por_iva": 0,
                    "retencion": 0,
                    "por_retencion": 0,
                    "reteiva": 0,
                    "por_reteiva": 0,
                    "reteica": 0,
                    "por_reteica": 0,
                    "descuento": 0,
                    "por_descuento": 0
                },
                {
                    "detalle_id": 2,
                    "producto": "Administración",
                    "descripcion": "Administración De 01-Ago-2014 a 31-Ago-2014",
                    "contrato_id": 5,
                    "contrato_numero": 5,
                    "cantidad": 1,
                    "valor_unitario": 14992,
                    "iva": 0,
                    "por_iva": 0,
                    "retencion": 0,
                    "por_retencion": 0,
                    "reteiva": 0,
                    "por_reteiva": 0,
                    "reteica": 0,
                    "por_reteica": 0,
                    "descuento": 0,
                    "por_descuento": 0
                }
            ]09:12:33"
        },
        {
            "factura_id": 8,14850,
            "factura_numero": 7,8520,
            "resolucion": "0FECO - 120000042273"18764000002851",
            "fecha_factura": "2014-01-2025-02-01",
            "fecha_vencimiento": "2014-01-2025-02-06",
            "valor_total": "1666850.3950000.00",
            "saldo": "0.3950000.00",
            "tercero_id": 22,
            "documento_tercero": "22222222"900456789",
            "nombre_tercero": "COOPERATIVAINVERSIONES MULTIACTIVA"HORIZONTE S.A.S.",
            "estado_id": 3,
            "estado": "Pagada"Anulada por NC",
            "estado_dian": null,"Aceptada",
            "estado_cliente_dian": null,
            "observaciones": null,
            "notas": 0,1,
            "creado_por": "Contador"Sandra",
            "fecha_envio_dian": null,"2025-02-01 10:05:44",
            "fecha_creacion": "2014-05-072025-02-01 11:14:46",
            "pdf_link": "https://instancia.arrendasoft.co/public/pdf?hash=xyz789ghi012...",
            "detalles": [
                {
                    "detalle_id": 10,
                    "producto": "Canon De Arrendamiento",
                    "descripcion": "Canon De Arrendamiento De 01-Ene-2014 a 31-Ene-2014",
                    "contrato_id": 3,
                    "contrato_numero": 3,
                    "cantidad": 1,
                    "valor_unitario": 1666850,
                    "iva": 0,
                    "por_iva": 0,
                    "retencion": 0,
                    "por_retencion": 0,
                    "reteiva": 0,
                    "por_reteiva": 0,
                    "reteica": 0,
                    "por_reteica": 0,
                    "descuento": 0,
                    "por_descuento": 0
                }
            ]08:20:15"
        }
    ],
    "pagination": {
        "total_records": 41326,15230,
        "total_pages": 83,305,
        "current_page": 83,1,
        "page_size": 500,50,
        "current_page_records": 326,4,
        "has_next_page": false,true,
        "has_previous_page": true
    },
    "filters_applied": {
        "documento": "1111111",
        "pendientes": true,
        "incluir_borrador": true,
        "resolucion_ids": [1, 3]false
    }
}

Claves y Descripciones del JSON de Facturación

Esta tabla enumera las claves presentes en el JSONEstructura principal de la respuesta y proporciona una breve descripción de cada una, explicando su propósito y el tipo de información que contienen.

CuerpoCampos de cada factura (body)

Cada elemento dentro dedel la listaarreglo body, tienecontiene las siguientes claves:

DetallesCampos de lapaginación factura

(pagination)

FuncionalidadEl enobjeto pruebas
Esta funcionalidad forma parte de un proceso de pruebas internas y no se encuentra disponible para usuarios del sistema.

Cada elemento dentro de la lista detallespagination de una factura, tienecontiene las siguientes claves:

Paginación

Cada elemento dentro de la lista pagination tiene las siguientes claves:

Filtros Aplicados

FuncionalidadNota sobre facturas sin resultados
Si no existen facturas registradas en pruebas
Estael funcionalidad forma parte de un proceso de pruebas internas y no se encuentra disponible para usuarios del sistema.

El objeto filters_applied contiene los filtros que fueron utilizados en la consulta. Solo se incluye ensistema, la respuesta cuandotendrá HTTP 200 con body vacío ([]), un message informativo: "No se aplicanencontraron filtros.facturas Lasen posiblesel clavessistema." son:y los valores de paginación en cero.

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 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 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:

{
    "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:

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

Posibles errores:

# Listar facturas con paginación por defecto
curl -X GET "https://{{instancia}}.arrendasoft.co//service/v2/public/invoices/list?page_size=100&page=3"list" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"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"

<?php

$instance = 'your_instance'tu_instancia'; // ReemplaceReemplaza con sutu instancia actualreal
$token = 'YOUR_AUTHENTICATION_TOKEN'TU_TOKEN_AQUI'; // Reemplace con el tokenToken obtenido desde eldel servicio de loginLogin

// Parámetros de ejemplo para listar facturaspaginación
$page = 1;
$page_size = 50;

$url = "https://{$instance}.arrendasoft.co/service/v2/public/invoices/list?";
$queryParams = http_build_query([
    'page' => $page,
    'page_size' => $page_size
]);

$url .= http_build_query("https://{$queryParams)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 ' . {$tokentoken}"
]);

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

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo "HTTPCódigo Statusde Code:estado HTTP: " . $http_code . "\n";
    echo "Response: " . $response . "\n";
    
    // Procesar la respuesta

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

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

        //foreach Ejemplo: Imprimir los números de las facturas
        foreach(($body as $invoice)factura) {
            echo "  Factura número: " . #{$invoice[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);

?>

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}")

// 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();

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