Cambios de las integraciones

Este es el registro de cambios de todo lo que usa tu integración: la API externa, los SDK de JavaScript y Python, las herramientas MCP, OAuth y el widget. Los cambios que te obligan a tocar tu código o a conceder un permiso nuevo llevan la marca CAMBIO QUE ROMPE o Cambio incompatible. Las versiones vigentes están al final de la página.

Si vienes de una versión anterior, estos son los cambios que te obligan a actuar:

Cambios que exigen tocar tu integración

1. 27 may

   Firma de los avisos

   Se firma timestamp.rawBody: los receptores que firmaban solo el cuerpo rechazan las entregas.

2. 2 sep

   Borrar archivos por MCP

   dev:write y crm:write dejan de borrar archivos; hace falta un ámbito propio.

3. 3 sep

   Portal del cliente por MCP

   portal_access exige crm:portal:view y crm:portal:manage.

4. 5 sep

   SDK 3.0.0 y permisos de la API

   identify exige crm:users:write y desaparece el periodo de gracia de los permisos.

5. 7 sep

   SDK 4.0.0 y cobro con tarjeta

   Se retira el correo al proveedor; cobrar exige Pagos con tarjeta (Stripe) en el plan.

6. 5 oct

   Enlaces a la documentación

   create_share_token exige el ámbito dev:docs:share.

2026-10-05

Los enlaces a la documentación tienen scope y permiso propios

Cambio incompatible para las integraciones que crean enlaces de documentación.

• documentation(operation: 'create_share_token') exige el scope dev:docs:share y el permiso DEV_DOCS_SHARE («Compartir documentación con enlace»). Antes bastaba con dev:docs:update y con poder ver la documentación.
• dev:docs:share se pide por su nombre: no viaja en dev:read, dev:write, dev:full ni admin:full. Añádelo a los scopes que pide tu aplicación. Los tokens emitidos antes no lo llevan y hay que volver a autorizarlos.
• REST: POST /api/dev-management/documentation/:id/share exige DEV_DOCS_VIEW y DEV_DOCS_SHARE.
• Los enlaces PRIVATE piden sesión: GET /api/share/:token responde 401 con errorCode: SHARE_LOGIN_REQUIRED si no hay sesión, y 404 si la sesión es de otra organización o no puede leer el documento. Los PUBLIC y TEMPORARY no cambian.
• Adjuntos de un enlace PRIVATE: GET /api/share/:token/file/:fileId?format=json devuelve { "url": "…" } en lugar de redirigir, para pedir la descarga con la sesión en la cabecera.

El usuario puede conceder menos scopes de los que pides

• La pantalla de consentimiento deja desactivar grupos de permisos antes de autorizar. El token lleva solo los scopes que quedan activados, y las renovaciones conservan ese conjunto reducido. Los de identidad (openid, profile, email) no se pueden desactivar.
• Lee el scope de la respuesta del token en vez de dar por hecho el conjunto pedido, y degrada con elegancia lo que dependa de un scope no concedido.
• Sin scope en la solicitud, la pantalla enseña el conjunto por defecto que se concede (los allowedScopes del registro o, sin ellos, los de identidad), y también se puede estrechar.
• Detalle en Pantalla de consentimiento.

2026-09-12

SDK JavaScript 4.1.0 y SDK Python 4.1.0, publicados en npm y PyPI

Superficie nueva, sin cambios incompatibles: actualizar desde la 4.0.1 no exige tocar nada.

• El calendario laboral de la empresa, por MCP. sdk.mcp.attendance.holidays (sobre POST /api/mcp/rrhh) ofrece getScope(), setScope(), import(year) y list() en JavaScript, y get_scope(), set_scope(), import_year(year) y list() en Python, en las variantes asíncrona y síncrona.
• El ámbito decide qué festivos cuentan. Sin comunidad elegida solo cuentan los nacionales y los propios de la empresa, así que lo primero es consultar el ámbito y solo después cargar el año. Cambiar el ámbito no borra festivos.
• Los municipales no se cargan: los publica cada ayuntamiento y la respuesta lo avisa en notice.
• Permisos: hr:attendance:view para consultar y listar; hr:attendance:manage para fijar el ámbito y cargar el año.

2026-09-09

SDK JavaScript 4.0.1 y SDK Python 4.0.1, publicados en npm y PyPI

Versión solo de documentación: no cambia ni el comportamiento ni la firma de ningún método, así que actualizar desde la 4.0.0 no exige tocar nada.

• AnnouncementsService documenta sus reglas: qué ámbitos exige (dev:announcements:view, :manage y :publish) y que antes de preparar o publicar un anuncio hay que consultar instructions().
• El número de versión del paquete de Python queda alineado: arrastraba una cifra antigua en su package.json auxiliar.

Quien venga de la 3.x debe leer antes los cambios incompatibles de la 4.0.0: esa versión retiró tres métodos sin sustituto.

2026-09-07

Pedir más plan y reservar una llamada, también por MCP

La herramienta transversal org_plan pasa de dos operaciones a doce. Las diez nuevas cubren pedir que se amplíe el plan (request_upgrade, list_my_requests, withdraw_upgrade_request, list_requests, dismiss_request) y reservar quince minutos con el equipo de UTILIA (list_sales_call_slots, book_sales_call, get_my_sales_call, cancel_sales_call, reschedule_sales_call). Las tres escrituras de la reserva exigen confirm: true.

