**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:
- **Buscar un tercero del que no conoces el identificador interno**, por documento exacto o por coincidencia parcial en el nombre.
- **Conciliar tus clientes con los que ya están en nuby.**
- **Construir un buscador en tu propia interfaz**, con paginación.
- **Obtener el `tercero_id`** que necesitan los demás servicios de la API.
---
**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**
```http
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:
**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.
- Si **no enviaste filtros**, `filters_applied` es `null`.
- Si **enviaste filtros**, `filters_applied` es un objeto con los filtros usados.
- Si hay resultados, `message` es `null`.
- Si no hay resultados, `message` es `No se encontraron terceros con los filtros aplicados.` y `body` es una lista vacía `[]`.
**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.
cURL
```bash
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
```php
'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";
}
```
Python
```python
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
```
JavaScript (Fetch API)
```javascript
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}`);
}
```
Power Query M (Excel / Power BI)
Power Query consulta una página por vez con `Web.Contents`. Puedes cambiar `nombre` por `documento` o `tipo_doc_id` en la cadena de la dirección.
```m
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
```
- **Para buscar un tercero concreto, usa `documento`.** Es coincidencia exacta y devuelve el registro correcto sin ambigüedad.
- **Usa `nombre` solo para búsquedas exploratorias.** Es coincidencia parcial y puede devolver varios terceros.
- **No pidas `page_size=1000` "por si acaso".** Pagina con un tamaño razonable y recorre con `page`.
- **Recorre hasta `total_pages`** y no hasta que una página venga vacía: si el filtro no tiene resultados, `total_pages` es `0`.
- **No uses la lista como detalle.** Para nombres y apellidos separados, ubicación completa, información tributaria y arreglo de tipos, consulta la página [*Buscar Tercero por Código*](https://docs.nuby.ai/books/api-nuby-v2/page/buscar-tercero-por-codigo).
- **Guarda el `tercero_id`** que encuentres: evita volver a buscar por documento en cada operación.
Si el tercero que buscas **no existe** en nuby, puedes crearlo con el servicio [*Crear o Resolver Tercero*](https://docs.nuby.ai/books/api-nuby-v2/page/crear-o-resolver-tercero).