Actualizar un 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 hace un upsert por documento: si el tercero existe, actualiza solo los campos que envías; si no existe, lo crea. Está pensado para que tu aplicación pueda propagar cambios sin conocer el tercero_id de nuby.

La regla más importante: lo que no envías se conserva. Esto aplica a los tipos de tercero, a los datos del cónyuge y a cualquier otro campo o JSON. No se borra nada por omisión.

¿Para qué sirve este servicio?
Úsalo para mantener el tercero de nuby alineado con el de tu plataforma sin guardar ni mapear identificadores internos. Los casos de uso más frecuentes son:

1. El Endpoint (La dirección web)

Método y dirección

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

¿Qué debo colocar en {{instancia}}?

Es la dirección web principal con la que ingresas a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co. Si entras a nuby escribiendo inmobiliaria.nuby.app en el navegador, esa es tu instancia.

Importante: no incluyas https:// ni barras diagonales (/) al final. La dirección se compone así: https:// + tu instancia + /service/v2/public/third-parties.

Encabezados requeridos

Permiso requerido (scope): third-parties:update

El cliente OAuth con el que se genera el token debe tener habilitado el permiso third-parties:update. 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.

Requisitos previos de esta operación

El documento es la clave. No se modifica por este endpoint: un documento distinto identifica otro tercero.

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

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

Obligatorios en el alta

referencia_externa, documento, tipo_doc_id, nombre1, direccion1, municipio_id y al menos un tipo (tipo_tercero_id o tipos[]).

Obligatorios en la edición

referencia_externa y documento. El resto es opcional: solo se actualiza lo que envías.

Campos del cuerpo

Campos que se ignoran: los campos fuera de esta lista (por ejemplo tercero_id, creadopor o password_hash) nunca se escriben y no generan error.

Preservación

Ejemplos de cuerpo

Actualizar solo el email de un tercero que ya existe:

{
  "referencia_externa": "TP-2026-0001-EDIT-1",
  "documento": "900123456",
  "email": "nuevo@acme.co"
}

Crear si no existe, con los obligatorios del alta:

{
  "referencia_externa": "TP-2026-0002",
  "documento": "900654321",
  "tipo_doc_id": 1,
  "nombre1": "ACME SAS",
  "tipo_tercero_id": 1,
  "direccion1": "CL 1 #2-3",
  "municipio_id": 1
}

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

Si el tercero existe y el payload es válido, la respuesta es 200 con el identificador del tercero y los indicadores de la operación:

{
  "success": true,
  "status": 200,
  "message": "Tercero actualizado.",
  "body": {
    "tercero_id": 123,
    "documento": "900123456",
    "created": false,
    "updated": true,
    "idempotent_replay": false
  }
}

Estructura principal de la respuesta

Las respuestas de escritura no traen pagination ni filters_applied: esos campos pertenecen a las consultas de lectura.

Campos del cuerpo (body)

Escenarios alternativos

Si el documento no existía y el payload trae los obligatorios, responde 201 con created: true, updated: false. El body queda así:

{
  "tercero_id": 124,
  "documento": "900654321",
  "created": true,
  "updated": false,
  "idempotent_replay": false
}

idempotent_replay: true indica que la respuesta viene de un reintento con la misma referencia_externa:

{
  "tercero_id": 123,
  "documento": "900123456",
  "created": false,
  "updated": true,
  "idempotent_replay": true
}

4. Idempotencia y reintentos

Toda escritura exige referencia_externa. La clave lógica es la combinación de tu origen, el recurso tercero y la referencia; el hash del payload es SHA-256 sobre una forma canónica del JSON, así que el orden de las llaves no altera la comparación.

Una referencia por cambio. Una referencia distinta habilita un cambio nuevo sobre el mismo documento; reutilizar la anterior devuelve la respuesta vieja y tu cambio no se aplica.

5. Seguridad y Posibles Errores

Tu pase tiene fecha de caducidad

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el sistema te bloquea el acceso con un error 401 y tu sistema debe volver a consumir el servicio de Login para pedir un pase nuevo.