• Dos ámbitos transversales nuevos. org:plan:request lo expanden los conjuntos :write y :full de los siete dominios, nunca los :read; org:plan:manage_requests, solo los :full. La herramienta deja de anunciarse como de solo lectura, porque seis de sus doce operaciones escriben.
• Categoría de avisos nueva en la herramienta notifications: planRequests («Peticiones de plan»).
• No entra en los SDK ni en la API externa: una clave de API no es una persona, no tiene administrador a quien pedirle nada y no puede sentarse en una videollamada.

El detalle está en MCP: pedir plan y reservar llamada.

Saber si la organización puede cobrar antes de intentarlo

Una aplicación externa ya no tiene que enterarse por un error de que la organización no puede cobrar con tarjeta.

• Endpoint nuevo GET /external/v1/payment-methods/readiness. Devuelve platformAvailable, organizationCanCharge, reason y livemode. Los seis motivos son estables: PLATFORM_DISABLED, NO_ACCOUNT, ONBOARDING_INCOMPLETE, CHARGES_DISABLED, ACCOUNT_DEAUTHORIZED y READY. Exige los aplicativos Finanzas y Stripe y el permiso billing:payment-methods:read; no estrena ningún permiso.
• En los dos SDK: sdk.paymentMethods.getReadiness() en JavaScript y payment_methods.get_readiness() en Python, en las variantes asíncrona y síncrona. Van en la 4.0.0 de los dos SDK, junto con la retirada del correo al proveedor que se describe abajo.
• Es el mismo criterio que usa el panel. Antes convivían tres formas distintas de decidir si se podía cobrar y se contradecían entre ellas. Ahora hay una, y la sirven este endpoint y las pantallas del panel.

El cobro con tarjeta se gatea por su propio aplicativo

Cobrar una factura, confirmar el cobro, devolverlo por la pasarela y gestionar las tarjetas guardadas exigen ahora el aplicativo «Pagos con tarjeta (Stripe)» en el plan de la organización, además de Finanzas. Sin él, la respuesta es 403 con errorCode: 'MODULE_NOT_ENABLED'.

Alcanza también a las herramientas MCP equivalentes: la herramienta payment_methods entera, crm_invoices_workflow en charge, charge_confirm, refund_create, payment_intent_cancel y payment_intents_list, y crm_clients_info:stripe_readiness.

No lo exigen, y es deliberado: el reembolso registrado a mano (refund_manual), los listados que incluyen reembolsos manuales, y marcar una factura como cobrada o parcialmente cobrada. Registrar una devolución en efectivo no necesita pasarela y exigirla sería falso.

MCP: el copiloto puede consultar el estado de los pagos con tarjeta

Operación nueva finance_settings:get_stripe, solo lectura. Devuelve la disponibilidad de la pasarela, el estado de la cuenta conectada y los requisitos pendientes ya traducidos al castellano. Ámbito finance:settings:view, el mismo que el resto de lecturas de ajustes de Finanzas; permiso del usuario: configurar o ver los pagos con tarjeta; aplicativos Finanzas y Stripe.

No hay ni habrá alta ni desconexión por MCP: el alta exige que una persona teclee en un formulario alojado por Stripe con verificación de identidad, y la desconexión es en la práctica irreversible.

RETIRADO: PATCH /finance/stripe/account/publishable-key devuelve 410

Nunca tuvo efecto. La clave publicable que usa el producto es la de la plataforma UTILIA OS, no una de la cuenta conectada, así que no había nada que guardar. No lo llamaba ni el panel, ni los SDK, ni las herramientas MCP. Responde 410 Gone de forma permanente y no tiene sustituto.

SDK 4.0.0: el método de disposición de cobro y la retirada del correo al proveedor

Versión MAYOR en los dos SDK. Lo que obliga a subir de mayor no es el método nuevo, sino la retirada: los tres métodos que desaparecen se publicaron en la 2.28.0 y siguen vivos en la 3.1.0, que está en npm y en PyPI, así que quitarlos rompe a quien los use.

• Añade sdk.paymentMethods.getReadiness() (payment_methods.get_readiness() en Python, en las dos variantes), con los tipos ChargingReadiness y ChargingReadinessReason.
• Retira sin sustituto sdk.mcp.erp.suppliers.getEmailRecipients, sendEmail y replyEmail, y con ellos los tipos SupplierEmailRecipients, SupplierSendEmailInput y SupplierReplyEmailInput.

Cómo actualizar. Si solo dejabas constancia de un correo que enviabas tú, usa logInteraction con type: 'EMAIL', que no cambia. Si de verdad enviabas el correo a través de UTILIA OS, esa capacidad ya no existe en el producto. No hay ninguna otra ruptura en esta versión: la tabla completa está en Versiones y compatibilidad.

RUPTURA: se retira el correo al proveedor

El envío de correo desde la actividad del proveedor desaparece del producto, y con él su superficie de integración. No hay sustituto: para dejar constancia de un correo que se mandó por otra vía sigue estando log_interaction con type: 'EMAIL'.

• Se retiran tres rutas REST: GET /finance/suppliers/:supplierId/interactions/email-recipients, POST /finance/suppliers/:supplierId/interactions/send-email y POST /finance/suppliers/:supplierId/interactions/:interactionId/reply.
• Se retiran tres operaciones MCP de la herramienta suppliers: get_email_recipients, send_email y reply_email, junto con su parámetro emailMessage. El resto de la actividad (registrar, conversación, historial, adjuntos, lote y reuniones) no cambia.
• Se retiran de los dos SDK los métodos getEmailRecipients, sendEmail y replyEmail de sdk.mcp.erp.suppliers (get_email_recipients, send_email y reply_email en Python) y sus tipos de entrada y salida.
• Los ámbitos finance:suppliers:interactions:read y :manage siguen existiendo y conservan todo lo demás: solo dejan de conceder lo relativo al correo.

