Obtener Cartera

Permite a una pasarela de pagos autenticada (por ejemplo, Palomma) consultar la registrarcartera el pagopagable de uno o varios ítems pagables en la inmobiliaria: una factura, un movimientotercero: (conceptofacturas /pendientes, interés)conceptos ofacturables, unaconceptos facturano juntofacturables con suse intereses adjuntos.de mora adjuntos a facturas de canon. El endpoint es idempotente, devuelve un cuerpo en formato de arreglo ysistema aplica automáticamente la configuración de filtros avanzados registrada para la pasarela (forma de pago, envío DIAN).autenticada.

¿Para qué sirve este servicio?
Está pensado exclusivamente para integraciones con pasarelas de pago. La pasarela lo invocaconsume cuandopara elmostrarle al deudor confirmalos elítems pagoque puede pagar en línea de(facturas, losconceptos ítemse devueltosintereses), previamente por GET /gateways/portfolio. El sistema persiste el pago, genera el recibo de caja y, cuandorespetando la configuración locomercial requiera, dispara el envío del documento electrónico ade la DIAN.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.

POSTGET https://{{instancia}}/service/v2/public/gateways/paymentsportfolio

¿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?)

DebesEste enviarservicio unarequiere peticiónautenticación POSTmediante conun elToken detalleJWT delobtenido pagopor en el cuerpo de la solicitud en formato JSON.OAuth2. La pasarela se identifica automáticamente a partir del client_name del token; no debes enviar el nombre de la pasarela ni la forma de pagoenviarlo en el body ni como query string: ambos se derivan de la configuración registrada..

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.

CuerpoParámetros de la peticiónconsulta (Body)query string):

ModosFiltros avanzados de operaciónla 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 clasificaexcluye elautomáticamente pagolas 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 unolugar de cuatro modos según los campos enviadosINGRESO_INQUILINO— y lano configuraciónson depagables lavía pasarela:
—pasarela Modoen movimientoesta único:versión. factura_id = null y movimiento_id = [n].
— Modo GROUP: factura_id = null y movimiento_id = [m1, m2, ...] con varios movimientos del mismo tercero. SoloNo se admite cuando la pasarela tiene activo el filtro avanzado «Agrupar conceptos del mismo periodo». Genera un único recibo de caja y, cuando aplique, una factura agrupada por contrato.
— Modo factura: factura_id = X y movimiento_id = [] o ausente.
— Modo factura + intereses adjuntos: factura_id = X y movimiento_id = [m1, m2, ...]. Los movimientos que pertenezcan a la factura X se ignoran (ya están cubiertos); los demás se procesan como intereses sueltosincluyen en la mismarespuesta transacción.ni en el conteo total.

Ejemplo 1: PagoEjemplos de una sola facturapeticiones:

GET https://{
    "factura_id": 4521,
    "monto": 1750000.00,
    "fecha_pago": "2026-04-25 14:30:00",
    "n_comprobante": "PALM-2026-04-25-998877"
{instancia}}/service/v2/public/gateways/portfolio

Ejemplo

GET 2: Pago de un movimiento (concepto suelto)
https://{{instancia}}/service/v2/public/gateways/portfolio?documento=1020304050

GET https://{
    "movimiento_id": 98515,
    "monto": 280000.00,
    "fecha_pago": "2026-04-25 14:30:00",
    "n_comprobante": "PALM-2026-04-25-998878"
{instancia}}/service/v2/public/gateways/portfolio?documento=1020304050&pendientes=true&page=1&page_size=20

Ejemplo

GET 3: Pago de una factura junto con sus intereses adjuntos
https://{{instancia}}/service/v2/public/gateways/portfolio?documento=1020304050&incluir_intereses_mora=true&incluir_conceptos_futuros=true&rango_conceptos_futuros_meses=3

GET https://{
    "factura_id": 4521,
    "movimiento_id": [98410, 98411],
    "monto": 1820000.00,
    "fecha_pago": "2026-04-25 14:30:00",
    "n_comprobante": "PALM-2026-04-25-998879"
{instancia}}/service/v2/public/gateways/portfolio?documento=1020304050&resolucion_ids=3,7

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

