**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 el **detalle completo de un tercero** a partir de su identificador interno en nuby (`tercero_id`): documento, nombres y apellidos por separado, datos de contacto, ubicación (municipio, departamento y país) y sus tipos o roles.
Úsalo después de crear o resolver un tercero, o cuando ya guardaste su `tercero_id` y necesitas todos sus datos sin volver a buscarlo por documento.
**¿Para qué sirve este servicio?**
Los casos de uso más frecuentes de este servicio son:
- **Mostrar el detalle completo de un tercero** en tu interfaz, con nombres y apellidos por separado.
- **Recuperar el contacto y la ubicación** del tercero (municipio, departamento y país) sin volver a buscarlo por documento.
- **Confirmar los tipos o roles** del tercero antes de usarlo en otro proceso.
- **Evitar guardar datos derivados** como `nombre_completo`: nuby los entrega listos.
---
**Nota sobre el envelope:** esta es una consulta de un solo registro, así que `pagination` y `filters_applied` siempre vienen en `null`.
##### **Campos del detalle**
**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.
**Importante:** los campos que no tienen valor registrado vienen en `null`, no se omiten. Verifica `null` antes de usar un dato en tu interfaz.
##### **Variantes de respuesta**
El detalle cambia según el tipo de persona y los roles del tercero. Los identificadores y etiquetas de las maestras (`tipo_doc`) varían por instancia; los ejemplos usan Cédula y NIT como referencia.
##### **Persona natural**
```json
{
"status": 200,
"message": null,
"body": {
"tercero_id": 124,
"documento": "1020304050",
"dv": null,
"tipo_doc_id": 2,
"tipo_doc": "Cédula",
"nombre1": "MARÍA",
"nombre2": null,
"apellido1": "GÓMEZ",
"apellido2": null,
"nombre_completo": "MARÍA GÓMEZ",
"direccion1": "CL 10 #5-20",
"direccion2": null,
"telefono1": "3001234567",
"telefono2": null,
"fax": null,
"email": "maria.gomez@example.co",
"email_cumpleanos": null,
"persona": 1,
"tipo_persona_id": null,
"regimen_id": null,
"resp_fiscal_id": null,
"tratamiento_id": null,
"autoretenedor": null,
"gran_contribuyente": null,
"banco_id": null,
"intTipoCuentaB": null,
"no_cuenta": null,
"aplica_documento_soporte": null,
"codigo_postal": null,
"municipio_id": 1,
"municipio": "Medellin",
"departamento": "Antioquia",
"pais": "Colombia",
"tipo_tercero_id": "2",
"tipos": [2]
},
"pagination": null,
"filters_applied": null
}
```
En una persona natural, `nombre2` y `apellido2` pueden venir en `null` si no están registrados. Los campos tributarios y bancarios también pueden ser `null`.
##### **Persona jurídica**
```json
{
"status": 200,
"message": null,
"body": {
"tercero_id": 123,
"documento": "900123456",
"dv": null,
"tipo_doc_id": 1,
"tipo_doc": "NIT",
"nombre1": "ACME",
"nombre2": null,
"apellido1": "SAS",
"apellido2": null,
"nombre_completo": "ACME SAS",
"direccion1": "CL 1 #2-3",
"direccion2": null,
"telefono1": "6040000000",
"telefono2": null,
"fax": null,
"email": "cuenta@acme.co",
"email_cumpleanos": null,
"persona": 2,
"tipo_persona_id": null,
"regimen_id": null,
"resp_fiscal_id": null,
"tratamiento_id": null,
"autoretenedor": null,
"gran_contribuyente": null,
"banco_id": null,
"intTipoCuentaB": null,
"no_cuenta": null,
"aplica_documento_soporte": null,
"codigo_postal": null,
"municipio_id": 1,
"municipio": "Medellin",
"departamento": "Antioquia",
"pais": "Colombia",
"tipo_tercero_id": "1",
"tipos": [1]
},
"pagination": null,
"filters_applied": null
}
```
En una persona jurídica, la razón social viene en `nombre1` y el NIT en `documento`. `apellido1` puede contener la terminación societaria o venir en `null`.
##### **Tercero con varios tipos**
```json
{
"status": 200,
"message": null,
"body": {
"tercero_id": 125,
"documento": "901234567",
"dv": null,
"tipo_doc_id": 1,
"tipo_doc": "NIT",
"nombre1": "INVERSIONES ANDINAS SAS",
"nombre2": null,
"apellido1": null,
"apellido2": null,
"nombre_completo": "INVERSIONES ANDINAS SAS",
"direccion1": "CR 43A #1-50",
"direccion2": null,
"telefono1": "6044445555",
"telefono2": null,
"fax": null,
"email": "contacto@andinas.co",
"email_cumpleanos": null,
"persona": 2,
"tipo_persona_id": null,
"regimen_id": null,
"resp_fiscal_id": null,
"tratamiento_id": null,
"autoretenedor": null,
"gran_contribuyente": null,
"banco_id": null,
"intTipoCuentaB": null,
"no_cuenta": null,
"aplica_documento_soporte": null,
"codigo_postal": null,
"municipio_id": 1,
"municipio": "Medellin",
"departamento": "Antioquia",
"pais": "Colombia",
"tipo_tercero_id": "1,2",
"tipos": [1, 2]
},
"pagination": null,
"filters_applied": null
}
```
##### **Comparación de variantes**
**Ojo con el identificador:** `tercero_id` es el número interno de nuby, no el documento del tercero. Si envías un documento en la dirección (por ejemplo `/third-parties/900123456`), no obtendrás el tercero que buscas. Para buscar por documento usa `/third-parties/list?documento=...`.
cURL
```bash
TOKEN="TU_TOKEN_AQUI"
INSTANCIA="tu-inmobiliaria.nuby.app"
TERCERO_ID=123
curl "https://${INSTANCIA}/service/v2/public/third-parties/${TERCERO_ID}" \
-H "Authorization: Bearer ${TOKEN}"
```
PHP
```php
Python
```python
import requests
instancia = "tu-inmobiliaria.nuby.app"
token = "TU_TOKEN_AQUI"
tercero_id = 123
url = f"https://{instancia}/service/v2/public/third-parties/{tercero_id}"
headers = {
"Authorization": f"Bearer {token}",
}
respuesta = requests.get(url, headers=headers, timeout=30)
if respuesta.status_code == 200:
tercero = respuesta.json()["body"]
print(tercero["documento"], "-", tercero["nombre_completo"])
print(tercero["municipio"], ",", tercero["departamento"], "-", tercero["pais"])
print("Tipos:", tercero["tipos"])
else:
print(respuesta.status_code, respuesta.json())
```
JavaScript (Fetch API)
```javascript
const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const terceroId = 123;
const url = `https://${instancia}/service/v2/public/third-parties/${terceroId}`;
const respuesta = await fetch(url, {
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await respuesta.json();
if (respuesta.ok) {
const tercero = data.body;
console.log(tercero.nombre_completo, tercero.documento);
console.log('Tipos:', tercero.tipos);
} else {
console.error(`${respuesta.status} ${data.error_code}: ${data.message}`);
}
```
Power Query M (Excel / Power BI)
Power Query convierte el detalle en una tabla de una fila. Los campos anidados, como `tipos`, se conservan como lista y puedes expandirlos si necesitas una fila por tipo.
```m
let
// 1. Configura tus datos de acceso
instancia = "tu-inmobiliaria.nuby.app",
token = "TU_TOKEN_AQUI",
terceroId = "123",
// 2. Prepara la dirección de la petición
url = "https://" & instancia & "/service/v2/public/third-parties/" & terceroId,
// 3. Envía la petición GET
response = Web.Contents(url, [
Headers = [
#"Authorization" = "Bearer " & token
]
]),
// 4. Decodifica la respuesta JSON
jsonResponse = Json.Document(response),
body = jsonResponse[body],
// 5. Convierte el detalle en tabla
tabla = Table.FromList({body}, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
expandido = Table.ExpandRecordColumn(tabla, "Column1",
{"tercero_id", "documento", "dv", "tipo_doc_id", "tipo_doc",
"nombre1", "nombre2", "apellido1", "apellido2", "nombre_completo",
"direccion1", "direccion2", "telefono1", "telefono2", "fax",
"email", "email_cumpleanos", "persona", "tipo_persona_id",
"regimen_id", "resp_fiscal_id", "tratamiento_id", "autoretenedor",
"gran_contribuyente", "banco_id", "intTipoCuentaB", "no_cuenta",
"aplica_documento_soporte", "codigo_postal", "municipio_id",
"municipio", "departamento", "pais", "tipo_tercero_id", "tipos"},
{"TerceroID", "Documento", "DV", "TipoDocID", "TipoDoc",
"Nombre1", "Nombre2", "Apellido1", "Apellido2", "NombreCompleto",
"Direccion1", "Direccion2", "Telefono1", "Telefono2", "Fax",
"Email", "EmailCumpleanos", "Persona", "TipoPersonaID",
"RegimenID", "RespFiscalID", "TratamientoID", "Autoretenedor",
"GranContribuyente", "BancoID", "IntTipoCuentaB", "NoCuenta",
"AplicaDocumentoSoporte", "CodigoPostal", "MunicipioID",
"Municipio", "Departamento", "Pais", "TipoTerceroID", "Tipos"}),
tipos = Table.TransformColumnTypes(expandido, {
{"TerceroID", Int64.Type},
{"TipoDocID", Int64.Type},
{"MunicipioID", Int64.Type},
{"Persona", Int64.Type}
})
in
tipos
```
- **Consulta el detalle solo cuando lo necesites.** Si solo vas a usar el identificador, la respuesta de **Crear o Resolver Tercero** ya te lo entrega.
- **Usa `nombre_completo` para mostrar** y los campos separados (`nombre1`, `apellido1`, ...) cuando necesites componer un formato propio.
- **Trata el `404` como un caso de negocio**, no como una falla técnica: significa que el identificador no existe en nuby.
- **Recuerda que los campos ausentes vienen en `null`**; no supongas cadenas vacías.
- Solo devuelve terceros que **existen** en nuby; no consulta maestras ni catálogos.
- El detalle **no incluye** algunos datos que sí se pueden enviar al crear el tercero, como `sexo`, `fecha_nacimiento`, `autore_res`, `gran_contr_res`, `representante`, `representante_legal` o `certificado`.
- El detalle **no incluye** contactos, archivos, bitácoras ni documentos del tercero.