Crear o Resolver Tercero [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 registra un tercero en nuby —es decir, una persona natural o jurídica con la que tu inmobiliaria se relaciona: un cliente, un propietario, un proveedor, un arrendatario— y le asigna sus tipos o roles dentro del sistema. Si el documento ya existe en nuby, no se crea un duplicado: el servicio devuelve el tercero que ya estaba registrado. Si no existe, lo crea en ese mismo momento.

Es el servicio que necesitas cuando tu plataforma maneja sus propios clientes y quiere que nuby tenga la misma información, sin pedirle al usuario que vuelva a digitar los datos en dos sistemas.

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

¿Ya tienes el tercero_id? Si tu sistema ya guardó el identificador interno de nuby, puedes seguir usándolo directamente en los demás servicios. Si solo tienes el documento, este es el servicio que lo resuelve.

1. El Endpoint (La dirección web)

Método y dirección

Apunta tu sistema a la siguiente dirección de petición POST:

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

¿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. Por ejemplo, si entras en inmobiliaria.nuby.app, esa es tu instancia. No incluyas https:// ni barras diagonales al final.

Encabezados requeridos

Permiso requerido (scope)

El cliente OAuth con el que se genera el token debe tener habilitado el permiso third-parties:create. Si el token es válido pero al cliente le falta ese 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. Allí se explica cómo identificarte y cómo se construye el encabezado Authorization.

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

El cuerpo debe ser un objeto JSON. La raíz del JSON lleva la referencia de idempotencia y, al mismo nivel, los datos del tercero.

Campos obligatorios

Importante: los datos obligatorios se exigen cuando el tercero no existe. Si el documento ya está registrado, nuby lo resuelve y no valida ni actualiza el resto de los campos.

Campos opcionales

Campos opcionales: tipo y descripción

Los campos opcionales se guardan si vienen, pero ninguno reemplaza a un obligatorio. Los identificadores se validan contra las maestras y, si no existen, la respuesta es 422.

Sobre persona: 1 indica persona natural y 2 persona jurídica. Si lo envías, nuby valida que el tipo de documento sea coherente: una persona natural no puede registrarse con NIT, y una persona jurídica debe registrarse con NIT. Si no lo envías, esa coherencia no se valida.

Campos que se ignoran: si envías campos que no están en las listas anteriores (por ejemplo tercero_id, creadopor o password_hash), el servicio los descarta en silencio y nunca los escribe. No se responde error por ese motivo.

Cómo se envían los tipos de tercero

Puedes enviar el rol del tercero de dos formas, y también combinarlas:

Si envías ambos, nuby los une en una sola lista, elimina los repetidos y conserva el orden. Los valores deben ser números enteros mayores que cero; los valores inválidos se descartan y, si al final no queda ningún tipo, la respuesta es 422.

Ejemplo: persona natural

Para una persona natural envía persona: 1 y un tipo de documento que no sea NIT. El identificador 2 del ejemplo es ilustrativo: usa el que corresponda a cédula en la maestra de tu instancia.

{
  "referencia_externa": "TP-000124",
  "documento": "1020304050",
  "tipo_doc_id": 2,
  "persona": 1,
  "nombre1": "María",
  "apellido1": "Gómez",
  "direccion1": "CL 10 #5-20",
  "municipio_id": 1,
  "tipo_tercero_id": 2,
  "email": "maria.gomez@example.co",
  "telefono1": "3001234567"
}

nuby almacena los nombres y apellidos en mayúsculas: este envío queda como MARÍA GÓMEZ.

Ejemplo: persona jurídica

Para una persona jurídica envía persona: 2 y un documento de tipo NIT. Si además necesitas asignarle varios roles, combina tipo_tercero_id con tipos[].

{
  "referencia_externa": "TP-000125",
  "documento": "901234567",
  "tipo_doc_id": 1,
  "persona": 2,
  "nombre1": "Inversiones Andinas SAS",
  "direccion1": "CR 43A #1-50",
  "municipio_id": 1,
  "tipo_tercero_id": 1,
  "tipos": [2],
  "email": "contacto@andinas.co",
  "telefono1": "6044445555"
}

El ejemplo usa tipo_doc_id: 1 para NIT, igual que el contrato. La coherencia con persona: 2 se valida antes de crear el tercero.

Ejemplo completo de la petición

{
  "referencia_externa": "TP-000123",
  "documento": "900123456",
  "tipo_doc_id": 1,
  "nombre1": "Acme SAS",
  "tipo_tercero_id": 1,
  "tipos": [2],
  "direccion1": "CL 1 #2-3",
  "municipio_id": 1,
  "email": "cuenta@acme.co",
  "telefono1": "6040000000"
}

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

El servicio tiene dos resultados posibles, y ambos son exitosos:

Tercero creado (201 Created)

{
  "success": true,
  "status": 201,
  "message": "Tercero creado.",
  "body": {
    "tercero_id": 123,
    "created": true,
    "documento": "900123456"
  }
}

Tercero existente (200 OK)

{
  "success": true,
  "status": 200,
  "message": "Tercero existente resuelto.",
  "body": {
    "tercero_id": 123,
    "created": false,
    "documento": "900123456"
  }
}

Reintento de una solicitud ya completada (replay)

Si repites la petición con la misma referencia_externa y el mismo contenido, nuby devuelve la respuesta original —con el mismo código HTTP— y le agrega la marca idempotent_replay: true:

{
  "success": true,
  "status": 201,
  "message": "Tercero creado.",
  "body": {
    "tercero_id": 123,
    "created": true,
    "documento": "900123456"
  },
  "idempotent_replay": true
}

Estructura del envelope de respuesta

Una escritura no devuelve pagination ni filters_applied: la respuesta es el resultado de la operación.

Qué contiene el cuerpo de la respuesta

La respuesta de este servicio es corta a propósito. Si necesitas el detalle completo del tercero (nombres, apellidos, ubicación, tipos, información tributaria), consulta la página Buscar Tercero por Código.

4. Cómo decide nuby si crea o resuelve

El servicio sigue siempre el mismo orden. Conocerlo te ayuda a interpretar las respuestas:

Ojo con las mayúsculas: los nombres y apellidos (nombre1, nombre2, apellido1, apellido2) se almacenan en mayúsculas. Si envías "Acme SAS", en nuby quedará "ACME SAS".

Ojo con el documento: solo se aceptan letras y números. Un documento con puntos, guiones o espacios (por ejemplo 900.123.456) no pasa la validación. Envíalo normalizado: 900123456.

Un tercero, un registro. El documento es único en nuby. Por eso dos envíos con el mismo documento —aunque traigan otro nombre— apuntan siempre al mismo tercero.

5. Idempotencia y reintentos

Toda escritura en esta API exige referencia_externa. nuby guarda la combinación (consumidor, recurso, referencia_externa) y recuerda qué respondió, para que un reintento no duplique el registro.

Importante: una respuesta 422 por datos inválidos no consume la referencia. Puedes corregir el contenido y reintentar con la misma referencia_externa sin conflicto.

Atención: no reutilices una referencia_externa para operaciones distintas. Si usas la misma referencia con un contenido diferente, nuby responde 409 IDEMPOTENCY_PAYLOAD_MISMATCH y no procesa nada. La referencia debe identificar una operación concreta, no un tercero.

Recomendación: guarda en tu plataforma la relación referencia_externa → tercero_id. Así puedes reintentar con seguridad ante timeouts o caídas de red, y sabes a qué tercero corresponde cada operación.

6. Seguridad y Posibles Errores

Las respuestas de error traen siempre success: false, el código HTTP, un message legible y un error_code estable que puedes usar en tu lógica.

Ejemplo de error de validación (422)

{
  "success": false,
  "status": 422,
  "message": "La solicitud contiene errores de validación.",
  "error_code": "VALIDATION_ERROR",
  "errors": {
    "direccion1": [
      "El campo \"Dirección Principal\" es obligatorio."
    ]
  }
}

El objeto errors está indexado por el nombre técnico del campo, y cada entrada es una lista de mensajes. Las validaciones más frecuentes son:

Validaciones y mensajes

Atención: cuando la respuesta es 422, nuby no crea ni modifica ningún tercero. Es seguro corregir el contenido y volver a enviar.

Casos especiales

Estos escenarios explican la mayoría de las dudas de integración. La regla que manda siempre es la misma: primero se resuelve el documento y, si ya existe, el resto del payload no se valida.

Tercero existente con payload incompleto

Persona natural con NIT

Documento con puntos o guiones

Campos ignorados

tipos[] + tipo_tercero_id

7. Ejemplos de integración

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

curl -X POST "https://${INSTANCIA}/service/v2/public/third-parties" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "referencia_externa": "TP-000123",
    "documento": "900123456",
    "tipo_doc_id": 1,
    "nombre1": "ACME SAS",
    "tipo_tercero_id": 1,
    "tipos": [2],
    "direccion1": "CL 1 #2-3",
    "municipio_id": 1,
    "email": "cuenta@acme.co",
    "telefono1": "6040000000"
  }'