El sistema respondedevolverá una respuesta JSON con HTTPlos 200ítems cuandopagables eldel pagotercero, los filtros realmente aplicados y la información de paginación. Cada ítem se registraentrega correctamente.con La clave body esla siempremisma unestructura arreglocanónica, inclusosin cuandoimportar elsi pago resulta en un solo registro. Cada elemento del arreglo describe un documento generado por la operación: la factura pagada,representa una factura nuevade creadacontrato, poruna factura de venta, un concepto facturable, un concepto no facturable o una factura con intereses facturables, o un anticipo si hubo excedente.adjuntos.

{
    "success": true,
    "status": 200,
    "message": "ElLa pagocartera de la pasarela fue registradoconsultada exitosamente.correctamente.",
    "body": [
        {
            "factura_id": 4521,
            "movimiento_id"factura_numero": null,"291",
            "pago_id"contrato_id": 87123,187,
            "recibo_id"contrato_numero": 56412,"C-000187",
            "documento_contable_id"tercero_id": 102345,272,
            "monto_pagado"tercero_documento": "1020304050",
            "tercero_nombre": "ANA MARÍA PÉREZ RODRÍGUEZ",
            "tercero_correo": "ana.perez@email.com",
            "tercero_telefono": "3001234567",
            "fecha_vencimiento": "2026-04-30",
            "observaciones": "Factura 291 del Contrato C-000187",
            "valor_total": 1750000.00,
            "fecha_pago": "2026-04-25 14:30:00",
            "forma_pago_id": 7,
            "forma_pago": "Pasarela Palomma",
            "n_comprobante": "PALM-2026-04-25-998877",
            "saldo_anterior"saldo": 1750000.00,
            "saldo_actual": 0.00,
            "estado": "pagada",
            "mensaje": "El pago cubrió el total de la factura.",
            "estado_dian": "pendiente",
            "documento_contable_pdf"factura_pdf": "https://demo.nuby.app/contabilidad_documento.php?hash=x1y2z3a4b5"a1b2c3d4e5",
            "gateway": "palomma",
            "client_name": "palomma_inmobiliaria_xyz"
        }
    ],
    "alertas": [],
    "data": {
        "factura_id": 4521,
        "pago_id": 87123,
        "recibo_id": 56412,
        "documento_contable_id": 102345,
        "confirm_pay_id": 9921,
        "gateway": "palomma",
        "client_name": "palomma_inmobiliaria_xyz",
        "documentos_generados"items": [
                {
                    "tipo"movimiento_id": 98231,
                    "descripcion": "recibo"Canon de arrendamiento - Canon abril 2026",
                    "id"valor_unitario": 56412,1600000.00,
                    "numero"cantidad": 1,
                    "REC-56412"valor_iva": 0.00,
                    "valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                },
                {
                    "tipo"movimiento_id": 98232,
                    "descripcion": "factura"Administración - Cuota administración abril 2026",
                    "id"valor_unitario": 4521, "numero": "FAC-4521" }
        ]
    }
}

Ejemplo de respuesta con excedente (anticipo):

{
    "success": true,
    "status": 200,
    "message": "El pago fue registrado exitosamente.",
    "body": [
        {
            "factura_id": 4521,
            "movimiento_id": null,
            "pago_id": 87124,
            "recibo_id": 56413,
            "documento_contable_id": 102346,
            "monto_pagado": 1750000.150000.00,
                    "fecha_pago"cantidad": "2026-04-25 14:30:00",1,
                    "forma_pago_id": 7,
            "forma_pago": "Pasarela Palomma",
            "n_comprobante": "PALM-2026-04-25-998880",
            "saldo_anterior": 1750000.00,
            "saldo_actual"valor_iva": 0.00,
                    "estado"valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                },
                {
                    "movimiento_id": 98410,
                    "descripcion": "pagada"Intereses de mora - Mora canon marzo 2026",
                    "mensaje"valor_unitario": "El pago cubrió el total de la factura.",35000.00,
                    "estado_dian"cantidad": "pendiente",1,
                    "documento_contable_pdf"valor_iva": "https://demo.nuby.app/contabilidad_documento.php?hash=x1y2z3a4b6",0.00,
                    "gateway"valor_retencion": "palomma",0.00,
                    "client_name"valor_reteiva": 0.00,
                    "palomma_inmobiliaria_xyz"valor_reteica": 0.00,
                    "valor_descuento": 0.00
                }
            ]
        },
        {
            "factura_id": null,
            "movimiento_id"factura_numero": null,
            "pago_id"contrato_id": null,187,
            "recibo_id"contrato_numero": null,"C-000187",
            "documento_contable_id"tercero_id": 102347,272,
            "monto_pagado"tercero_documento": 50000.00,"1020304050",
            "fecha_pago"tercero_nombre": "ANA MARÍA PÉREZ RODRÍGUEZ",
            "tercero_correo": "ana.perez@email.com",
            "tercero_telefono": "3001234567",
            "fecha_vencimiento": "2026-04-25 14:30:00"05-15",
            "forma_pago_id": 7,
            "forma_pago"observaciones": "PasarelaCosto Palomma"del Contrato C-000187",
            "n_comprobante"valor_total": "PALM-2026-04-25-998880",280000.00,
            "saldo_anterior"saldo": null,
            "saldo_actual": null,280000.00,
            "estado": "anticipo"pendiente",
            "mensaje"items": [
                {
                    "movimiento_id": 98515,
                    "descripcion": "SeReparación generólocativa un- anticipoReparación porlocativa valorbaño de 50000.00 con el excedente del pago."principal",
                    "estado_dian"valor_unitario": null,280000.00,
                    "gateway"cantidad": "palomma",1,
                    "client_name"valor_iva": 0.00,
                    "palomma_inmobiliaria_xyz"valor_retencion": 0.00,
                    "valor_reteiva": 0.00,
                    "valor_reteica": 0.00,
                    "valor_descuento": 0.00
                }
            ]
        }
    ],
    "alertas": [],
    "data"filters_applied": {
        "factura_id"documento": 4521,
        "pago_id": 87124,
        "recibo_id": 56413,
        "documento_contable_id": 102346,
        "anticipo_documento_contable_ids": [102347]1020304050",
        "confirm_pay_id"pendientes": 9922,true,
        "gateway"incluir_borrador": false,
        "palomma"incluir_conceptos_no_factura": true,
        "incluir_conceptos_futuros": false,
        "incluir_intereses_mora": true,
        "agrupar_conceptos_periodo": false
    },
    "client_name"pagination": {
        "palomma_inmobiliaria_xyz"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 elementoítem de (body[])

