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:

1. El Endpoint (La dirección web)

Método y dirección

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

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)

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.

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

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:

Campos del envelope

4. Seguridad y Posibles Errores

Errores frecuentes y solución

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

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

$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";
}

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())

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}`);
}

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

Límites de este servicio

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.