Actualizaciones parciales

Todos los endpoints PUT de la API siguen un patrón de actualización parcial — enviá solo los campos que querés cambiar, no el recurso completo.

A diferencia de la semántica PUT estándar

En REST tradicional (RFC 7231), PUT reemplaza el recurso completo. El PUT de GeoTareas se comporta como un merge/patch — los campos omitidos conservan su valor actual. Este diseño evita la pérdida accidental de datos cuando solo necesitás cambiar uno o dos campos.

Cómo funciona

1. Enviá solo los campos que querés cambiar — los campos omitidos conservan su valor actual.
2. Enviá null para vaciar un campo — esto establece el valor en NULL en la base de datos.
3. El ID del recurso va en la URL, nunca en el cuerpo — incluir id en el cuerpo devuelve un VALIDATION_ERROR.
4. Las mismas validaciones que POST — las restricciones de campo (tipo, formato, requerido) aplican por igual a las actualizaciones. Un email inválido se rechaza tanto al crear como al actualizar.
5. Los campos de solo lectura se ignoran — si enviás un campo que no es editable (ej. createdAt, id), el servidor lo ignora silenciosamente. No se genera ningún error, pero el campo no se modifica.

Ejemplos

Actualizar un solo campo

cURL

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com"}' \
  "https://$TENANT/apidev/v1/clients/104820579301"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients/104820579301`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': API_KEY,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email: 'new@example.com' }),
  }
);
const result = await res.json();
console.log(result.data.updated_fields); // ["email"]

Python

response = requests.put(
    f"https://{TENANT}/apidev/v1/clients/104820579301",
    headers={**headers, "Content-Type": "application/json"},
    json={"email": "new@example.com"},
)
print(response.json()["data"]["updated_fields"])  # ["email"]

Solo cambia email. Nombre, teléfono, dirección — todo lo demás queda como está.

Respuesta:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["email"]
  }
}

Actualizar varios campos a la vez

PUT /apidev/v1/clients/104820579301
Content-Type: application/json

{
  "email": "new@example.com",
  "phone": "+5491155551234",
  "address": "Av. Corrientes 1234, CABA"
}

Respuesta:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["email", "phone", "address"]
  }
}

Vaciar un campo con null

Para eliminar explícitamente un valor, enviá null:

PUT /apidev/v1/clients/104820579301
Content-Type: application/json

{
  "phone": null
}

El campo phone se establece en NULL en la base de datos. Todos los demás campos quedan sin cambios.

Respuesta:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["phone"]
  }
}

Diferencia entre omitir y enviar null

• Omitir un campo: el campo conserva su valor actual (sin cambio)
• Enviar null: el campo se vacía explícitamente (se establece en NULL)

No son lo mismo. {} no cambia nada; {"phone": null} borra el número de teléfono.

Formato de respuesta

Todos los endpoints PUT devuelven una respuesta consistente que indica qué campos fueron efectivamente modificados:

Campo	Tipo	Descripción
success	boolean	true si la actualización se completó sin errores
data.id	string	El ID del recurso actualizado
data.updated_fields	array	Lista de nombres de campos que fueron modificados

tip

Usá updated_fields para confirmar que tu actualización se aplicó. Si un campo que enviaste falta en esta lista, el nuevo valor era idéntico al existente — no hizo falta ningún cambio.

Errores comunes

Error	Qué sucede	Solución
Enviar id en el cuerpo	VALIDATION_ERROR	Poné el ID solo en el path de la URL
Enviar un formato de email inválido	VALIDATION_ERROR — las mismas validaciones que POST	Revisá las restricciones de campo en la documentación del endpoint
Omitir un campo para "vaciarlo"	No pasa nada — el campo conserva su valor actual	Enviá null explícitamente para vaciarlo
Enviar el recurso completo de un GET	Funciona, pero arriesga sobrescribir cambios concurrentes	Enviá solo los campos que pretendés cambiar