*MCP › Referencia › CRM › Contactos*

# Actualizar un contacto

> Actualiza parcialmente un contacto (envía solo los campos que cambian).

> **Requiere confirmación humana:** Pon esta herramienta en la lista de «preguntar antes de ejecutar» de tu cliente. Las anotaciones son pistas que declara el servidor, no garantías: no decidas la aprobación solo por `destructiveHint`.

Las listas de emails, teléfonos y direcciones sustituyen por completo la lista existente. Devuelve el contacto actualizado en detalle.

HERRAMIENTA `filmo_contacts_update` · `contacts:write` · 120/min · Anotación del servidor: Destructiva · Anotación del servidor: Idempotente · Requiere confirmación humana

## Argumentos

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `contactId` | string | Sí | Identificador del contacto. |
| `name` | string | No | Nombre del contacto (persona o empresa). |
| `contactType` | string | No | Tipo de contacto: person (particular) o company (negocio). `person`, `company` |
| `role` | string | No | Rol del contacto: client, provider, lead, debtor, creditor, student, teacher o unspecified. `client`, `provider`, `lead`, `debtor`, `creditor`, `student`, `teacher`, `unspecified` |
| `status` | string | No | Estado del contacto: active (operativo), inactive (desactivado) o archived (cerrado, conservado como histórico). `active`, `inactive`, `archived` |
| `nif` | string | No | NIF/CIF o número de identificación fiscal; null lo borra ("" también se normaliza a null). |
| `commercialName` | string | No | Nombre comercial; null lo borra. |
| `position` | string | No | Cargo o puesto; null lo borra. |
| `emails` | object[] | No | Lista de direcciones de correo electrónico que REEMPLAZA por completo la lista existente (máx. 20). Los ids internos los genera el servidor. |
| `emails.email` | string<email> | Sí | Dirección de email; se valida el formato. |
| `emails.label` | string | No | Etiqueta descriptiva del email (p. ej. "Personal", "Facturación"). |
| `emails.isPrimary` | boolean | No | Marca este correo electrónico como el principal del contacto. |
| `phoneNumbers` | object[] | No | Lista de teléfonos que REEMPLAZA por completo la lista existente (máx. 20). Los ids internos los genera el servidor. |
| `phoneNumbers.number` | string | Sí | Número de teléfono. |
| `phoneNumbers.label` | string | No | Etiqueta descriptiva del teléfono (p. ej. "Móvil", "Oficina"). |
| `phoneNumbers.countryCode` | string | No | Prefijo telefónico internacional del país (p. ej. "+34"). |
| `phoneNumbers.isPrimary` | boolean | No | Marca este teléfono como el principal del contacto. |
| `websites` | object[] | No | Lista de sitios web que REEMPLAZA por completo la lista existente (máx. 20). Los ids internos los genera el servidor. |
| `websites.url` | string<uri> | Sí | URL del sitio web; se valida el formato. |
| `websites.label` | string | No | Etiqueta descriptiva del sitio web (p. ej. "Web corporativa", "LinkedIn"). |
| `addresses` | object[] | No | Lista de direcciones que REEMPLAZA por completo la lista existente (máx. 20). Envía el id de cada dirección existente que quieras conservar; las direcciones sin id se crean con uno nuevo. Un id que no es una dirección de este contacto responde 400. Omitir una dirección que un pedido usa como dirección de facturación o de envío responde 409 `address_in_use` y no se cambia nada. |
| `addresses.id` | string | No | Identificador de una dirección existente para conservarla; omítelo para añadir una nueva. |
| `addresses.label` | string | No | Etiqueta descriptiva de la dirección (p. ej. "Facturación", "Envío"). |
| `addresses.addressLine1` | string | Sí | Primera línea de la dirección (calle y número). Obligatorio. |
| `addresses.addressLine2` | string | No | Segunda línea de la dirección (piso, puerta, etc.). |
| `addresses.city` | string | No | Ciudad de la dirección. |
| `addresses.province` | string | No | Provincia o región de la dirección. |
| `addresses.postcode` | string | No | Código postal de la dirección. |
| `addresses.country` | string | No | País de la dirección (código o nombre corto). |
| `addresses.isMain` | boolean | No | Marca esta dirección como la principal del contacto. |
| `folder` | string | No | Carpeta o agrupación organizativa; null la borra. |
| `contactNumber` | string | No | Número de contacto (referencia interna); null lo borra. |
| `discountPercentage` | number | No | Porcentaje de descuento general del contacto (0-100); null lo borra. |
| `subscribedToMarketing` | boolean | No | Si el contacto está suscrito a comunicaciones de marketing. |
| `idempotencyKey` | string | No | Clave de idempotencia elegida por el cliente (se recomienda un UUID). Repetir la misma clave con los mismos argumentos en 24 h devuelve la respuesta almacenada sin volver a ejecutar; con argumentos distintos responde 422. Es la forma segura de reintentar tras un fallo de red. |
| `ifMatch` | string | No | Bloqueo optimista: el meta.etag que obtuviste de la lectura de detalle de este recurso (o "*"). Si el recurso ha cambiado desde entonces, la llamada falla con 412 precondition_failed antes de escribir nada; léelo de nuevo y reintenta. Omítelo para escribir sin condiciones. |