2026-09-05

SDK 3.0.0: la facturación y el cobro de una aplicación externa funcionan de verdad

Versión mayor en los dos SDK. La razón principal no es el volumen: es que cinco servicios que existían y devolvían 401 siempre pasan a funcionar contra otra ruta, y uno desaparece. La tabla de rupturas completa está en Versiones y compatibilidad del SDK.

• sdk.subscriptions funciona, sobre /external/v1/subscriptions. Hasta ahora atacaba una ruta de la API del panel. Firmas nuevas: clientId desaparece y userId es obligatorio. Se retiran remove (la baja es cancel) y stats.
• sdk.paymentAuthorizations es nuevo (sdk.payment_authorizations en Python), y ahora sí crea autorizaciones desde la aplicación, con su prueba legal. sdk.mandates queda como alias en desuso; listForClient se retira.
• sdk.invoices gana cinco acciones: send, charge, markPaid, getPublicLink y regeneratePublicLink.
• sdk.invoices.scheduledCharges funciona sobre la API externa. En Python se reubica bajo sdk.invoices con alias en la raíz, y se retira retrieve, cuya ruta no existía.
• sdk.invoices.refunds.create emite el reembolso. cancelPreview y cancel se retiran: deshacer un reembolso es del equipo.
• sdk.invoices.rectifications se retira con un error que dice qué usar. sdk.invoices.getPdfUrl también (sustituto: regeneratePublicLink). Si tu integración lo usó, regenera la clave de API de la aplicación.
• sdk.webhooks.verify y .parse verifican cualquier familia de avisos, con tipos por evento. sdk.chat.webhooks.verify queda como alias.
• Enumerados derivados del esquema real: InvoiceStatus pasa de 7 a 12 valores y TaxSystem suma IPSI e INTERNATIONAL. En Python, un enumerado incompleto reventaba con un error de validación en la primera factura reembolsada.

API externa: suscripciones, autorizaciones de cobro, cobros programados y acciones sobre la factura

• POST /external/v1/subscriptions y sus trece rutas. Cuotas recurrentes de los usuarios de la aplicación, con generación, envío y cobro automáticos. Exige el aplicativo Finanzas y la capacidad de facturación recurrente.
• /external/v1/payment-authorizations. El consentimiento firmado que habilita cobrar sin el usuario delante, con texto canónico, versión, momento, IP y navegador. Exige Finanzas, Stripe y la capacidad de cobro automático.
• /external/v1/invoices/:id/scheduled-charges y /external/v1/scheduled-charges/:id. Cobros programados para una fecha futura, con cancelación y reintento adelantado.
• Cinco acciones sobre una factura emitida: send (envío por correo con su PDF), mark-paid (cobro fuera de la pasarela), refund, public-link (leer y emitir) y charge (cobro sin nadie delante).
• POST /external/v1/invoices acepta sendEmail y devuelve emailSent. Un emailSent en falso no es una factura fallida: está emitida y numerada, solo falló el correo.
• Puente de identidad. El usuario de la aplicación se materializa como ficha de cliente del CRM la primera vez que se factura, se guarda tarjeta o se crea una suscripción. POST /users/identify acepta clientId para vincularlo a una ficha creada antes.
• POST /users/identify acepta los datos fiscales: taxId y billingAddress (con street, city, postalCode y country obligatorios y province opcional). Se propagan a la ficha del CRM y a la de la pasarela. El alta de factura rellena con el receptor del documento los huecos que el usuario no tenga guardados, y lo que declare identify manda siempre.
• dayOfMonth es opcional en una suscripción mensual: sin él se toma el día de startDate, recortado a 28 cuando es posterior.

CAMBIO QUE ROMPE: el puente solo alcanza las fichas de cliente que creó la propia aplicación

Una aplicación externa solo puede reutilizar, converger o vincular fichas que haya creado ella, con POST /external/v1/clients o con el propio puente. Una ficha nativa del CRM, dada de alta por el equipo, queda fuera de su alcance: identify({ clientId }) la rechaza con 404 CLIENT_NOT_ACCESSIBLE y la deduplicación automática por identificador fiscal o correo tampoco la reutiliza. Cuando la coincidencia cae en una ficha nativa se crea una ficha nueva y el hallazgo se registra en el histórico de auditoría.

Unir una ficha de la aplicación con una ficha nativa sigue siendo posible desde el panel, con sesión iniciada, permiso y alcance.

CAMBIO QUE ROMPE: send solo escribe a direcciones conocidas de la factura

En POST /external/v1/invoices/:id/send, to y cc solo aceptan direcciones ya registradas de esa factura: contactos de facturación activos del cliente puente, contactos del CRM marcados para recibir facturas, el correo del usuario externo y el destinatario con el que se emitió. Cualquier otra rechaza el envío entero con 422 INVOICE_EMAIL_RECIPIENT_NOT_ALLOWED.

Hay además un cupo de 100 envíos por hora y aplicación: superado, 429 RATE_LIMIT_EXCEEDED con la cabecera Retry-After.

CAMBIO QUE ROMPE: las lecturas de una aplicación ya no traen sus claves

GET /integrations/apps y GET /integrations/apps/:id ya no devuelven ninguna clave: traen webhookSecretConfigured, un booleano, y de la clave de API solo su prefijo, su nombre, su estado y sus datos de uso. Las claves se entregan solo al crearlas y al regenerarlas.

El enlace público que emite la aplicación solo permite ver y pagar