Esta respuesta la produce el middleware de autenticación y no el contrato de la operación, así que usa el envelope heredado (statusCode y error.description), no success ni error_code:

Errores del contrato de la operación

Los errores de la operación traen success: false, el código HTTP, un message legible y un error_code estable:

Mensajes de validación frecuentes

Trata el 409 TERCERO_IDENTIDAD_CONFLICTIVA como un caso de negocio, no como una falla técnica: ese documento existe en nuby con otro tipo de documento, y este endpoint no lo cambia. No lo reintentes con el mismo payload.

6. Ejemplos de integración

Aquí tienes ejemplos listos para adaptar a tu plataforma. Todos usan {{instancia}}, Authorization: Bearer, actualizan solo el email de un tercero y tratan el éxito (200/201) junto con los rechazos de negocio más frecuentes (409 y 422).

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

curl -X PUT "https://${INSTANCIA}/service/v2/public/third-parties" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "referencia_externa": "TP-2026-0001-EDIT-1",
    "documento": "900123456",
    "email": "nuevo@acme.co"
  }'

<?php
$instancia = 'mi-inmobiliaria.nuby.app'; // Tu dirección web completa
$token     = 'TU_TOKEN_AQUI';            // Token obtenido del servicio Login

$payload = [
    'referencia_externa' => 'TP-2026-0001-EDIT-1',
    'documento'          => '900123456',
    'email'              => 'nuevo@acme.co',
];

$ch = curl_init("https://{$instancia}/service/v2/public/third-parties");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

$info = json_decode($respuesta, true);

if ($httpCode === 200 || $httpCode === 201) {
    echo "Tercero {$info['body']['tercero_id']}: {$httpCode}\n";
    echo "Creado: " . var_export($info['body']['created'], true) . "\n";
    echo "Actualizado: " . var_export($info['body']['updated'], true) . "\n";
} elseif ($httpCode === 409 || $httpCode === 422) {
    echo "Rechazo de negocio {$info['error_code']}: {$info['message']}\n";
} else {
    echo "Error HTTP {$httpCode}: {$info['message']}\n";
}

import requests

# 1. Configura tus datos de acceso
instancia = "mi-inmobiliaria.nuby.app"  # Reemplaza con tu dirección web completa
token = "TU_TOKEN_AQUI"                 # Token obtenido del servicio Login

# 2. Prepara el cuerpo y envía la petición
url = f"https://{instancia}/service/v2/public/third-parties"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}
payload = {
    "referencia_externa": "TP-2026-0001-EDIT-1",
    "documento": "900123456",
    "email": "nuevo@acme.co",
}

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

# 3. Procesa la respuesta
if respuesta.status_code in (200, 201):
    body = respuesta.json()["body"]
    print(f"Tercero {body['tercero_id']} - creado: {body['created']} - actualizado: {body['updated']}")
elif respuesta.status_code in (409, 422):
    error = respuesta.json()
    print(f"Rechazo de negocio {error['error_code']}: {error['message']}")
else:
    print(f"Error HTTP {respuesta.status_code}: {respuesta.text}")

// 1. Configura tus datos de acceso
const instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa
const token = 'TU_TOKEN_AQUI';                // Token obtenido del servicio Login

// 2. Función que actualiza (o crea) el tercero
async function actualizarTercero(payload) {
  const url = `https://${instancia}/service/v2/public/third-parties`;

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

  const info = await response.json().catch(() => ({}));

  if (!response.ok) {
    console.error(`Error HTTP ${response.status} ${info.error_code ?? ''}: ${info.message ?? ''}`);
    return null;
  }

  return info.body;
}

// 3. Cambia solo el email y revisa el resultado
actualizarTercero({
  referencia_externa: 'TP-2026-0001-EDIT-1',
  documento: '900123456',
  email: 'nuevo@acme.co',
}).then((body) => {
  if (!body) {
    return;
  }

  console.log(`Tercero ${body.tercero_id} creado: ${body.created} actualizado: ${body.updated}`);
});

7. Buenas prácticas y límites conocidos

Recomendaciones

Límites de este servicio