Obtener Cartera [Beta]

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

Permite a una pasarela de pagos autenticada consultar la cartera pagable de un tercero: facturas pendientes, conceptos facturables, conceptos no facturables e intereses de mora adjuntos a facturas de canon. El sistema aplica automáticamente la configuración de filtros avanzados registrada para la pasarela autenticada.

¿Para qué sirve este servicio?
Está pensado exclusivamente para integraciones con pasarelas de pago. La pasarela lo consume para mostrarle al deudor los ítems que puede pagar en línea (facturas, conceptos e intereses), respetando la configuración comercial de la inmobiliaria (qué incluir, qué excluir, qué resoluciones se admiten, etc.).

Endpoint restringido a pasarelas registradas
Este endpoint solo puede ser consumido por clientes OAuth2 cuyo client_name esté registrado como una pasarela activa en la inmobiliaria. Cualquier otro cliente recibirá 403 Forbidden.

1. El Endpoint (La dirección web)

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

GET https://{{instancia}}/service/v2/gateways/portfolio

¿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.

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

Este servicio requiere autenticación mediante un Token JWT obtenido por OAuth2. La pasarela se identifica automáticamente a partir del client_name del token; no debes enviarlo en el body ni como query string.

Autenticación requerida
Este servicio requiere un Token de autenticación válido. Debes incluir el encabezado Authorization: Bearer TU_TOKEN en cada petición. El token se obtiene consumiendo el servicio de Login. El cliente OAuth además debe estar registrado como pasarela activa; en caso contrario el endpoint responderá 403.

Parámetros de consulta (query string):

Filtros avanzados de la pasarela
Los filtros enviados por el caller se combinan con la configuración de filtros avanzados registrada para la pasarela autenticada en la inmobiliaria. Si la pasarela no tiene configuración propia, se aplica el comportamiento por defecto (solo facturas con estado pendiente, sin borradores, sin conceptos sueltos ni intereses adjuntos). Los filtros realmente aplicados se devuelven en la respuesta dentro de filters_applied.

Exclusión de facturas a propietario
El endpoint excluye automáticamente las facturas cuyos detalles estén asociados a movimientos de tipo FACTURA_PROPIETARIO (por ejemplo, comisiones del contrato facturadas al propietario). Estas facturas siguen una lógica contable distinta —generan EGRESO_PROPIETARIO en lugar de INGRESO_INQUILINO— y no son pagables vía pasarela en esta versión. No se incluyen en la respuesta ni en el conteo total.

Ejemplos de peticiones:

GET https://{{instancia}}/service/v2/gateways/portfolio

GET https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050

GET https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050&pendientes=true&page=1&page_size=20

GET https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050&incluir_intereses_mora=true&incluir_conceptos_futuros=true&rango_conceptos_futuros_meses=3

GET https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050&resolucion_ids=3,7

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

El sistema devolverá una respuesta JSON con los ítems pagables del tercero, los filtros realmente aplicados y la información de paginación. Cada ítem se entrega con la misma estructura canónica, sin importar si representa una factura de contrato, una factura de venta, un concepto facturable, un concepto no facturable o una factura con intereses adjuntos.

