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

**¿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:

- **Propagar un cambio de datos** del tercero —nombre, dirección, teléfono o correo— desde tu sistema hacia nuby. - **Actualizar un solo campo** (por ejemplo el `email`) sin reenviar el resto: lo que no envías se conserva. - **Crear el tercero si el documento todavía no existe**, con el mismo servicio y los obligatorios del alta. - **Corregir datos sin tocar los tipos ni el cónyuge** que ya estaban registrados. - **Propagar cambios desde un sistema que solo conoce el documento** del cliente, no el `tercero_id`. ---

Dato	Valor
Método	`PUT`
Ruta	`/third-parties`
Scope requerido	`third-parties:update`
Autenticación	`Authorization: Bearer `
Cuerpo de la petición	Objeto JSON con los datos del tercero

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

Encabezado	¿Obligatorio?	Valor
`Authorization`	Sí	`Bearer `, con el token obtenido en el servicio Login.
`Content-Type`	Sí	`application/json`: la petición lleva cuerpo JSON.

Si aún no tienes un token, consulta la página [*Login*](https://docs.nuby.ai/books/api-nuby-v2/page/login) del libro **API nuby V2**. Allí se explica cómo identificarte y cómo se construye el encabezado `Authorization`.

- `documento` es obligatorio siempre: es la llave con la que nuby identifica el tercero. - El `documento` solo admite **letras y números**: sin puntos, guiones ni espacios (`900.123.456` se rechaza). - Si el tercero **no existe**, el payload debe traer los obligatorios del alta; si falta uno, la respuesta es `422`. - El cliente OAuth del token debe tener el permiso `third-parties:update`.

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

Campo	Tipo	Requerido	Descripción
`referencia_externa`	texto	Sí	Identificador único de tu operación: es la llave de idempotencia. No puede venir vacía.
`documento`	texto	Sí	Documento o NIT del tercero. Es la llave de identidad y no se modifica por este endpoint. Solo letras y números.
`tipo_doc_id`	entero	Solo en el alta	Identificador del tipo de documento en la maestra de nuby. Debe ser mayor que cero y existir en el sistema.
`nombre1`	texto	Solo en el alta	Primer nombre, o la razón social si es una empresa. nuby lo guarda en mayúsculas.
`direccion1`	texto	Solo en el alta	Dirección principal del tercero.
`municipio_id`	entero	Solo en el alta	Identificador del municipio. Debe ser mayor que cero y existir en la maestra de municipios.
`tipo_tercero_id` o `tipos[]`	entero / arreglo o cadena	Solo en el alta (al menos uno)	Rol o roles del tercero. Se fusionan, se eliminan duplicados y se descartan valores no numéricos o `<= 0`. Si no se envían en la edición, se conservan los tipos actuales y, si no queda ninguno, la respuesta es `422`.
`persona`	entero	No	`1` persona natural (no admite NIT/NOP); `2` persona jurídica (exige NIT/NOP). Si se omite, la coherencia documento↔persona no se valida.
`nombre2`	texto	No	Segundo nombre. Se almacena en mayúsculas. Si no se envía, se conserva el valor actual.
`apellido1`	texto	No	Primer apellido. Se almacena en mayúsculas. Si no se envía, se conserva el valor actual.
`apellido2`	texto	No	Segundo apellido. Se almacena en mayúsculas. Si no se envía, se conserva el valor actual.
`sexo`	texto	No	Si no se envía, se conserva el valor actual.
`fecha_nacimiento`	fecha	No	Si no se envía, se conserva el valor actual.
`dv`	texto	No	Dígito de verificación del documento. Se acepta si viene y se conserva si no.
`tratamiento_id`	entero	No	Identificador de la maestra de tratamiento. Se valida contra el catálogo.
`direccion2`	texto	No	Dirección secundaria. Si no se envía, se conserva el valor actual.
`telefono1`, `telefono2`	texto	No	Teléfonos del tercero. Si no se envían, se conservan.
`fax`	texto	No	Si no se envía, se conserva el valor actual.
`email`	texto	No	Correo principal. El servicio no valida su formato.
`email_cumpleanos`	texto	No	Correo alterno. Si no se envía, se conserva el valor actual.
`codigo_postal`	texto	No	Si no se envía, se conserva el valor actual.
`tipo_persona_id`	entero	No	Identificador de la maestra de tipo de persona. Se valida contra el catálogo.
`regimen_id`	entero	No	Régimen tributario. Se valida contra el catálogo.
`resp_fiscal_id`	entero	No	Responsabilidad fiscal. Se valida contra el catálogo.
`autoretenedor`	indicador	No	Marca de autorretenedor. Si no se envía, se conserva el valor actual.
`autore_res`	indicador	No	Si no se envía, se conserva el valor actual.
`gran_contribuyente`	indicador	No	Marca de gran contribuyente. Si no se envía, se conserva el valor actual.
`gran_contr_res`	indicador	No	Si no se envía, se conserva el valor actual.
`aplica_documento_soporte`	indicador	No	Marca de documento soporte. Si no se envía, se conserva el valor actual.
`banco_id`	entero	No	Banco del tercero. Se valida contra el catálogo.
`intTipoCuentaB`	entero	No	Tipo de cuenta bancaria. Si no se envía, se conserva el valor actual.
`no_cuenta`	texto	No	Número de cuenta bancaria. Si no se envía, se conserva el valor actual.
`representante`	texto	No	Si no se envía, se conserva el valor actual.
`representante_legal`	texto	No	Si no se envía, se conserva el valor actual.
`certificado`	texto / indicador	No	Si no se envía, se conserva el valor actual.
`CY_*` (campos del cónyuge)	según el campo	No	Sin ningún `CY_*` se conserva `data_conyuge`; si envías algunos, solo esos cambian.
`data_conyuge`	objeto JSON	No	Datos del cónyuge. Si no llega ningún `CY_*`, se conserva completo.
`data_propiedades`	objeto JSON	No	Si no se envía, se conserva el JSON anterior.
`por_retencion`	objeto JSON	No	Si no se envía, se conserva el JSON anterior.
`nombre_aux`	texto	No	Se calcula en el alta si falta y se conserva en la edición.

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

- Sin `tipo_tercero_id`/`tipos[]`: se conservan los tipos existentes. - Sin `CY_*`: se conserva el cónyuge; si envías algunos, solo esos cambian. - Sin un campo o JSON: se conserva el valor anterior. - `nombre_aux` se calcula en el alta si falta y se conserva en la edición.

Campo	Tipo	Descripción
`success`	booleano	`true` cuando la operación se completó.
`status`	entero	Replica el código HTTP de la respuesta: `200` si actualizó, `201` si creó.
`message`	texto	Mensaje legible del resultado.
`body`	objeto	Identificador del tercero e indicadores de la operación. En un error, este campo no existe.

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

Campo	Tipo	Descripción
`tercero_id`	entero	Identificador interno del tercero en nuby.
`documento`	texto	Documento con el que se resolvió el tercero: el mismo que enviaste.
`created`	booleano	`true` si el tercero se creó en esta llamada.
`updated`	booleano	`true` si el tercero existía y se aplicaron los campos enviados.
`idempotent_replay`	booleano	`true` cuando la respuesta viene de un reintento con la misma `referencia_externa`.

Situación	Qué responde nuby
Reintento con el mismo payload	La respuesta original con `idempotent_replay: true`.
Otra solicitud con la misma referencia en curso	`409 IDEMPOTENCY_IN_PROGRESS`.
La misma referencia con un payload distinto	`409 IDEMPOTENCY_PAYLOAD_MISMATCH`.
La solicitud anterior terminó en `422`	La referencia se libera: puedes reintentar con el mismo valor y el payload corregido.
La solicitud anterior terminó en `500`	Se permite reintentar, incluso con datos corregidos.
No se pudo registrar la solicitud de idempotencia	`500 IDEMPOTENCY_STORAGE_ERROR`.

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

Situación	HTTP	Detalle
No se envió el encabezado `Authorization`	`401`	`JWT Token required.`
El encabezado no tiene el formato `Bearer {token}`	`400`	`JWT Token not send.`
El token no fue encontrado en el sistema	`401`	`JWT Token not found.`
El token expiró	`401`	`JWT Token expired.`

HTTP	`error_code`	Cuándo
`400`	`VALIDATION_ERROR`	El cuerpo no es un objeto JSON.
`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`	El consumidor no tiene `third-parties:update`.
`409`	`TERCERO_IDENTIDAD_CONFLICTIVA`	El documento existe con otro `tipo_doc_id`.
`409`	`IDEMPOTENCY_PAYLOAD_MISMATCH`	La misma referencia se usó con otro payload.
`409`	`IDEMPOTENCY_IN_PROGRESS`	Otra solicitud con la misma referencia está en proceso.
`422`	`VALIDATION_ERROR`	Falta un obligatorio o un valor no cumple las reglas del modelo.
`500`	`INTERNAL_ERROR`	Fallo técnico; el detalle queda en el log `API_INTEGRACION`.

- `El campo "{Etiqueta}" es obligatorio.` - `El campo "{Etiqueta}" debe ser un identificador numérico mayor que cero.` (para `tipo_doc_id` y `municipio_id`) - `Debe enviar al menos un tipo de tercero en "Tipo de Tercero" o en tipos[].` - `El valor ingresado en el campo "{Etiqueta}" no es válido para el sistema.` (maestras) - `Una Persona Natural no puede registrarse con un tipo de documento de tipo NIT.` - `Una Persona Jurídica debe registrarse de forma obligatoria con un documento de tipo NIT.`

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

cURL

```bash 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

```php '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"; } ```

Python

```python 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}") ```

JavaScript (Fetch API)

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