EscenariosMapeo especialesde estados de factura

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

4. Idempotencia

El endpoint detecta automáticamente reintentosInformación de unpaginación mismo pago y responde (409 Conflictpagination sin volver a registrarlo. Las reglas de idempotencia son:

Cómo interpretar el 409
Una respuesta 409 Conflict de este endpoint no es un fallo: significa que el pago ya existe en nuby. La pasarela debe tratarla como confirmación idempotente y no reintentar. El cuerpo incluye error_code = "DUPLICATE_PAYMENT", is_business_error = true y, en data, los identificadores del pago original (confirm_pay_id, confirm_pay_reference_code, factura_id, pago_id, recibo_id, documento_contable_id).

Ejemplo de respuesta 409:

{
    "success": false,
    "status": 409,
    "message": "El pago ya fue registrado previamente para la pasarela palomma_inmobiliaria_xyz.",
    "body": [ /* snapshot del body original */ ],
    "error_code": "DUPLICATE_PAYMENT",
    "data": {
        "factura_id": 4521,
        "pago_id": 87123,
        "recibo_id": 56412,
        "documento_contable_id": 102345,
        "confirm_pay_id": 9921,
        "confirm_pay_reference_code": "PALM-2026-04-25-998877",
        "gateway": "palomma",
        "client_name": "palomma_inmobiliaria_xyz"
    },
    "duplicate": {
        "payload": { /* payload original recibido en el primer intento */ }
    }
}

5.4. Seguridad y Posibles Errores

El sistema realiza validaciones de autenticación, autorización por pasarela, configuraciónpasarela y consistencia del payload.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, cuando aplica,y error_codebody: [].

6.5. Ejemplos de integración

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

# PagoConsultar dela unacartera facturadel tercero con documento 1020304050
curl -X POSTGET "https://{{instancia}}/service/v2/public/gateways/payments"portfolio?documento=1020304050&pendientes=true&page=1&page_size=20" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

\
-d '{
  "factura_id": 4521,
  "monto": 1750000.00,
  "fecha_pago": "2026-04-25 14:30:00",
  "n_comprobante": "PALM-2026-04-25-998877"
}'

# PagoCartera incluyendo intereses de unamora facturay juntoconceptos confuturos sus(3 intereses adjuntosmeses)
curl -X POSTGET "https://{{instancia}}/service/v2/public/gateways/payments"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" \
-d '{
  "factura_id": 4521,
  "movimiento_id": [98410, 98411],
  "monto": 1820000.00,
  "fecha_pago": "2026-04-25 14:30:00",
  "n_comprobante": "PALM-2026-04-25-998879"
}'

