Ir al contenido principal

Buscar Tercero por Código [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 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.

1. El Endpoint (La dirección web)

Método y dirección
Dato Valor
Método GET
Recurso /third-parties/{tercero_id}
Cuerpo de la petición No se envía cuerpo 
GET https://{{instancia}}/service/v2/public/third-parties/{tercero_id}

¿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
Encabezado Valor
Authorization Bearer <token>, con el token obtenido en el servicio Login.
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?)

Este servicio no requiere cuerpo: el único dato que envías es el identificador del tercero, que va en la dirección. Los encabezados requeridos se describen en la sección 1.

{tercero_id} es el identificador interno que devuelve nuby al crear o listar terceros. Debe ser un número: la dirección solo acepta dígitos.

Parámetros de la ruta (path)
Parámetro Tipo Requerido Descripción
tercero_id entero Sí Identificador interno del tercero. Va en la dirección, después de /third-parties/, y define qué tercero se devuelve.

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

{
  "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,2",
    "tipos": [1, 2]
  },
  "pagination": null,
  "filters_applied": null
}

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.

Campo Tipo Puede ser null Descripción
tercero_id entero No Identificador interno del tercero en nuby.
documento texto No Número de documento o NIT.
dv texto Sí Dígito de verificación, si está registrado.
tipo_doc_id entero No Identificador del tipo de documento.
tipo_doc texto Sí Nombre del tipo de documento (por ejemplo, NIT); puede ser null si el catálogo no lo resuelve.
nombre1 texto No Primer nombre o razón social. En una empresa, la razón social viene en este campo.
nombre2 texto Sí Segundo nombre, si está registrado.
apellido1 texto Sí Primer apellido, si está registrado.
apellido2 texto Sí Segundo apellido, si está registrado.
nombre_completo texto No Nombre unificado, listo para mostrar.
direccion1 texto No Dirección principal.
direccion2 texto Sí Dirección secundaria.
telefono1 texto Sí Teléfono principal.
telefono2 texto Sí Teléfono secundario.
fax texto Sí Fax registrado.
email texto Sí Correo principal.
email_cumpleanos texto Sí Correo alterno para cumpleaños.
persona entero Sí 1 persona natural, 2 persona jurídica.
tipo_persona_id entero Sí Identificador de la maestra de tipo de persona.
regimen_id entero Sí Identificador del régimen tributario.
resp_fiscal_id entero Sí Identificador de la responsabilidad fiscal.
tratamiento_id entero Sí Identificador de la maestra de tratamiento.
autoretenedor indicador Sí Indicador de autorretenedor.
gran_contribuyente indicador Sí Indicador de gran contribuyente.
banco_id entero Sí Identificador del banco.
intTipoCuentaB entero Sí Tipo de cuenta bancaria.
no_cuenta texto Sí Número de cuenta bancaria.
aplica_documento_soporte indicador Sí Indicador de documento soporte.
codigo_postal texto Sí Código postal.
municipio_id entero No Identificador del municipio.
municipio texto Sí Nombre del municipio resuelto.
departamento texto Sí Nombre del departamento resuelto.
pais texto Sí Nombre del país resuelto.
tipo_tercero_id texto Sí Tipos del tercero en una cadena separada por comas, por ejemplo "1,2".
tipos arreglo Sí Los mismos tipos como arreglo de enteros ordenado de menor a mayor, por ejemplo [1, 2].

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
{
  "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
{
  "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
{
  "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
Variante persona tipos Qué cambia
Persona natural 1 [2] Nombres y apellidos por separado; documento que no es NIT.
Persona jurídica 2 [1] Razón social en nombre1; documento de tipo NIT.
Varios tipos 1 o 2 [1, 2] tipo_tercero_id es "1,2" y tipos repite los mismos valores.
Campos que no devuelve el detalle

Algunos datos se aceptan al crear el tercero, pero no forman parte de la respuesta de lectura. No los esperes en el body:

Campo Por qué no aparece Dónde consultarlo
sexo No forma parte del contrato de lectura. Módulo de terceros de nuby.
fecha_nacimiento No forma parte del contrato de lectura. Módulo de terceros de nuby.
autore_res Es un dato de creación que el detalle no devuelve. Información tributaria del tercero, en nuby.
gran_contr_res Es un dato de creación que el detalle no devuelve. Información tributaria del tercero, en nuby.
representante No se incluye en la respuesta de lectura. Módulo de terceros de nuby.
representante_legal No se incluye en la respuesta de lectura. Módulo de terceros de nuby.
certificado Es un dato de creación, no de consulta. Módulo de terceros de nuby.
Contactos, archivos, bitácoras y documentos No forman parte de esta API. Módulo de terceros de nuby.
Campos del envelope
Campo Valor en el detalle Significado
status 200 Consulta exitosa.
message null No hay mensaje informativo en una consulta con resultados.
body Objeto con el detalle Cabecera, datos de contacto, ubicación, información tributaria y tipos.
pagination null Es un solo registro, no una lista paginada.
filters_applied null La ruta usa el identificador, no filtros de consulta.

4. Seguridad y Posibles Errores

HTTP error_code Cuándo ocurre y cómo resolverlo
401 — No enviaste el encabezado Authorization, o el token no existe o expiró. Vuelve a consumir Login.
403 CONSUMIDOR_NO_AUTENTICADO El token es válido, pero no corresponde a un cliente OAuth habilitado para consumir la API.
403 RECURSO_NO_AUTORIZADO Al cliente OAuth le falta el permiso catalogs:read.
404 TERCERO_NO_ENCONTRADO No existe un tercero con ese identificador. Verifica el tercero_id o búscalo por documento en la página Listar Terceros.
500 INTERNAL_ERROR Fallo interno al consultar. Reintenta; si persiste, contacta a soporte.
Errores frecuentes y solución
Código Causa Qué hacer
401 No enviaste el token o ya expiró. Vuelve a consumir Login y repite la consulta.
403 RECURSO_NO_AUTORIZADO Al cliente OAuth le falta el permiso catalogs:read. Solicita el scope a tu administrador en nuby.
404 TERCERO_NO_ENCONTRADO El tercero_id no existe en nuby. Verifica el identificador o busca por documento con Listar Terceros.
404 TERCERO_NO_ENCONTRADO Enviaste el documento en la ruta (/third-parties/900123456) en lugar del identificador interno. Usa /third-parties/list?documento=... para resolver el documento.
500 INTERNAL_ERROR Fallo interno al consultar. Reintenta; si persiste, contacta a soporte con el tercero_id consultado.
Ejemplo de tercero inexistente (404)
{
  "success": false,
  "status": 404,
  "message": "No se encontró el tercero con el código solicitado.",
  "error_code": "TERCERO_NO_ENCONTRADO"
}

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

5. Ejemplos de integración

cURL 
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

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

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

$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);

if ($codigo === 200) {
    $tercero = $datos['body'];
    echo $tercero['documento'] . ' - ' . $tercero['nombre_completo'] . "\n";
    echo $tercero['municipio'] . ', ' . $tercero['departamento'] . "\n";
} else {
    echo "HTTP {$codigo}: " . $datos['message'] . "\n";
}
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) 
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.

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

6. Buenas prácticas y límites conocidos

Recomendaciones
  • 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.
Límites de este servicio
  • 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.

Para buscar por documento o listar terceros, revisa la página Listar Terceros. Para crear un tercero nuevo o resolver uno existente, revisa Crear o Resolver Tercero.

¿Necesita ayuda adicional?

Nuestro equipo de soporte está disponible para asistirle:

Escríbenos a nuestro correo:

📞 (604) 444-7417 Opción 2

📧 soporte@nuby.ai

Escríbenos a nuestra línea de Whatsapp:

Whatsapp

Síguenos en nuestras redes sociales:

Instagram LinkedIn YouTube TikTok
Volver arriba