# Editar (/docs/developers/api-reference/custom-fields/employees/edit) ## Descripcion general [#descripcion-general] Este endpoint permite actualizar parcialmente una definición de campo personalizado. Todos los campos del cuerpo son **opcionales**: si omites una clave, ese campo no se toca; si la envías como `null`, ese campo se limpia (cuando aplica). El identificador en la URL es el **`key` actual** de la definición. Una solicitud exitosa devuelve `200` con la forma completa de la definición actualizada. Las definiciones eliminadas se tratan como no encontradas (`404`). **`key` es editable, pero con cuidado.** El `key` es el identificador público referenciado por integraciones externas. Si lo cambias, el segmento de URL para `PATCH`/`DELETE` cambia con él — las llamadas siguientes deben usar el nuevo `key`. Las integraciones que hardcodeen el `key` original dejarán de funcionar. Además, el nuevo `key` no puede colisionar con un campo nativo del empleado (`first_name`, `rfc`, `notes`, `department_code`, etc.); si lo hace, la solicitud falla con `400`. **`type` es editable, pero generalmente no debería cambiar.** Los valores existentes en `employee_custom_field_value` viven en la columna tipada que corresponde al `type` **original**. Cambiar `type` **no migra** los valores: se quedan en su columna anterior y pueden no devolverse cuando los lectores esperan el tipo nuevo. Solo cámbialo si no hay valores aún (o si los limpiaste manualmente). ## Endpoint [#endpoint] `PATCH https://app.integranom.com/api/v1/employee-custom-fields/{key}` **Path param:** `key` — el `key` actual de la definición. Usa solo minúsculas, números y guiones bajos. Debe iniciar con letra. Máx. 60. ## Renombrar el campo [#renombrar-el-campo] *** Envía solo los campos que quieras cambiar. El resto de la definición queda intacto. ```json { "name": "Talla de uniforme" } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employee-custom-fields/shirt_size" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Talla de uniforme" }' ``` **Respuesta** ```json { "key": "shirt_size", "name": "Talla de uniforme", "type": "select", "description": "Talla solicitada por el empleado.", "select_options": ["XS", "S", "M", "L", "XL"], "is_required_for_create": false, "is_required_for_payroll": false, "is_active": true, "sort_order": 0, "created_at": "2026-05-25T10:00:00.000Z", "updated_at": "2026-05-25T11:15:32.000Z" } ``` ## Agregar opciones a un select [#agregar-opciones-a-un-select] *** Mientras `type` permanece como `select`, puedes reescribir el arreglo completo de `select_options`. El handler valida contra el **estado efectivo** (lo que enviaste + lo que ya estaba almacenado). ```json { "select_options": ["XS", "S", "M", "L", "XL", "XXL"] } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employee-custom-fields/shirt_size" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "select_options": ["XS", "S", "M", "L", "XL", "XXL"] }' ``` **Respuesta** ```json { "key": "shirt_size", "name": "Talla de uniforme", "type": "select", "description": "Talla solicitada por el empleado.", "select_options": ["XS", "S", "M", "L", "XL", "XXL"], "is_required_for_create": false, "is_required_for_payroll": false, "is_active": true, "sort_order": 0, "created_at": "2026-05-25T10:00:00.000Z", "updated_at": "2026-05-25T11:18:09.000Z" } ``` ## Cambiar un text a select [#cambiar-un-text-a-select] *** Para convertir un campo de `text` (u otro tipo) a `select`, envía el nuevo `type` junto con `select_options`. Si la nueva `type` es `select` y no hay opciones (ni en el cuerpo ni almacenadas), el request se rechaza con `400`. ```json { "type": "select", "select_options": ["A", "B"] } ``` Si en cambio quitas el tipo `select` (por ejemplo `{ "type": "text" }`), las `select_options` existentes se **auto-limpian** (se ponen en `null`) sin importar lo que envíes. **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employee-custom-fields/notes" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "select", "select_options": ["A", "B"] }' ``` **Respuesta** ```json { "key": "notes", "name": "Notas", "type": "select", "description": null, "select_options": ["A", "B"], "is_required_for_create": false, "is_required_for_payroll": false, "is_active": true, "sort_order": 0, "created_at": "2026-05-25T10:00:00.000Z", "updated_at": "2026-05-25T11:22:44.000Z" } ``` ## Renombrar el key [#renombrar-el-key] *** Si renombras `key`, la URL para llamadas siguientes cambia: a partir de aquí debes usar `/api/v1/employee-custom-fields/uniform_size` (no `/shirt_size`). Cualquier integración externa que hardcodee el `key` original debe actualizarse. ```json { "key": "uniform_size" } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employee-custom-fields/shirt_size" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "uniform_size" }' ``` **Respuesta** ```json { "key": "uniform_size", "name": "Talla de uniforme", "type": "select", "description": "Talla solicitada por el empleado.", "select_options": ["XS", "S", "M", "L", "XL", "XXL"], "is_required_for_create": false, "is_required_for_payroll": false, "is_active": true, "sort_order": 0, "created_at": "2026-05-25T10:00:00.000Z", "updated_at": "2026-05-25T11:30:00.000Z" } ``` ## Campos del cuerpo [#campos-del-cuerpo] | Campo | Tipo | Notas | | ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | No vacío tras recortar. | | `key` | string | Editable, pero las integraciones externas pueden hardcodear el valor original. Si lo cambias, el segmento de URL cambia — las llamadas siguientes deben usar el nuevo `key`. | | `type` | `text` \| `number` \| `date` \| `boolean` \| `select` | Editable, pero los valores existentes en `employee_custom_field_value` viven en la columna tipada del `type` original. Cambiar `type` **no migra** los valores. | | `description` | string \| null | `null` o `""` limpian la descripción. | | `select_options` | string\[] | Requerido cuando el `type` efectivo es `select` (el handler verifica el estado fusionado: lo enviado + lo actual). Si cambias `type` a algo distinto de `select`, las opciones se auto-limpian. | | `is_required_for_create` | boolean | | | `is_required_for_payroll` | boolean | | | `is_active` | boolean | Flag activo controlado por el usuario. Independiente del borrado. | | `sort_order` | integer ≥ 0 | | ### Interacción `type` ↔ `select_options` [#interacción-type--select_options] * Si el `type` efectivo nuevo es `select` y no hay opciones (ni en el cuerpo ni almacenadas), la solicitud se rechaza con `400`. * Si cambias `type` saliendo de `select`, las `select_options` existentes se **auto-limpian** (se ponen en `null`) sin importar lo que envíes. * Si `type` no cambia y el caller toca `select_options`, solo se reescriben las opciones. ## Forma de la respuesta [#forma-de-la-respuesta] `200 OK` — misma forma que la respuesta de [crear](/docs/developers/api-reference/custom-fields/employees/create) en modo single. ## Errores [#errores] | Status | Causa | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Formato inválido del `key` en la URL; falla de validación del cuerpo; el `type` efectivo nuevo es `select` sin `select_options`; el nuevo `key` colisiona con un campo nativo del empleado. | | `404` | La definición no existe (o fue eliminada) en esta organización. | | `409` | El nuevo `key` ya está en uso por otra definición viva de la organización. |