allowedActions es siempre ["VIEW", "PAY"] en los enlaces emitidos por la API externa, también cuando la factura viene de una suscripción. Firmar o retirar autorizaciones de cobro no es posible desde ese enlace. El enlace que reparte el equipo desde el panel no cambia. En un cobro con REQUIRES_ACTION, el enlace que se entrega es adicional y no revoca el que el usuario ya tuviera.

Dos códigos de error nuevos donde antes había uno confuso

• AUTO_CHARGE_DISABLED_FOR_ORGANIZATION (409, sin nextStep): la organización tiene apagado el cobro automático con tarjeta. Antes salía como PAYMENT_AUTHORIZATION_REQUIRED, que mandaba a la aplicación a recoger un consentimiento que no desbloqueaba nada. Lo enciende el equipo de la organización en los ajustes de Finanzas.
• SCHEDULED_CHARGE_RETRY_TOO_SOON (409) ya se emite. Estaba declarado y no lo lanzaba nadie: el tope de cinco reintentos manuales por factura cada 24 horas respondía con un 409 sin código.

La configuración de facturación de una aplicación deja de exigir la pasarela

GET y PATCH /integrations/apps/:id/billing-config se gobiernan con Integraciones y Finanzas, sin Stripe, igual que billing-summary. Emitir facturas es capacidad de Finanzas y funciona sin pasarela: una organización con Finanzas y sin Stripe factura por transferencia y registra el cobro a mano. Antes, la pantalla le mostraba un candado que prometía un plan superior para algo que su plan ya incluía. Los cobros con tarjeta siguen exigiendo Stripe.

El permiso «Emitir facturas» deja de anunciarse como reservado

El catálogo describía crm:invoices:issue como un alias reservado que «todavía no es exigido por ningún endpoint» y remitía a POST /external/v1/invoices/:id/issue. Las dos cosas eran falsas: ese endpoint no existe y POST /external/v1/invoices exige el permiso desde el primer día. Crear una factura necesita crm:invoices:write y crm:invoices:issue; el texto de «Crear facturas» lo advierte ahora.

CAMBIO QUE ROMPE: POST /external/v1/users/identify exige permiso

Desde esta fecha exige crm:users:write. Si tu aplicación ya usaba identify, concédele ese permiso antes de desplegar.

CAMBIO QUE ROMPE: se retira el periodo de gracia de los permisos

El periodo de transición de los permisos ha terminado. El permiso se exige en todas las llamadas, también en aplicaciones creadas hace tiempo.

Permisos: 56, con una categoría nueva

• Once permisos nuevos: crm:invoices:send, crm:users:write, billing:refund, los tres de suscripciones, los tres de autorizaciones de cobro y los dos de cobros programados. El catálogo pasa de 45 a 56.
• Categoría financial-critical, para lo que mueve dinero o corta un ingreso: billing:charge, billing:refund, billing:subscriptions:cancel, billing:payment-authorizations:write y crm:invoices:cancel. Mismas exigencias al conceder que los críticos de datos personales, con distinto motivo de blindaje, porque quien revisa la solicitud necesita saber por qué está protegido.
• El catálogo se recorta por el plan. Cada entrada declara qué aplicativos y capacidades exige, UTILIA OS lo recorta antes de servirlo y conceder un permiso fuera de plan responde 400 SCOPE_OUT_OF_PLAN. Un cambio de plan nunca borra permisos ya concedidos: dejan de resolverse.

Avisos: dieciséis eventos nuevos en dos dominios

• Suscripciones (ocho): SUBSCRIPTION_CREATED, _UPDATED, _PAUSED, _RESUMED, _CANCELLED, _COMPLETED, _INVOICE_GENERATED y _PAYMENT_AUTHORIZATION_PENDING.
• Cobros programados (ocho): CHARGE_SCHEDULED, _STARTED, _SUCCEEDED, _FAILED, _REQUIRES_ACTION, _RETRY_SCHEDULED, _RETRIES_EXHAUSTED y _CANCELLED.
• Dos más en dominios existentes: PAYMENT_METHOD_EXPIRING y PAYMENT_AUTHORIZATION_CONSUMED.
• INVOICE_SENT ya se emite. Estaba declarado desde el principio y nunca llegaba a nadie.
• PAYMENT_AUTHORIZATION_GRANTED y _REVOKED pasan a dirigidos cuando el recurso pertenece a un usuario de una aplicación externa. Antes viajaban siempre por difusión.
• En CHARGE_REQUIRES_ACTION, la dirección del enlace solo viaja a veces: sí cuando el cobro lo lanzó la aplicación, nulo cuando lo lanzó el motor de cobros programados, porque de un enlace emitido solo se guarda su huella. En los dos casos llega publicLinkAvailable.

2026-09-03

Ámbitos: el portal del cliente sale de «Modificar contactos»

• CAMBIO QUE ROMPE: portal_access exige ámbitos propios. Sus lecturas exigen crm:portal:view y sus diez escrituras crm:portal:manage; ya no basta con crm:contacts:update.
• Sin red de compatibilidad, a propósito. Los tokens con crm:full siguen funcionando sin tocar nada; los demás se reautorizan pidiendo la familia nueva, que el descubrimiento del servidor de CRM ya publica.
• La lectura queda fuera de crm:read pese a terminar en :view, y la gestión fuera de crm:write. Mismo criterio que las personas de contacto del proveedor.

Fusión de duplicados: cuatro ámbitos nuevos que ningún paquete expande