## Resultado

En un éxito el resultado lleva `structuredContent` con `data` y `meta`. Estos son los atributos de `data`.

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `id` | string | Identificador único del contacto. |
| `name` | string | Nombre del contacto (persona o empresa). |
| `contactType` | string | Tipo de contacto: person (particular) o company (negocio). `person`, `company` |
| `role` | string | Rol del contacto: client, provider, lead, debtor, creditor, student, teacher o unspecified. `client`, `provider`, `lead`, `debtor`, `creditor`, `student`, `teacher`, `unspecified` |
| `status` | string | Estado del contacto: active (operativo), inactive (desactivado) o archived (cerrado, conservado como histórico). `active`, `inactive`, `archived` |
| `nif` | string | NIF/CIF o número de identificación fiscal; null si no se ha registrado. |
| `commercialName` | string | Nombre comercial; null si coincide con el nombre o no consta. |
| `position` | string | Cargo o puesto de la persona de contacto; null si no está registrado. |
| `contactNumber` | string | Número de contacto asignado por la cuenta (referencia interna); null si no consta. |
| `emails` | object[] | Lista de direcciones de correo electrónico del contacto. |
| `emails.id` | string | Identificador interno del correo electrónico dentro del contacto. |
| `emails.label` | string | Etiqueta descriptiva del email; null si no tiene. |
| `emails.email` | string | Dirección de email. |
| `emails.isPrimary` | boolean | Si este es el email principal del contacto. |
| `billingEmail` | string | Email de facturación dedicado; null significa que se usa el email principal. |
| `phoneNumbers` | object[] | Lista de teléfonos del contacto. |
| `phoneNumbers.id` | string | Identificador interno del teléfono dentro del contacto. |
| `phoneNumbers.label` | string | Etiqueta descriptiva del teléfono; null si no tiene. |
| `phoneNumbers.number` | string | Número de teléfono. |
| `phoneNumbers.countryCode` | string | Prefijo telefónico internacional del país (p. ej. "+34"); null si no consta. |
| `phoneNumbers.isPrimary` | boolean | Si este es el teléfono principal del contacto. |
| `websites` | object[] | Lista de sitios web del contacto. |
| `websites.id` | string | Identificador interno del sitio web dentro del contacto. |
| `websites.label` | string | Etiqueta descriptiva del sitio web; null si no tiene. |
| `websites.url` | string | URL del sitio web. |
| `addresses` | object[] | Lista de direcciones del contacto. |
| `addresses.id` | string | Identificador interno de la dirección dentro del contacto. |
| `addresses.label` | string | Etiqueta descriptiva de la dirección; null si no tiene. |
| `addresses.addressLine1` | string | Primera línea de la dirección; null si no consta. |
| `addresses.addressLine2` | string | Segunda línea de la dirección; null si no consta. |
| `addresses.city` | string | Ciudad; null si no consta. |
| `addresses.province` | string | Provincia o región; null si no se ha registrado. |
| `addresses.postcode` | string | Código postal; null si no se ha registrado. |
| `addresses.country` | string | País; null si no consta. |
| `addresses.isMain` | boolean | Si esta es la dirección principal del contacto. |
| `folder` | string | Carpeta o agrupación organizativa; null si el contacto no está clasificado. |
| `discountPercentage` | number | Porcentaje de descuento general del contacto (0-100); null si no hay descuento configurado. |
| `preferredLanguage` | string | Idioma preferido del contacto; null si no se ha registrado. |
| `currency` | string | Moneda por defecto del contacto como código ISO 4217; null si no consta. |
| `paymentMethod` | object | Método de pago preferido del contacto; null si no está configurado. |
| `paymentMethod.type` | string | Tipo de método de pago: bank_transfer, card, cash, sepa_direct_debit u other. `bank_transfer`, `card`, `cash`, `other`, `sepa_direct_debit` |
| `paymentMethod.customValue` | string | Detalle en texto libre cuando el tipo es "other" (por ejemplo, un método registrado antes de configurarse); null en caso contrario. |
| `paymentDays` | integer[] | Días del mes en que el contacto hace pagos; null si no está configurado. |
| `expirationDays` | integer | Días de vencimiento por defecto de las facturas del contacto; null si no está configurado. |
| `subscribedToMarketing` | boolean | Si el contacto está suscrito a comunicaciones de marketing. |
| `isAppUser` | boolean | Si el contacto tiene acceso a la app. |
| `customFields` | object<string, any> | Valores de los campos personalizados por identificador de campo personalizado; las definiciones están en `/api/v1/custom-fields`. |
| `createdAt` | string<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `updatedAt` | string<date-time> | Fecha de la última actualización en ISO 8601 con desplazamiento. |
| `relatedContacts` | object[] | Contactos relacionados con este contacto (p. ej. las personas de una empresa). |
| `relatedContacts.id` | string | Identificador único del contacto relacionado. |
| `relatedContacts.name` | string | Nombre del contacto relacionado. |
| `relatedContacts.commercialName` | string | Nombre comercial del contacto relacionado; null si no consta. |
| `relatedContacts.contactType` | string | Tipo del contacto relacionado: person o company. `person`, `company` |
| `relatedContacts.role` | string | Rol del contacto relacionado. `client`, `provider`, `lead`, `debtor`, `creditor`, `student`, `teacher`, `unspecified` |
| `relatedContacts.status` | string | Estado del contacto relacionado: active, inactive o archived. `active`, `inactive`, `archived` |
| `relatedContacts.relationRole` | string | Rol de la relación entre los dos contactos (p. ej. "empleado de"); null si no consta. |