<?php

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

$payload = [
    'referencia_externa' => 'TP-000123',
    'documento' => '900123456',
    'tipo_doc_id' => 1,
    'nombre1' => 'ACME SAS',
    'tipo_tercero_id' => 1,
    'tipos' => [2],
    'direccion1' => 'CL 1 #2-3',
    'municipio_id' => 1,
    'email' => 'cuenta@acme.co',
    'telefono1' => '6040000000',
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

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

echo "HTTP: {$codigo}\n";
print_r(json_decode($respuesta, true));

import requests

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

payload = {
    "referencia_externa": "TP-000123",
    "documento": "900123456",
    "tipo_doc_id": 1,
    "nombre1": "ACME SAS",
    "tipo_tercero_id": 1,
    "tipos": [2],
    "direccion1": "CL 1 #2-3",
    "municipio_id": 1,
    "email": "cuenta@acme.co",
    "telefono1": "6040000000",
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

respuesta = requests.post(url, json=payload, headers=headers, timeout=30)

if respuesta.ok:
    datos = respuesta.json()
    print(f"Tercero {datos['body']['tercero_id']} — creado: {datos['body']['created']}")
else:
    print(respuesta.status_code, respuesta.json())

const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const url = `https://${instancia}/service/v2/public/third-parties`;

const payload = {
  referencia_externa: 'TP-000123',
  documento: '900123456',
  tipo_doc_id: 1,
  nombre1: 'ACME SAS',
  tipo_tercero_id: 1,
  tipos: [2],
  direccion1: 'CL 1 #2-3',
  municipio_id: 1,
  email: 'cuenta@acme.co',
  telefono1: '6040000000'
};

const respuesta = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(payload)
});

