Listar Terceros [BETA]

Funcionalidad en desarrollo y pruebas: este servicio está disponible en el ambiente de pruebas y todavía no debe usarse en producción. El funcionamiento, los campos y los mensajes de error pueden cambiar antes del despliegue definitivo.

Este servicio devuelve una lista paginada de terceros registrados en nuby, con sus datos principales de identificación y contacto. Puedes filtrar por documento exacto, por coincidencia parcial en el nombre y por tipo de documento.

Úsalo para buscar un tercero del que no conoces el identificador interno, para conciliar tus clientes con los de nuby o para construir un buscador en tu propia interfaz.

¿Para qué sirve este servicio?
Los casos de uso más frecuentes de este servicio son:

1. El Endpoint (La dirección web)

Método y dirección

GET https://{{instancia}}/service/v2/public/third-parties/list

¿Qué debes colocar en {{instancia}}? La dirección web principal con la que ingresas a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co, sin https:// y sin barras diagonales al final.

Encabezados requeridos

Permiso requerido (scope)

Este servicio es de solo lectura y exige el permiso catalogs:read en el cliente OAuth. Si el token es válido pero al cliente le falta el permiso, la respuesta es 403 con el código RECURSO_NO_AUTORIZADO.

Si aún no tienes un token, consulta la página Login del libro API nuby V2.

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

Todos los parámetros son opcionales y se envían en la dirección web (query string). Si no envías ninguno, recibes la primera página con los primeros 50 terceros ordenados por documento.

Importante: page y page_size deben ser números positivos. Un valor en cero, negativo o con letras produce 400; no se corrige automáticamente.

Los filtros se combinan. Si envías documento y tipo_doc_id al mismo tiempo, la búsqueda exige que se cumplan ambos.

Ejemplos de dirección

GET /third-parties/list?page=1&page_size=50
GET /third-parties/list?documento=900123456
GET /third-parties/list?nombre=acme&page_size=10
GET /third-parties/list?tipo_doc_id=1&page=2

Validaciones de parámetros

La consulta se valida antes de ejecutarse. Si un parámetro no cumple su regla, la respuesta es 400 VALIDATION_ERROR y no se devuelve ningún tercero:

Cuándo usar cada filtro

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

La respuesta tiene una estructura uniforme para todas las consultas de la API: los datos van en body y la información de paginación en pagination.

{
  "status": 200,
  "message": null,
  "body": [
    {
      "tercero_id": 123,
      "documento": "900123456",
      "tipo_doc_id": 1,
      "tipo_doc": "NIT",
      "nombre_completo": "ACME SAS",
      "email": "cuenta@acme.co",
      "telefono1": "6040000000",
      "direccion1": "CL 1 #2-3",
      "municipio_id": 1,
      "tipo_tercero_id": "1,2"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 1,
    "total_pages": 1
  },
  "filters_applied": {
    "documento": "900123456"
  }
}

Variantes de respuesta

El listado cambia el contenido de filters_applied y de message según los filtros y las coincidencias. Maneja estos tres casos:

Con filtros

{
  "status": 200,
  "message": null,
  "body": [
    {
      "tercero_id": 123,
      "documento": "900123456",
      "tipo_doc_id": 1,
      "tipo_doc": "NIT",
      "nombre_completo": "ACME SAS",
      "email": "cuenta@acme.co",
      "telefono1": "6040000000",
      "direccion1": "CL 1 #2-3",
      "municipio_id": 1,
      "tipo_tercero_id": "1,2"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 },
  "filters_applied": { "documento": "900123456" }
}

Sin filtros

Sin parámetros, filters_applied es null y recibes la primera página de todos los terceros, ordenados por documento ascendente.

{
  "status": 200,
  "message": null,
  "body": [
    {
      "tercero_id": 123,
      "documento": "900123456",
      "tipo_doc_id": 1,
      "tipo_doc": "NIT",
      "nombre_completo": "ACME SAS",
      "email": "cuenta@acme.co",
      "telefono1": "6040000000",
      "direccion1": "CL 1 #2-3",
      "municipio_id": 1,
      "tipo_tercero_id": "1,2"
    },
    {
      "tercero_id": 124,
      "documento": "901234567",
      "tipo_doc_id": 1,
      "tipo_doc": "NIT",
      "nombre_completo": "INVERSIONES ANDINAS SAS",
      "email": null,
      "telefono1": "6044445555",
      "direccion1": "CR 43A #1-50",
      "municipio_id": 1,
      "tipo_tercero_id": "1"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 2, "total_pages": 1 },
  "filters_applied": null
}

Lista vacía

No es un error: se responde 200 con body: [] y un mensaje informativo. Si enviaste filtros, filters_applied sigue reflejándolos.

{
  "status": 200,
  "message": "No se encontraron terceros con los filtros aplicados.",
  "body": [],
  "pagination": { "page": 1, "page_size": 50, "total": 0, "total_pages": 0 },
  "filters_applied": { "nombre": "zzz" }
}

Campos de cada tercero en la lista

Importante: la columna “Puede ser null” describe el contrato del endpoint para terceros creados o actualizados por la API. En terceros históricos de nuby algunos campos que hoy son obligatorios pueden estar vacíos o en null; no asumas que un campo marcado “No” siempre trae valor.

Lista vs. detalle

Paginación

filters_applied y message

Comportamiento de filters_applied y message

Campos del envelope

Una lista vacía no es un error. Cuando ningún tercero coincide con los filtros, el servicio responde 200 con body: []. Revisa pagination.total para confirmar que no hay coincidencias.

Orden de los resultados: la lista se ordena por documento ascendente y, cuando hay documentos repetidos, por tercero_id ascendente. El orden es estable entre páginas.

4. Seguridad y Posibles Errores

Ejemplo de parámetro inválido (400)

{
  "success": false,
  "status": 400,
  "message": "El parámetro \"page\" debe ser un número positivo.",
  "error_code": "VALIDATION_ERROR"
}

5. Ejemplos de integración

TOKEN="TU_TOKEN_AQUI"
INSTANCIA="tu-inmobiliaria.nuby.app"

# Buscar por documento exacto
curl -G "https://${INSTANCIA}/service/v2/public/third-parties/list" \
  --data-urlencode "documento=900123456" \
  -H "Authorization: Bearer ${TOKEN}"

# Buscar por nombre, página 1 de 10 registros
curl -G "https://${INSTANCIA}/service/v2/public/third-parties/list" \
  --data-urlencode "nombre=acme" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=10" \
  -H "Authorization: Bearer ${TOKEN}"

<?php

$instancia = 'tu-inmobiliaria.nuby.app';
$token = 'TU_TOKEN_AQUI';

$query = http_build_query([
    'documento' => '900123456',
    'page' => 1,
    'page_size' => 50,
]);

$url = "https://{$instancia}/service/v2/public/third-parties/list?{$query}";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$token}",
]);