• crm:clients:merge, crm:contacts:merge y crm:leads:merge. Gobiernan las operaciones deduplicate y merge de clientes, contactos y leads. Fusionar archiva o borra fichas y reescribe sus punteros en medio centenar de tablas, sin vuelta atrás desde la aplicación.
• Quedan fuera de crm:read, crm:write y también de crm:full, aunque ese paquete expanda su dominio por prefijo. La exclusión es explícita: dejarlos entrar por prefijo se lo habría concedido, sin ningún acto nuevo del titular, a toda integración autorizada hace meses con crm:full. Se piden por su nombre.
• Las previas por reglas siguen siendo baratas. deduplicate_preview de clientes y contactos es lectura pura bajo el ámbito de ver, así que se puede enseñar el trabajo pendiente a una persona sin pedir el de fusionar. La previa de merge, en cambio, la ejecuta la misma operación destructiva y exige el ámbito de fusión.
• dryRun es lo único que distingue una previa de una fusión aplicada: las dos respuestas tienen la misma forma. Quien no lo mire dará por fusionado lo que sigue intacto.
• crm_clients: merge añade dos banderas que exigen alcance total sobre el permiso de fusionar: allowDifferentTaxId (dos identificadores fiscales distintos son la misma empresa, sin excepción si las dos fichas tienen facturas emitidas) y allowPortalAccessMerge (los interlocutores externos de una empresa pasan a ver los documentos de la otra).

SDK JavaScript 2.27.0 y SDK Python 2.27.0

• sdk.mcp.crm es un servicio nuevo, contra POST /api/mcp/crm, con los sub-espacios clients, contacts y leads: altas y ediciones sueltas y en lotes de hasta 50, duplicados, fusión con su previa, búsqueda de datos de empresa en internet, consentimiento de correo del contacto y transiciones del lead.
• El CRM gana la fusión de duplicados en los dos SDK: deduplicatePreview, deduplicate, mergePreview y merge en clientes y contactos, y mergePreview / merge en leads. Los métodos de fusión envían la confirmación por ti; los de previa, no, y ahí está toda la diferencia.
• Guía nueva de punta a punta: Poner al día una cartera de clientes, con lotes, logotipos, fusión con previa y espejo incremental por cursor, en los dos SDK.

2026-09-02

SDK JavaScript 2.26.0 y SDK Python 2.26.0: buscador global y avisos

• Dos herramientas MCP transversales nuevas. sdk.mcp.search (buscador global del ecosistema, publicado en los servidores de gestión del trabajo, CRM y Finanzas) y sdk.mcp.notifications (avisos de la persona que autorizó el token y sus preferencias, en los siete servidores). Tienen página propia.
• Los datos bancarios y fiscales dejan de viajar por defecto. Ámbitos nuevos finance:suppliers:view-sensitive y crm:clients:view-sensitive, fuera de los conjuntos de lectura y escritura. Los tokens emitidos antes los conservan hasta el 2 de marzo de 2027.
• REGRESIÓN DECLARADA: dev:write y crm:write dejan de borrar archivos, versiones y carpetas del gestor. Para borrar hace falta dev:files:full o crm:files:delete. En contrapartida, dev:write gana dev:files:manage.
• Vincular archivos a una ficha exige FILE_MANAGER_LINK_CRM, no CLIENTS_EDIT, y las herramientas de archivos admiten trece tipos de ficha en vez de siete.
• El cliente MCP deja de tragarse el mensaje de los errores de una tool: lee las tres formas que conviven, añade la pista al mensaje y conserva el código original en errorCode.

SDK JavaScript 2.25.0 y SDK Python 2.25.0: fusión con superviviente elegido

• La fusión de duplicados deja de imponer quién sobrevive: deduplicate({ survivorIds }) elige como mucho uno por grupo, y llamar sin argumentos se comporta exactamente igual que antes. Un identificador que no manda sobre nada es un error, no un valor descartado en silencio: la operación es todo o nada.
• La previa devuelve por fin los números de todos los miembros, el superviviente propuesto incluido: sin ellos no se puede saber qué se movería al elegir a otro.

2026-09-01

SDK JavaScript 2.24.0 y SDK Python 2.24.0: las personas del proveedor dejan de ser contactos del CRM

• CAMBIO DE SUPERFICIE. Las personas de contacto de un proveedor pasan a ser una entidad propia de Finanzas que vive dentro del proveedor, con su propio identificador y sus propios permisos. El motivo es de producto: hasta entonces, para ver con quién se habla en un proveedor hacía falta tener contratado el CRM.
• linkContact y unlinkContact desaparecen y no se sustituyen por nada: ya no hay nada que atar ni que soltar. El equivalente es createContact para el alta y deleteContact para la baja.
• getContact y deleteContact son nuevos, y updateContact cambia de firma: direcciona la persona por su propio identificador, no por el par proveedor más contacto.

2026-08-05

SDK JavaScript 2.23.0 y SDK Python 2.23.0: campañas, listas y entregabilidad de Marketing