*Llamada · filmo_contacts_update*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_contacts_update",
    "arguments": {
      "contactId": "cont_8f2a1c"
    }
  }
}
```

*Resultado (generado desde el esquema)*

```json
{
  "structuredContent": {
    "data": {
      "id": "id_8f2a1c",
      "name": "Example",
      "contactType": "person",
      "role": "client",
      "status": "active",
      "nif": "00000000T",
      "commercialName": "Example",
      "position": "<position>",
      "contactNumber": "<contactNumber>",
      "emails": [
        {
          "id": "id_8f2a1c",
          "label": "Example",
          "email": "ana@example.com",
          "isPrimary": true
        }
      ],
      "billingEmail": "ana@example.com",
      "phoneNumbers": [
        {
          "id": "id_8f2a1c",
          "label": "Example",
          "number": "<number>",
          "countryCode": "ES",
          "isPrimary": true
        }
      ],
      "websites": [
        {
          "id": "id_8f2a1c",
          "label": "Example",
          "url": "https://example.com"
        }
      ],
      "addresses": [
        {
          "id": "id_8f2a1c",
          "label": "Example",
          "addressLine1": "<addressLine1>",
          "addressLine2": "<addressLine2>",
          "city": "<city>",
          "province": "<province>",
          "postcode": "<postcode>",
          "country": "ES",
          "isMain": true
        }
      ],
      "folder": "<folder>",
      "discountPercentage": 1,
      "preferredLanguage": "es-ES",
      "currency": "EUR",
      "paymentMethod": {
        "type": "bank_transfer",
        "customValue": "<customValue>"
      },
      "paymentDays": [
        1
      ],
      "expirationDays": 1,
      "subscribedToMarketing": true,
      "isAppUser": true,
      "customFields": {
        "key": "<key>"
      },
      "createdAt": "2026-09-01T08:00:00Z",
      "updatedAt": "2026-09-01T08:00:00Z",
      "relatedContacts": [
        {
          "id": "id_8f2a1c",
          "name": "Example",
          "commercialName": "Example",
          "contactType": "person",
          "role": "client",
          "status": "active",
          "relationRole": "<relationRole>"
        }
      ]
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## La misma operación por REST

Esta herramienta ejecuta [`PATCH /api/v1/contacts/{contactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/update-a-contact).

---

URL canónica: https://docs.filmo.io/es/mcp/tools/contacts/filmo-contacts-update  
Última actualización: 2026-10-25