const data = await respuesta.json();

if (respuesta.ok) {
  console.log(`Tercero ${data.body.tercero_id} — creado: ${data.body.created}`);
} else {
  console.error(`${respuesta.status} ${data.error_code}: ${data.message}`, data.errors ?? {});
}

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

    // 2. Prepara la dirección de la petición
    url = "https://" & instancia & "/service/v2/public/third-parties",

    // 3. Construye el cuerpo JSON
    cuerpo = Json.FromValue([
        referencia_externa = "TP-000123",
        documento = "900123456",
        tipo_doc_id = 1,
        nombre1 = "ACME SAS",
        tipo_tercero_id = 1,
        tipos = {2},
        direccion1 = "CL 1 #2-3",
        municipio_id = 1,
        email = "cuenta@acme.co",
        telefono1 = "6040000000"
    ]),

    // 4. Envía la petición POST
    response = Web.Contents(url, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ],
        Content = cuerpo
    ]),

    // 5. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],

    // 6. Convierte el resultado en tabla
    tabla = Table.FromList({body}, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"tercero_id", "created", "documento"},
        {"TerceroID", "Creado", "Documento"}),
    tipos = Table.TransformColumnTypes(expandido, {
        {"TerceroID", Int64.Type},
        {"Creado", type logical}
    })
in
    tipos

8. Buenas prácticas y límites conocidos

Recomendaciones

Límites de este servicio

Lo que este servicio NO hace

Para consultar terceros ya registrados, revisa las páginas Listar Terceros y Buscar Tercero por Código.