• sdk.mcp.marketing pasa a cubrir SEIS herramientas enteras. Se añaden campaigns (marketing_campaigns, 35 operaciones), lists (marketing_lists, 17) y deliverability (marketing_deliverability, 10), y reports se completa con complaints, linkHeatmap y audienceTech (doce en total). Los mismos nombres en snake_case en Python, en variante asíncrona y síncrona.
• Qué hizo la audiencia y segundos intentos: engagementBreakdown (gratuito), resendPreview, createResend y listResends. Los siete grupos no son porciones de una tarta —opened ya contiene a clicked— y «no abrieron» excluye siempre a quien pulsó. Un segundo intento nunca escribe a quien se quejó, exige un asunto distinto del original, admite como mucho dos por campaña y no toca los contadores de la campaña original.
• listRecipients deja de perder el filtro de EXCLUIDOS (isExcluded) y gana engagement, ortogonal al resultado de envío.
• Interés de los suscriptores y apartado de inactivos: listSubscribers (que no existía en MCP, así que apartar era un viaje de ida), engagementSummary, setAsideInactive (vista previa por defecto) y reactivateSubscriber. Apartar no es dar de baja: no se toca el consentimiento.
• Política de quejas: getComplaintPolicy y setComplaintPolicy. El inquilino solo puede ser más estricto (10 a 30 puntos básicos); el techo del 0,3 % y el bloqueo del servidor compartido son de plataforma. Antes de un bloqueo hay siete días sostenidos y un aviso por correo con 48 horas de antelación, y se levanta solo cuando la tasa baja.
• La tasa de quejas es null cuando no hay forma de medirla y un SUELO cuando la hay. Nunca es un cero.
• HUECO ESCRITO: deviceType, emailClient y country de listRecipients se omiten sin el permiso EMAIL_MARKETING_VIEW_RECIPIENT_DETAIL y el scope nuevo marketing:recipients:detail:view. La operación responde igual y llega recipientDetailIncluded: false: el recorte va por campo y no por operación para que ningún token ya emitido pierda la operación.
• HUECO ESCRITO: el mapa de calor por enlace no existe para automatizaciones ni para las campañas anteriores a la medición por enlace. Eso no es un cero. El desglose por dirección de destino (clickThrough) sigue disponible para todo y es gratuito.
• Scope nuevo en el servidor Marketing: marketing:recipients:detail:view. Documentado en Descubrimiento OAuth y en Servidor MCP Marketing.

SDK JavaScript y SDK Python: informes de Marketing

• Nuevo sdk.mcp.marketing.reports, la herramienta MCP marketing_reports entera: campaignStats, engagementOverview, clickThrough, topCampaigns, engagementHeatmap y engagementTrends (los mismos seis en snake_case en Python, en variante asíncrona y síncrona). Solo lectura y sin capacidad de plan. Detalle en Servidor MCP Marketing.
• Las cifras de campaña cambian de base, no solo de nombre: aparecen accepted, delivered (que vale null sin detección de devueltos), acceptanceRate, clickToOpenRate, metricsAvailability y bounceDetectionEnabled; deliveryRate queda sustituida por acceptanceRate, la tasa de rebote pasa a calcularse sobre los aceptados y el recuento de rebotados deja de incluir los fallos de salida. Quien tuviera cifras guardadas verá números distintos para las mismas campañas. Las definiciones, con su denominador, en Definiciones de las métricas de Marketing.
• sendStatus deja de admitir OPENED y CLICKED al filtrar destinatarios: nunca fueron estados de entrega y filtrar por ellos devolvía una lista vacía sin dar ningún error. Ahora responde con un error que lo explica. Usa las marcas de tiempo openedAt y clickedAt.
• Los errores de plan se distinguen de los de permiso: isPlanError() / is_plan_error y el objeto planContext. Ojo, por el carril MCP ese código no viaja: ver Errores de plan.

SDK JavaScript y SDK Python: medición del origen y negocio por campaña

• Nuevo sdk.mcp.marketing.trackingSettings / tracking_settings, la herramienta MCP marketing_tracking_settings entera desde su primera versión: get, update y previewLink / preview_link. Configura qué etiquetas de origen se añaden a los enlaces de los correos y si viaja el identificador del destinatario. previewLink es una función pura: no firma nada y no emite ningún identificador real.
• Scope OAuth nuevo marketing:tracking:manage, que no entra en marketing:write y hay que pedir de forma explícita (o usar marketing:full). En la pantalla de autorización aparece con su propio bloque. Ver Descubrimiento OAuth y Pantalla de consentimiento.
• sdk.mcp.marketing.reports se completa con la atribución de ingresos: campaignAttribution, attributionSummary y entityOrigin (los mismos en snake_case en Python). topCampaigns admite además CONVERSIONS (oportunidades originadas, no ventas cerradas), REVENUE_ISSUED y REVENUE_COLLECTED; hasta ahora CONVERSIONS devolvía un error diciendo que el producto no las registra.
• Dos huecos que hay que leer antes de integrar. Los importes de la atribución no viajan por el servidor MCP de marketing (su token no puede portar scopes de finanzas): llegan los recuentos y el bloque de dinero se declara en excludedBlocks con reason: 'missing_scope', que no es un cero. Y las facturas creadas con sdk.invoices.create() (API externa v1) nacen sin vínculo comercial y quedan fuera del negocio originado por cualquier campaña, porque esa API no admite opportunityId.
• Los formularios de captación ganan captureUtm y utmPersistence en los tipos de lead_forms_create y lead_forms_update, y el envío público admite _utm y _ur. Aviso para quien incruste el widget: se sirve con una caché de hasta 24 horas sobre una dirección sin versión, así que los sitios ya publicados pueden tardar ese tiempo en tomar la versión nueva. Ver Insertar un formulario en tu web.

SDK JavaScript y SDK Python: enlaces con el dominio del cliente