$respuesta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$datos = json_decode($respuesta, true);

echo "HTTP: {$codigo}\n";
echo "Total: " . ($datos['pagination']['total'] ?? 0) . "\n";

foreach ($datos['body'] as $tercero) {
    echo $tercero['documento'] . ' - ' . $tercero['nombre_completo'] . "\n";
}

import requests

instancia = "tu-inmobiliaria.nuby.app"
token = "TU_TOKEN_AQUI"
url = f"https://{instancia}/service/v2/public/third-parties/list"

headers = {
    "Authorization": f"Bearer {token}",
}

pagina = 1
total_paginas = 1

while pagina <= total_paginas:
    respuesta = requests.get(
        url,
        headers=headers,
        params={"nombre": "acme", "page": pagina, "page_size": 50},
        timeout=30,
    )

    if respuesta.status_code != 200:
        print(respuesta.status_code, respuesta.json())
        break

    datos = respuesta.json()
    total_paginas = datos["pagination"]["total_pages"]

    for tercero in datos["body"]:
        print(tercero["documento"], tercero["nombre_completo"])

    pagina += 1

const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';

const params = new URLSearchParams({
  nombre: 'acme',
  page: '1',
  page_size: '10'
});

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

const respuesta = await fetch(url, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const data = await respuesta.json();

if (respuesta.ok) {
  console.log(`Página ${data.pagination.page} de ${data.pagination.total_pages}`);
  data.body.forEach(t => console.log(t.documento, t.nombre_completo));
} else {
  console.error(`${respuesta.status} ${data.error_code}: ${data.message}`);
}

let
    // 1. Configura tus datos de acceso
    instancia = "tu-inmobiliaria.nuby.app",
    token = "TU_TOKEN_AQUI",

    // 2. Prepara la dirección con el filtro y la página
    url = "https://" & instancia & "/service/v2/public/third-parties/list?nombre=acme&page=1&page_size=1000",

    // 3. Envía la petición GET
    response = Web.Contents(url, [
        Headers = [
            #"Authorization" = "Bearer " & token
        ]
    ]),

    // 4. Decodifica el envelope
    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",
        {"tercero_id", "documento", "tipo_doc_id", "tipo_doc", "nombre_completo",
         "email", "telefono1", "direccion1", "municipio_id", "tipo_tercero_id"},
        {"TerceroID", "Documento", "TipoDocID", "TipoDoc", "NombreCompleto",
         "Email", "Telefono1", "Direccion1", "MunicipioID", "TipoTerceroID"}),
    tipos = Table.TransformColumnTypes(expandido, {
        {"TerceroID", Int64.Type},
        {"TipoDocID", Int64.Type},
        {"MunicipioID", Int64.Type}
    }),
    totalPaginas = pagination[total_pages]
in
    tipos

6. Buenas prácticas y límites conocidos

Si el tercero que buscas no existe en nuby, puedes crearlo con el servicio Crear o Resolver Tercero.