{
    "success": true,
    "status": 200,
    "message": "La cartera de la pasarela fue consultada correctamente.",
    "body": [
        {
            "factura_id": 4521,
            "factura_numero": "291",
            "contrato_id": 187,
            "contrato_numero": "C-000187",
            "tercero_id": 272,
            "tercero_documento": "1020304050",
            "tercero_nombre": "ANA MARÍA PÉREZ RODRÍGUEZ",
            "fecha_vencimiento": "2026-04-30",
            "observaciones": "Canon de arrendamiento abril 2026, Administración abril 2026",
            "valor_total": 1750000.00,
            "saldo": 1750000.00,
            "estado": "pendiente",
            "items": [
                {
                    "movimiento_id": 98231,
                    "valor_unitario": 1600000.00,
                    "cantidad": 1,
                    "valor_iva": 0.00,
                    "valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                },
                {
                    "movimiento_id": 98232,
                    "valor_unitario": 150000.00,
                    "cantidad": 1,
                    "valor_iva": 0.00,
                    "valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                },
                {
                    "movimiento_id": 98410,
                    "valor_unitario": 35000.00,
                    "cantidad": 1,
                    "valor_iva": 0.00,
                    "valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                }
            ]
        },
        {
            "factura_id": null,
            "factura_numero": null,
            "contrato_id": 187,
            "contrato_numero": "C-000187",
            "tercero_id": 272,
            "tercero_documento": "1020304050",
            "tercero_nombre": "ANA MARÍA PÉREZ RODRÍGUEZ",
            "fecha_vencimiento": "2026-05-15",
            "observaciones": "Reparación locativa baño principal",
            "valor_total": 280000.00,
            "saldo": 280000.00,
            "estado": "pendiente",
            "items": [
                {
                    "movimiento_id": 98515,
                    "valor_unitario": 280000.00,
                    "cantidad": 1,
                    "valor_iva": 0.00,
                    "valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                }
            ]
        }
    ],
    "filters_applied": {
        "documento": "1020304050",
        "pendientes": true,
        "incluir_borrador": false,
        "incluir_conceptos_no_factura": true,
        "incluir_conceptos_futuros": false,
        "incluir_intereses_mora": true
    },
    "pagination": {
        "total_records": 2,
        "total_pages": 1,
        "current_page": 1,
        "page_size": 10,
        "current_page_records": 2,
        "has_next_page": false,
        "has_previous_page": false
    }
}

Campos de la respuesta

Estructura de cada ítem (body[])

Mapeo de estados de factura

Estructura de cada renglón interno (body[].items[])

Información de paginación (pagination)

4. Seguridad y Posibles Errores

El sistema realiza validaciones de autenticación, autorización por pasarela y parámetros. Si alguna falla, devolverá un error con su respectivo código HTTP. La estructura del cuerpo de error siempre incluye success: false, status, message y body: [].

5. Ejemplos de integración

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

# Consultar la cartera del tercero con documento 1020304050
curl -X GET "https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050&pendientes=true&page=1&page_size=20" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Cartera incluyendo intereses de mora y conceptos futuros (3 meses)
curl -X GET "https://{{instancia}}/service/v2/gateways/portfolio?documento=1020304050&incluir_intereses_mora=true&incluir_conceptos_futuros=true&rango_conceptos_futuros_meses=3" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

<?php

$instance = 'tu_instancia'; // Reemplaza con tu instancia real
$token = 'TU_TOKEN_AQUI'; // Token obtenido del servicio Login (cliente OAuth registrado como pasarela)

$queryParams = http_build_query([
    'documento' => '1020304050',
    'pendientes' => 'true',
    'incluir_intereses_mora' => 'true',
    'page' => 1,
    'page_size' => 20,
]);

$url = "https://{$instance}/service/v2/gateways/portfolio?{$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);
curl_close($ch);

echo "Código HTTP: {$http_code}\n";

if ($http_code === 200) {
    $data = json_decode($response, true);
    echo "Total ítems: " . ($data['pagination']['total_records'] ?? 0) . "\n";
    foreach ($data['body'] as $item) {
        $tipo = $item['factura_id'] ? "Factura #{$item['factura_id']}" : "Concepto";
        echo "  [{$tipo}] {$item['tercero_nombre']} - Saldo: {$item['saldo']} - Vence: {$item['fecha_vencimiento']}\n";
    }
} else {
    echo "Error consultando la cartera:\n{$response}\n";
}

?>

import requests

# 1. Configura tus datos de acceso
instancia = 'mi-inmobiliaria.nuby.app'
token = 'TU_TOKEN_AQUI'  # Token de un cliente OAuth registrado como pasarela

# 2. Prepara la dirección y los parámetros
url = f"https://{instancia}/service/v2/gateways/portfolio"

params = {
    "documento": "1020304050",
    "pendientes": "true",
    "incluir_intereses_mora": "true",
    "page": 1,
    "page_size": 20,
}

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 HTTP: {response.status_code}")

    if response.status_code == 200:
        data = response.json()
        print(f"Total ítems: {data['pagination']['total_records']}")
        for item in data['body']:
            tipo = f"Factura #{item['factura_id']}" if item['factura_id'] else "Concepto"
            print(f"  [{tipo}] {item['tercero_nombre']} - Saldo: {item['saldo']} - Vence: {item['fecha_vencimiento']}")
    else:
        print("Error consultando la cartera.")
        print(response.text)
except Exception as e:
    print(f"Error de conexión: {e}")

// 1. Configura tus datos de acceso
const instancia = 'mi-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI'; // Token de un cliente OAuth registrado como pasarela

// 2. Prepara la dirección con parámetros
const params = new URLSearchParams({
    documento: '1020304050',
    pendientes: 'true',
    incluir_intereses_mora: 'true',
    page: 1,
    page_size: 20,
});

const url = `https://${instancia}/service/v2/gateways/portfolio?${params}`;

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

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

        if (response.ok) {
            const data = await response.json();
            console.log(`Total ítems: ${data.pagination.total_records}`);
            data.body.forEach(item => {
                const tipo = item.factura_id ? `Factura #${item.factura_id}` : 'Concepto';
                console.log(`  [${tipo}] ${item.tercero_nombre} - Saldo: ${item.saldo} - Vence: ${item.fecha_vencimiento}`);
            });
        } else {
            const errorData = await response.text();
            console.log('Error consultando la cartera.');
            console.log(errorData);
        }
    } catch (error) {
        console.error(`Error de conexión: ${error}`);
    }
}

consultarCartera();