• Nuevo sdk.mcp.marketing.trackingDomains / tracking_domains, la herramienta MCP email_tracking_domains entera desde su primera versión: list, get, getSetupInstructions, create, verify, setEmission, retryCertificate y retire (los mismos en snake_case en Python, en variante asíncrona y síncrona). Hace que los enlaces medidos de las campañas salgan por un subdominio del cliente en vez de por un dominio de UTILIA, que es lo último que quedaba con efecto real sobre la entregabilidad: los filtros antispam penalizan que los enlaces de un correo apunten a un dominio ajeno al remitente.
• Ningún scope nuevo. Se reutilizan marketing:deliverability:view y marketing:deliverability:manage, que ya existían. Las tres lecturas admiten además marketing:campaigns:view, porque el permiso que pide el REST es la vista del módulo y sin esa alternativa el token cerraría lo que el permiso abre.
• Ninguna operación borra nada, y es una decisión. retire programa el fin del servicio y devuelve en serveUntil / serve_until la fecha hasta la que ese subdominio sigue atendiendo los enlaces de los correos ya entregados. Un enlace de un correo ya enviado no se puede romper: lleva su dominio escrito dentro y no hay forma de reescribirlo.
• create no empieza a medir. El alta solo abre el proceso; la medición se enciende con setEmission cuando el dominio está sirviendo. Informar de que «ya se mide por su dominio» justo después de crearlo es falso.
• Aviso que hay que trasladar al cliente: si retira su registro CNAME, el certificado deja de poder renovarse y a los 90 días como mucho los enlaces de sus correos YA ENVIADOS dejan de abrirse con un aviso de seguridad del navegador. certificateExpiresAt / certificate_expires_at trae la fecha exacta. Ver Enlaces con tu propio dominio.
• Puerta de plan: create, verify, set_emission y retry_certificate exigen las dos capacidades del lote de medición, «Analítica avanzada de Marketing» y «Negocio por campaña». Quedan exentas las tres lecturas y retire, que es la salida: quien deja de tener las capacidades sigue viendo su subdominio y puede soltarlo cuando quiera.

---

2026-08-03

SDK JavaScript 2.22.0 y SDK Python 2.22.0

• Imágenes de presupuesto completas. sdk.budgets gana uploadImageToSection / upload_image_to_section (colocar una imagen dentro de un apartado), scanLegacyImages / scan_legacy_images (detectar las imágenes heredadas incrustadas en el HTML, que se ven en el editor y no salen en el PDF) y migrateLegacyImages / migrate_legacy_images (convertirlas en colocaciones reales, de forma idempotente y tolerando fallos parciales).
• textWrap queda obsoleto: el generador del PDF nunca lo aplicó, la imagen siempre ocupa su propia línea. Se sigue aceptando y el servidor lo ignora.
• La opción deleteFile al borrar una imagen queda obsoleta: el borrado del binario pasó a ser automático por recuento de referencias.
• Cambios aditivos, sin rupturas de contrato.

---

2026-07-28

SDK JavaScript 2.21.0 y SDK Python 2.21.0

• sdk.oauth.getAuthorizedApps() / get_authorized_apps() devuelve los permisos ya traducidos y recortados por el plan de la organización: permissions, permissionCount, unavailablePermissionCount y unavailableModules. Todos los campos son opcionales, para no romper contra un backend anterior.
• AuthorizedApp.scope queda obsoleto (retirada prevista el 2027-02-01) y cambia de significado: ya no es el universo de scopes concedidos a la aplicación, sino ese universo recortado por el plan. Quien lo use para decidir qué puede hacer la aplicación verá menos de lo que hay; sustitúyelo por permissions y unavailablePermissionCount.

---

2026-07-12

SDK JavaScript 2.20.0 y SDK Python 2.20.0

• Plataforma de chat extensible: nuevo servicio sdk.chat sobre /external/v1/chat, con publicación de mensajes como aplicación (v1) y lectura de canales, miembros e historial visible (v2), más sdk.chat.webhooks.verify() para validar localmente la firma HMAC.
• Detalle completo en Plataforma de chat.

---

2026-07-05

API externa de clientes: grupos de empresas

• El CRM incorpora los grupos de empresas (matriz y filiales, dos niveles) y la API externa /external/v1/clients los refleja de forma aditiva: parentClientId en todas las respuestas, parent { id, name, slug } en el detalle y el endpoint nuevo GET /external/v1/clients/:id/group.
• PATCH /external/v1/clients/:id acepta parentClientId para vincular una filial a su matriz o desvincularla con null. Exige el scope nuevo crm:clients:write:hierarchy además de crm:clients:write; las API Keys existentes NO lo obtienen automáticamente. El catálogo de scopes pasa de 35 a 36.
• Webhooks nuevos CLIENT_LINKED_TO_GROUP y CLIENT_UNLINKED_FROM_GROUP, con payload de solo identificadores. La mutación del vínculo NO dispara CLIENT_UPDATED.
• Errores nuevos: 409 CLIENT_HIERARCHY_CONFLICT y 422 CLIENT_HIERARCHY_INVALID_TYPE.
• Detalle en Endpoints de clientes del CRM y Gestión de scopes.

SDK JavaScript 2.18.0 y SDK Python 2.18.0

• sdk.externalClients.getGroup(id) / sdk.external_clients.get_group(client_id) y soporte de parentClientId en update (en Python, parent_client_id con None explícito para desvincular).
• Tipos y modelos nuevos: ExternalClientParent, ExternalClientHierarchyRole, ExternalClientGroupResponse. Espejo del catálogo de scopes actualizado a 36 entradas.
• Cambios aditivos, sin cambios incompatibles. Matriz completa en Versiones y compatibilidad del SDK.

---

2026-07-02

SDK JavaScript 2.17.0 y SDK Python 2.17.0

• Nuevo método sdk.mcp.opportunities.listStages() / list_stages(): devuelve las etapas del pipeline por defecto de la organización, cuyos id son los valores válidos para cambiar de etapa una oportunidad.

---

2026-05-27