<?php

$instance = 'tu_instancia'; // Reemplaza con tu instancia real
$token = 'TU_TOKEN_AQUI'; // Token deobtenido undel servicio Login (cliente OAuth registrado como pasarelapasarela)

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

$url = "https://{$instance}/service/v2/public/gateways/payments";

portfolio?{$payload = [
    'factura_id'     => 4521,
    'monto'          => 1750000.00,
    'fecha_pago'     => '2026-04-25 14:30:00',
    'n_comprobante'  => 'PALM-2026-04-25-998877',
]queryParams}";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
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";

$data = json_decode($response, true);

if ($http_code === 200) {
    $data = json_decode($response, true);
    echo "PagoTotal registrado.ítems: Recibo:" . ($data['pagination']['total_records'] ?? 0) . "\n";
    foreach ($data['body'] as $item) {
        $tipo = $item['factura_id'] ? "Factura #{$item['factura_id']}" : "Concepto";
        echo "  [{$tipo}] {$data[item['data'tercero_nombre'][} - Saldo: {$item['recibo_id'saldo']} - Vence: {$item['fecha_vencimiento']}\n";
    } elseif ($http_code === 409) {
    echo "Pago ya existía previamente. confirm_pay_id: {$data['data']['confirm_pay_id']}\n";
    // No reintentar: el pago ya está registrado en nuby.
} else {
    echo "Error registrandoconsultando ella pago: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 ella bodydirección dely pagolos parámetros
url = f"https://{instancia}/service/v2/public/gateways/payments"portfolio"

payloadparams = {
    "factura_id": 4521,
    "monto": 1750000.00,
    "fecha_pago"documento": "2026-04-25 14:30:00"1020304050",
    "n_comprobante"pendientes": "PALM-2026-04-25-998877"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 POSTGET y procesa la respuesta
try:
    response = requests.post(get(url, json=payload,params=params, headers=headers)
    print(f"Código HTTP: {response.status_code}")

    data = response.json()

    if response.status_code == 200:
        data = response.json()
        print(f"PagoTotal registrado. Recibo:ítems: {data['data'pagination']['recibo_id'total_records']}")
        eliffor response.status_codeitem in data['body']:
            tipo == 409:f"Factura #{item['factura_id']}" if item['factura_id'] else "Concepto"
            print(f"Pago  ya existía previamente. confirm_pay_id:[{tipo}] {data[item['data'tercero_nombre'][} - Saldo: {item['confirm_pay_id'saldo']} - Vence: {item['fecha_vencimiento']}")
        # No reintentar: el pago ya está registrado en nuby.
    else:
        print("Error registrandoconsultando ella pago.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 ella bodydirección delcon pagoparámetros
const params = new URLSearchParams({
    documento: '1020304050',
    pendientes: 'true',
    incluir_intereses_mora: 'true',
    page: 1,
    page_size: 20,
});

const url = `https://${instancia}/service/v2/public/gateways/payments`;

const payload = portfolio?${
    factura_id: 4521,
    monto: 1750000.00,
    fecha_pago: '2026-04-25 14:30:00',
    n_comprobante: 'PALM-2026-04-25-998877',
}params}`;

// 3. Función para registrarconsultar ella pagocartera
async function registrarPago(consultarCartera() {
    try {
        const response = await fetch(url, {
            method: 'POST'GET',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`,
            },
        body: JSON.stringify(payload),
        });

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

        if (response.ok) {
            const data = await response.json();
            ifconsole.log(`Total (response.statusítems: ${data.pagination.total_records}`);
            data.body.forEach(item ==> {
                const tipo = 200)item.factura_id ? `Factura #${item.factura_id}` : 'Concepto';
                console.log(`Pago  registrado. Recibo:[${tipo}] ${data.data.recibo_id}item.tercero_nombre} - Saldo: ${item.saldo} - Vence: ${item.fecha_vencimiento}`);
            });
        } else if{
            (response.statusconst errorData === 409)await {
            console.log(`Pago ya existía previamente. confirm_pay_id: ${data.data.confirm_pay_id}`response.text();
            // No reintentar: el pago ya está registrado en nuby.
        } else {
            console.log('Error registrandoconsultando ella pago.cartera.');
            console.log(data)errorData);
        }
    } catch (error) {
        console.error(`Error de conexión: ${error}`);
    }
}

registrarPago(consultarCartera();