Avisos: la firma HMAC pasa a calcularse sobre timestamp.rawBody (cambio que rompe)

• Todas las entregas de webhook cambian de mensaje firmado. Hasta esta fecha la cabecera X-Utilia-Signature se calculaba sobre el cuerpo crudo a secas; desde este despliegue se calcula sobre la cadena `${timestamp}.${rawBody}`, donde timestamp es exactamente el valor de la cabecera X-Utilia-Timestamp (milisegundos Unix). Es el patrón que popularizó Stripe y añade defensa anti-replay.
• Rompe a todo receptor que no se actualice. Un receptor que siga firmando solo el cuerpo obtendrá siempre una firma distinta y rechazará las entregas legítimas (normalmente con 401). Como un 4xx se trata como fallo permanente, la entrega se cierra sin agotar los reintentos y el evento se pierde.
• Qué hay que cambiar en tu servidor: reconstruye el mensaje como `${timestamp}.${rawBody}` antes de calcular el HMAC-SHA256, comprueba que X-Utilia-Timestamp está dentro de una ventana de ±5 minutos y compara en tiempo constante. Ejemplos completos en Node.js y Python en Firma HMAC de los avisos.
• El envío de prueba del panel no acompañó al cambio en ese momento y seguía firmando solo el cuerpo. Ya está corregido: hoy la prueba firma exactamente igual que las entregas reales. Detalle en Entregas y reintentos de los avisos.

---

2026-05-12

MCP: la herramienta tickets puede crear tickets

• Nueva operación de creación de tickets de soporte vía MCP. Ya estaba disponible la lectura y la actualización; ahora también la creación.
• Quien abre el ticket es siempre la persona del token; no se puede abrir en nombre de otra.
• Se quita el HTML de title y description antes de guardarlos, para que no pueda ejecutarse código si el contenido se muestra como HTML.
• Límite propio del canal MCP: como mucho 10 tickets por hora y persona. El límite general de MCP (60 peticiones por minuto) sigue aplicándose por encima.
• Trazabilidad en la actividad del ticket: TICKET_CREATED registra el canal (source: 'mcp') y el oauthClientId del token de origen.

OAuth: el conjunto support:write

• El conjunto support:write ahora se expande a support:tickets:create además de support:tickets:update. Los clientes OAuth con support:write autorizado antes del 12 de mayo de 2026 pueden crear tickets sin volver a dar su consentimiento. Consulta los detalles en la referencia de scopes.

---

2026-04-08

SDK JavaScript 1.8.0

• Nuevo parámetro theme en getAuthorizationUrl(), getLoginUrl() y loginWithPopup(): permite solicitar tema claro ('light') u oscuro ('dark') en la pantalla de consentimiento OAuth.

SDK Python 0.7.0

• Nuevo parámetro theme en get_authorization_url() y get_login_url() (versión asíncrona y síncrona): permite solicitar tema claro ('light') u oscuro ('dark') en la pantalla de consentimiento OAuth.

---

2026-04-05

Documentación de OAuth

• Página nueva para obtener un token en cinco minutos: OAuth: tu primer token en 5 minutos.
• Página nueva de botones y marca, con logotipos, colores, tipografía y código del botón «Iniciar sesión con UTILIA».
• Página nueva de problemas frecuentes, con los diez fallos más comunes al integrar OAuth.
• Reescritas las seis páginas de referencia (visión general, descubrimiento, flujo de autorización, token y revocación, scopes y recursos, pantalla de consentimiento), con ejemplos en curl, JavaScript y Python.

---

2026-04-02

OAuth en el panel de aplicaciones

• OAuth integrado en cada aplicación externa (hoy, pestaña OAuth de su ficha).
• Configuración del nombre, las direcciones de retorno y los scopes.
• Generación y regeneración de Client ID y Client Secret.
• Visualización y revocación de aplicaciones autorizadas.

Soporte OIDC (OpenID Connect)

• Endpoint /.well-known/openid-configuration para descubrimiento automático.
• Endpoint /api/oauth/userinfo para obtener claims del usuario autenticado.
• Endpoint /api/oauth/jwks para verificación de firma de ID tokens.
• ID tokens JWT con claims estándar: sub, name, email, picture, etc.
• Scopes OIDC: openid (obligatorio), profile, email.

SDK JavaScript 1.7.0

• Flujo OAuth 2.1 simplificado: getAuthorizationUrl() gestiona PKCE automáticamente.
• handleCallback(code): recupera el code_verifier sin parámetros manuales.
• Validación automática del estado CSRF en handleCallback.
• isAuthenticated(): verifica si hay sesión OAuth activa.
• logout(): revoca tokens y limpia el almacenamiento.
• loginWithPopup(): inicio de sesión OAuth mediante ventana emergente para SPAs.
• ErrorCode.AUTH_EXPIRED: código de error nuevo para sesiones OAuth caducadas.
• Estado PKCE persistente en MemoryTokenStorage y FileTokenStorage.

SDK Python 0.6.0

• Flujo OAuth 2.1 simplificado: get_authorization_url() gestiona PKCE automáticamente.
• handle_callback(code): recupera el code_verifier sin parámetros manuales.
• Validación automática del estado CSRF en handle_callback.
• is_authenticated(): verifica si hay sesión OAuth activa.
• logout(): revoca tokens y limpia el almacenamiento.
• ErrorCode.AUTH_EXPIRED: nuevo código de error para sesiones OAuth expiradas.
• Corrección crítica: el cliente síncrono ahora comparte storage con el asíncrono.
• Estado PKCE persistente en MemoryTokenStorage y FileTokenStorage.

---

Versiones vigentes