Versiones y compatibilidad

Esta página es la referencia única de versiones del ecosistema de integración de UTILIA OS: la API externa, los dos SDK oficiales y el widget. Úsala para fijar las dependencias de tu proyecto y para saber qué aporta cada versión antes de actualizar.

Matriz de versiones

La 4.8.0 es la versión del repositorio en los dos lenguajes y está sin publicar. La 4.7.0, del 22 de octubre de 2026, y la 4.6.0 y la 4.5.0, del 21, tampoco se han publicado todavía. La última publicada, la que instalan npm install @utilia-os/sdk-js y pip install utilia-sdk, es la 4.1.0 en npm y la 4.2.0 en PyPI. La 4.1.1 no llegó a publicarse por separado: sus cambios van incluidos en la 4.2.0, y cada versión incluye las anteriores. Los dos SDK comparten numeración, para que la paridad entre lenguajes se mantenga versión a versión.

Antes de dar por hecho que un método existe, comprueba qué versión tienes con npm ls @utilia-os/sdk-js o pip show utilia-sdk: si vienes de la 3.x, la 4.0.0 retiró tres métodos y tu código puede depender de ellos.

Lo que todavía no puedes instalar

Varias guías enseñan métodos de versiones sin publicar. Las rutas de la API funcionan igual sin ellos: mientras tanto, llámalas directamente con los ejemplos de curl de cada guía.

El widget 1.2.0, con la opción userSignature para la verificación de identidad, tampoco está publicado: el que se instala es el 1.1.0, que no manda la firma.

Novedades de la versión 4.8.0

La 4.8.0 está sin publicar en npm y en PyPI. Trae las suscripciones a las aplicaciones de pago del catálogo y necesita el servidor con los cobros de aplicaciones; contra uno anterior, subscription no llega. No hay métodos nuevos de escritura: comprar, cambiar de plan, cancelar o pagar se hace en UTILIA OS.

• La suscripción de cada instalación. En una ficha «De pago en UTILIA», appInstallations.list() y get() traen subscription (ExternalAppSubscription): plan, precio sin impuestos, estado (TRIALING, ACTIVE, PAST_DUE, PAUSED o ENDED), prueba, periodo, cancelación y cambio programado. list({ subscriptionStatus }) (subscription_status en Python) filtra por su estado. Ver La suscripción de una aplicación de pago.
• isAccessAllowed(instalacion) (is_access_allowed): si la empresa puede usar tu aplicación, mirando la instalación y su suscripción.
• Avisos de la suscripción. Doce avisos APP_SUBSCRIPTION_* en el dominio integrations (APP_SUBSCRIPTION_WEBHOOK_EVENTS) y su carga tipada, AppSubscriptionWebhookData. Ver Los avisos de la suscripción.
• MCP. installationsGet() e installationsList() traen subscription, sin importe si no puedes ver el plan de la empresa. Salen listingsList() y listingsGet(), que llegaron con la 4.7.0 sin publicarse: las fichas que publica una cuenta de desarrollador se gestionan en el servidor de desarrolladores.

Novedades de la versión 4.6.0

La 4.6.0 está sin publicar en npm y en PyPI. sdk.diagnostics, la orden doctor, el diagnóstico de las claves de la organización y la orientación de los errores necesitan el servidor con el sistema de pruebas de la API, y la captura y la gestión de los errores, el servidor con POST /external/v1/errors/batch y las rutas de gestión; el resto funciona igual contra un servidor anterior. La guía de la captura está en Capturar los errores de tu aplicación. Todo es aditivo salvo los tipos de sdk.mcp.integrationsOverview y los cambios de la tabla de debajo.

• Comprobar tu integración. sdk.diagnostics, con la clave de tu aplicación y sin ningún permiso de la API: me(), get(), calls(), checkRequest(), run(), sendWebhookSample(), checkWebhookReceiver() y openApi(), sobre GET /external/v1/me y las rutas de /external/v1/diagnostics. En Python, los mismos en snake_case (check_request, send_webhook_sample, check_webhook_receiver, open_api), asíncronos y síncronos. Ver Referencia de métodos.
• La orden doctor. npx @utilia-os/sdk-js doctor en JavaScript y utilia-doctor en Python, con --run, --check "POST /external/v1/invoices" --body cuerpo.json, --json, --strict, --base-url y --allow-insecure-http. Lee la clave de UTILIA_API_KEY (nunca la muestra) y sale con 0 si no hay nada que bloquee, 1 si lo hay (con --strict, también si hay avisos) y 2 si no se pudo comprobar. No manda la clave por http:// salvo a este mismo equipo (localhost, 127.0.0.1 o ::1). Pensada para tu asistente de IA y tu integración continua: ver La orden doctor.
• Instrucciones para tu asistente de IA. diagnostics.getMarkdown() (get_markdown()) pide GET /external/v1/diagnostics?format=markdown y devuelve el texto, sin la clave.
• Diagnóstico de las claves de API de la organización. diagnostics.organizationApiKey() (organization_api_key()) pide el diagnóstico de una clave utk_. Una clave utk_ pasada en apiKey viaja ahora en Authorization: Bearer, que es donde la acepta el servidor (antes iba en X-Api-Key y se rechazaba siempre), y doctor la reconoce por su prefijo.
• Claves publicadas en una web. Con la clave de una aplicación con dominios autorizados, calls(), run(), sendWebhookSample() y checkWebhookReceiver() responden 403 DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY (constante nueva en los dos SDK) y el diagnóstico trae credential.publishable. doctor --run no lanza la prueba activa con esa clave: lo explica y no lo cuenta como fallo.
• Campos que ya mandaba el servidor: traffic.hourly del diagnóstico, credential.publishable de me(), y payload y responseSnippet de la muestra de un aviso. DiagnosisAccessReason gana TENANT_SUSPENDED, TENANT_CANCELLED y PUBLISHABLE_KEY_CEILING.
• Uso de IA de tu aplicación. sdk.aiAnalytics.getOverview() y getTrends() (sdk.ai_analytics.get_overview() y get_trends()), con startDate y endDate opcionales y el scope analytics:ai:read.
• Comentarios de presupuesto con clave de API. budgetComments.list y create van a /external/v1/budgets/{budgetId}/comments, siempre con visibilidad CLIENT. update y remove lanzan METHOD_NOT_AVAILABLE_WITH_API_KEY sin hacer la petición.
• Campos descartados. La opción onIgnoredFields (on_ignored_fields) recibe los campos que el servidor descartó sin error en una escritura (cabecera X-Utilia-Ignored-Fields); sin la opción, el SDK deja un aviso en la consola o en el registro utilia_sdk.
• Errores que dicen quién lo arregla. UtiliaSDKError gana fixedBy, docsUrl, requiredScopes y retryAfterMs (fixed_by, docs_url, required_scopes y retry_after, en segundos), y retryable llega del cuerpo de todo error de /external/v1, con el ayudante readErrorGuidance (read_error_guidance). Códigos tipados nuevos: INSUFFICIENT_SCOPE (con isInsufficientScopeError), DIAGNOSTICS_RATE_LIMITED, DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY, DIAGNOSTICS_UNAVAILABLE, BUDGET_ERROR_CODES y, entre los de las credenciales, API_KEY_WRONG_KIND, API_KEY_WRONG_HEADER y AUTH_TOKEN_INVALID. INSUFFICIENT_SCOPE_MESSAGE queda en desuso: el servidor ya nombra el permiso que falta.
• Catálogo público de errores. PUBLIC_API_ERROR_CATALOG trae cada errorCode de la API con quién lo arregla y si se puede repetir, comprobado contra el del servidor. REQUEST_ERROR_CODES tipa los errores de la forma de la petición (INVALID_JSON, JSON_CONTENT_TYPE_REQUIRED, METHOD_NOT_ALLOWED y REQUEST_BODY_TOO_LARGE), y los de facturas ganan INVOICE_PDF_PENDING, INVOICE_PDF_REVIEW_REQUIRED, INVOICE_PDF_STORAGE_UNAVAILABLE, INVOICE_NUMBERING_UNAVAILABLE, INVOICE_ISSUANCE_REVIEW_REQUIRED y RECTIFICATION_OPERATION_INCOMPLETE.
• Avisos tipados con sus nombres reales. ChatWebhookEvent lleva los nombres que manda el servidor (CHAT_MESSAGE_CREATED…) y llegan ALL_WEBHOOK_EVENTS, WEBHOOK_EVENTS_BY_DOMAIN, WebhookEventName e isWebhookEventName (is_webhook_event_name), comprobados contra el catálogo del servidor.
• Datos fiscales de los usuarios. Permiso nuevo crm:users:read:fiscal-data: sin él, users.list no trae el NIF ni la dirección de facturación, e identify solo los que mandas en esa llamada. ExternalUser los declara opcionales. Ver Usuarios externos.
• Claves dentro de una página web. Constantes nuevas SCOPE_NOT_ALLOWED_FROM_BROWSER (403, con los permisos en error.details.notAllowedScopes) y SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS (400), y el hallazgo PUBLISHABLE_KEY_SENSITIVE_SCOPES, que doctor enseña como aviso. Ver Claves dentro de una página web.
• Catálogo de permisos. Los nombres y las descripciones de EXTERNAL_API_SCOPE_DESCRIPTIONS son copia de los que enseña el panel. Los valores de los permisos no cambian: compara el valor, no el texto.
• Tipos de sdk.mcp.integrationsOverview con la forma real del servidor. Los de status(), health() y quickstart() prometían campos que el servidor no manda (worstApp.name, credentials.v1Count, webhooks.last24hSuccessRate, events.catalogCount…), y en Python status() fallaba al validar la respuesta. Ahora son copia de la respuesta: health.worstApp.appName (worst_app.app_name), status.webhooks.last24h.successRate, events.catalogSize, y los nuevos apiCalls, appsByStatus y appsNeedingAttention. Llega también appDiagnosis(appId) (app_diagnosis), el diagnóstico de una aplicación por MCP.
• Captura de errores. errors.install engancha lo que nadie trata (en el navegador, error y unhandledrejection; en Node, uncaughtExceptionMonitor; en Python, sys.excepthook, threading.excepthook y asyncio) y errors.capture (capture_exception) y captureMessage (capture_message) envían lo que atrapas. Nunca lanzan: van a una cola en memoria que envía en lotes de 25 por POST /external/v1/errors/batch, junta los repetidos, respeta Retry-After y no se reporta a sí misma. flush envía lo pendiente.
• Más métodos de errors. reportBatch (report_batch), get, resolve, reopen, silence y unsilence. La gestión exige el scope nuevo analytics:errors:manage: el catálogo pasa a 59.
• Respuestas que dicen la verdad. report devuelve accepted, status (created, updated o regressed) o reason, y count. SystemError (SystemErrorEntry) gana status, silencedUntil, environment, firstRelease, lastRelease, regressionCount y lastRegressedAt, y ErrorStats, silenced.
• Campos nuevos al enviar: release, environment, fingerprint y tags en ReportErrorInput. ErrorFilters gana status y firstRelease (first_release), y en JavaScript severity admite una sola gravedad o una lista.
• ai.reportError (report_error) admite release y environment y hace un solo intento.
• Corregido (JavaScript): errors.list enviaba varias gravedades como severity[]= y el servidor ignoraba el filtro. Ahora van como parámetro repetido.

Qué cambia si vienes de la 4.5

Los tres últimos cambios de los errores son del servidor, no del SDK: llegan igual con cualquier versión.

Las lecturas, PUT, PATCH, DELETE y los POST que solo consultan (invoices.validate, users.identify, el pase de conexión, checkRequest, run y el carril MCP) se reintentan como antes.

Novedades de la versión 4.5.0

La 4.5.0 (2026-10-21) trae los métodos de las claves de API de la organización y el ensayo de facturas sin numerar, y retira los métodos que ninguna organización cliente podía usar. Está sin publicar en npm y en PyPI.

• Claves de API de la organización por MCP. sdk.mcp.apiCredentials gana orgKeysList, orgKeysGet, orgKeysUsage, orgKeysCatalog, orgKeysCandidates, orgKeysCreate, orgKeysUpdate, orgKeysRotate, orgKeysEndTransition y orgKeysRevoke (en Python, en snake_case). Crear, renovar y ampliar una clave piden la confirmación en el móvil: la primera llamada lanza APPROVAL_REQUIRED y se repite con twoFactorApprovalId. Ver las operaciones org_keys_* en la referencia MCP.
• Credenciales personales y de aplicación. create y rotate admiten twoFactorApprovalId, que el servidor ya pedía. create ya no admite kind: 'SERVICE_ACCOUNT' y CreateApiCredentialInput.userId queda en desuso.
• Probar sin facturas reales. invoices.validate, invoices.validatePdf (validate_pdf), invoices.rectifications.validate y webhooks.signTestPayload (sign_test_payload), con los campos displayNumber y emailDelivery en los tipos de las facturas y livemode y meta.test en los avisos.
• Listados del CRM por MCP. El servidor ya no repite la lista en clients, contacts y leads; el SDK rellena ese alias desde items, así que el código que aún lo lee sigue funcionando.

Qué cambia si vienes de la 4.4

Novedades de la versión 4.4.0

La 4.4.0 (2026-10-15) trae las series de facturación de las aplicaciones. Es aditiva: sin seriesCode ni serie por defecto en tu aplicación, todo se numera exactamente igual que en la 4.3.

• Series de tu aplicación. Tu organización puede reservar a tu aplicación una o varias series (por ejemplo, APP-202600001), separadas de las facturas del equipo, y fijar cuál se usa por defecto. invoices.listSeries() (list_series(), asíncrono y síncrono) las consulta con crm:invoices:read, y invoices.create las elige con seriesCode (series_code) o DEFAULT para la de siempre. Tu aplicación no crea ni cambia series. Ver Series disponibles.
• Suscripciones: type (ordinarias o simplificadas, estas solo con cuotas de hasta 400 € impuestos incluidos) y seriesCode en el alta y en el cambio. La serie queda fijada en la suscripción.
• Respuestas ampliadas: seriesCode en cada factura (también en las rectificativas, con DEFAULT) y type y seriesCode en cada suscripción. invoices.list filtra por seriesCode.
• Fecha de expedición acotada: issueDate no puede ser futura ni anterior a la de la última factura de la misma serie, y su año es el de la numeración (INVOICE_ISSUE_DATE_OUT_OF_ORDER).
• Errores: INVOICE_ERROR_CODES (InvoiceErrorCode) gana INVOICE_SERIES_NOT_AVAILABLE, INVOICE_SERIES_TYPE_MISMATCH, INVOICE_SERIES_INACTIVE e INVOICE_ISSUE_DATE_OUT_OF_ORDER, y los dos de la gestión de series de la organización (INVOICE_SERIES_PREFIX_RESERVED, INVOICE_SERIES_IN_USE).
• MCP: appsBillingGetConfig y appsBillingUpdateConfig (apps_billing_get_config y apps_billing_update_config) leen y fijan las series por defecto de la aplicación.
• Ventanilla única del IVA (Próximamente). El SDK trae ya el contrato de una función que todavía no está disponible para las organizaciones: taxSystem: 'EU_OSS', líneas EU_VAT con vatRateClass y ossSupplyType, consumerResidence.evidenceItems, invoices.getEuVatRates() (get_eu_vat_rates(), asíncrono y síncrono), taxSystem, consumerCountryCode y ossScheme en las respuestas y los 14 códigos OSS_*. Mientras tanto, cualquier dato suyo responde 403 FEATURE_COMING_SOON, que se reconoce con isFeatureComingSoonError y getComingSoonFeature (is_feature_coming_soon_error y get_coming_soon_feature).
• Permisos: sin scopes nuevos; el catálogo sigue en 57. La descripción de crm:invoices:read dice ahora que también permite consultar las series y, si la ventanilla única está disponible, los tipos de IVA de la Unión.

Qué cambia si vienes de la 4.3

Novedades de la versión 4.3.0

La 4.3.0 (2026-10-13) amplía la facturación de las aplicaciones que cobran con su propia pasarela. Todo es aditivo en la API externa.

• Facturas simplificadas. invoices.create admite type: 'SIMPLIFIED' (type=InvoiceType.SIMPLIFIED): serie propia (T-), hasta 400 € impuestos incluidos y destinatario opcional. Sin type, la factura sigue siendo ordinaria. list filtra por type. Ver Facturas.
• Precios con impuestos incluidos (pricesIncludeTax, prices_include_tax): el total de cada línea es exactamente lo cobrado; 39,99 € con IGIC al 7 % son 37,37 de base y 2,62 de cuota.
• Factura ya cobrada con el bloque payment y residencia del consumidor con consumerResidence (consumer_residence).
• Régimen del pequeño empresario del IGIC (REPEP): causa EXEMPT_IGIC_SMALL_BUSINESS y mención «Exención franquicia fiscal», que UTILIA OS pone sola dentro de un periodo del régimen.
• Rectificativas desde tu aplicación: invoices.rectifications.create y list, sobre POST y GET /external/v1/invoices/:id/rectifications. UTILIA OS decide el código legal (R5 o R1); el bloque refund registra la devolución hecha en tu pasarela. Scope nuevo crm:invoices:rectify, crítico financiero: el catálogo pasa a 57. Ver Facturas rectificativas.
• Respuestas ampliadas: type, legalMentions, originalInvoiceId, paymentRegistered y, por línea, exemptionReason y exempt; en el detalle, rectifications y effectiveTotal.
• Errores: INVOICE_ERROR_CODES e isInvoiceErrorCode (InvoiceErrorCode e is_invoice_error_code en Python) con los códigos nuevos, y los datos de un error de negocio (missingFields, lineNumber, remainingRectifiableAmount) en error.details.
• Corregido: un 403 cuyo mensaje contenía «origen» se reescribía como «Origen no permitido por CORS». El rechazo por origen se reconoce ahora solo por su errorCode (ORIGIN_ERROR_CODES, isOriginErrorCode).

Qué cambia si vienes de la 4.2

Novedades de la versión 4.2.0

La 4.2.0 (2026-10-13) acompaña los cambios de la API externa sobre las claves de las aplicaciones: la clave ya no viaja en ninguna dirección, las claves se pueden renovar con un periodo de transición y el SDK avisa cuando usas la anterior.

• Pase de conexión. sdk.tickets.createStreamToken({ route, userId }) o ({ route, jobId }) (tickets.create_stream_token(route, user_id=..., job_id=...) en Python) pide un pase de un solo uso y cinco minutos para abrir por tu cuenta una conexión en tiempo real, sin la clave en la dirección. En JavaScript, streamUpdates, ai.streamSuggestions y ai.streamTranscription ya lo piden solos, y streamUpdates reconecta con un pase nuevo cada vez (esperas de 1 a 30 segundos) y deja de intentarlo si el servidor rechaza el pase con un 4xx. En Python, las conexiones del SDK llevan la clave en la cabecera. Ver Abrir la conexión por tu cuenta.
• Verificar avisos con varias claves. sdk.webhooks.verify y parse leen también X-Utilia-Webhook-Signatures y aceptan una clave o varias, con fecha de caducidad (validUntil, WebhookSecret(..., valid_until=...) en Python), para poner la clave de firma nueva en tu servidor en cuanto la renuevas. Errores locales nuevos: WEBHOOK_SECRET_EXPIRED y WEBHOOK_SECRET_INVALID. Ver Cuando renuevas la clave de firma.
• Aviso de clave anterior. La opción onApiKeyExpires (on_api_key_expires) recibe, una vez por fecha, el aviso de que la clave en uso es la anterior de una renovación y hasta cuándo vale; sdk.apiKeyExpiresAt (api_key_expires_at) guarda esa fecha. Sin la opción, el SDK deja un único aviso por fecha en la consola o en el registro utilia_sdk. Ver Configurar el cliente.
• El SDK se identifica con la cabecera X-Utilia-SDK (utilia-sdk-js/4.2.0, utilia-sdk-python/4.2.0).
• Errores de las credenciales tipados: CREDENTIAL_ERROR_CODES, isCredentialErrorCode y KnownErrorCode en JavaScript; CredentialErrorCode e is_credential_error_code en Python. Con OAuth, un 401 OAUTH_BEARER_NOT_ALLOWED ya no renueva el token ni repite la petición.
• Confirmación en el móvil de las operaciones MCP: getApprovalChallenge, isApprovalRequired y APPROVAL_REQUIRED (get_approval_challenge, is_approval_required). Ver Confirmar una operación en el móvil.
• budgetSignatures con clave de API: list, get y verify van a /external/v1/budgets/{budgetId}/signatures y funcionan. El resto de métodos lanzan METHOD_NOT_AVAILABLE_WITH_API_KEY antes de hacer la petición. SignerAuditEvent gana ipAddressMasked y deviceLabel.
• MCP, renovación de claves de las aplicaciones externas: appsRegenerateApiKey y appsWebhooksRegenerateSecret admiten graceDays y twoFactorApprovalId, y llegan appsWebhooksSecretCutover, appsWebhooksSecretRetirePrevious, appsWebhooksSecretAdvisoryDismiss, appsApiKeyRetirePrevious, appsApiKeyAdvisoryDismiss, appsSetResponsible, appsListResponsibleCandidates y appsWebhooksTestSigningKey (en Python, en snake_case).

Qué cambia si vienes de la 4.1

El último cambio es del servidor, no del SDK: llega igual con cualquier versión.

Novedades de la versión 4.1.1

La 4.1.1 (2026-10-11) dejó de poner credenciales en las direcciones que genera el SDK. budgets.getPdfUrl, budgetSignatures.getCertificateUrl y budgets.streamGenerateItemsStatus ya no incluyen la clave, y, con clave de API, lanzan antes de construir nada METHOD_NOT_AVAILABLE_WITH_API_KEY, porque sus rutas exigen la sesión de una persona y nunca han aceptado la clave. Con OAuth devuelven la dirección como hasta ahora, sin credenciales. En Python, la clave de las conexiones en tiempo real pasó a viajar solo en la cabecera. Sin cambios incompatibles para ninguna integración que funcionara. No se publicó por separado: va incluida en la 4.2.0.

Novedades de la versión 4.1.0

La 4.1.0 (2026-09-12) añade el calendario laboral de la empresa por MCP, sin cambios incompatibles. sdk.mcp.attendance.holidays envuelve la parte de festivos de la herramienta attendance del servidor de recursos humanos (POST /api/mcp/rrhh):

• getScope() (get_scope() en Python) devuelve el ámbito de la empresa (comunidad autónoma, isla y municipio) y el vocabulario cerrado para elegirlo.
• setScope() (set_scope()) lo fija. No borra ningún festivo: los del ámbito anterior dejan de contar y quedan visibles como «de otros ámbitos».
• import(year) (import_year(year), porque import es palabra reservada en Python) carga el calendario oficial de ese año. Es idempotente.
• list() lista los festivos; applicable filtra los que cuentan para la empresa o los de otros ámbitos.

Los festivos municipales no se cargan: los publica cada ayuntamiento y la respuesta lo avisa en notice. Consultar y listar exige hr:attendance:view; elegir el ámbito y cargar el año, hr:attendance:manage.

Si ya estás en la 4.0.1, subir a la 4.1.0 no te obliga a tocar nada.

Novedades de la versión 4.0.1

La 4.0.1 (2026-09-09) es una versión solo de documentación interna del paquete: no cambia ningún comportamiento ni ninguna firma. Además alinea el número de versión del paquete de Python, que arrastraba un 2.23.0 en su package.json que no correspondía con lo que de verdad se publica.

Si ya estás en la 4.0.0, subir a la 4.0.1 no te obliga a tocar nada.

Novedades de la versión 4.0.0

La 4.0.0 (2026-09-07) añade sdk.paymentMethods.getReadiness() (payment_methods.get_readiness() en Python, en las variantes asíncrona y síncrona), que responde si la organización puede cobrar con tarjeta ahora mismo y por qué no. Es el mismo criterio que usa la interfaz de UTILIA OS para decidir si enseña el botón de cobrar. Tipos nuevos: ChargingReadiness y ChargingReadinessReason. El detalle está en Comprobar si se puede cobrar.

Es una versión mayor porque retira los tres métodos del correo al proveedor: getEmailRecipients, sendEmail y replyEmail.

Novedades de la versión 3.0.0

La 3.0.0 (2026-09-05) hace que la facturación y el cobro de una aplicación externa funcionen de verdad. Es una versión mayor, y la razón principal no es el volumen de cambios: es que cinco servicios que existían y devolvían 401 siempre pasan a funcionar contra otra ruta, y uno desaparece.

Lo que gana:

• sdk.subscriptions funciona, sobre /external/v1/subscriptions, con trece métodos: alta, listado, detalle, cambios, pausa, reanudación, baja, reactivación, generación adelantada, próximo cobro, facturas generadas, historial de ejecuciones y reintento del cobro.
• sdk.paymentAuthorizations es nuevo (sdk.payment_authorizations en Python), con el texto de consentimiento, el alta de la autorización firmada, el listado, el detalle y la retirada.
• sdk.invoices gana cinco acciones: send, charge, markPaid, getPublicLink y regeneratePublicLink.
• sdk.invoices.scheduledCharges funciona, con programar, listar, cancelar y adelantar el reintento.
• sdk.invoices.refunds.create emite el reembolso por la API externa.
• sdk.webhooks.verify y sdk.webhooks.parse verifican la firma de cualquier familia de avisos, con tipos por evento para facturación, suscripciones y cobros.
• sdk.users.identify acepta clientId para vincular el usuario a una ficha de cliente que la aplicación creó antes.
• Los enumerados se derivan 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.
• El catálogo de permisos de los dos SDK pasa a 56, con la categoría nueva de críticos financieros.

Tabla de rupturas

Novedades de la versión 2.27.0

La 2.27.0 (2026-09-04) completa la paridad del CRM en los dos SDK oficiales.

• sdk.mcp.crm es nuevo, con clientes, contactos y leads: altas y ediciones unitarias o por lotes, duplicados, fusiones y transiciones.
• Las operaciones destructivas o con efecto externo mandan confirmación explícita desde sus métodos de alto nivel.
• Los errores MCP conservan errorCode y details, de modo que una integración puede distinguir permisos, campos inválidos y reglas de negocio.

Novedades de la versión 2.26.0

La 2.26.0 (2026-09-02) recoge el lote MCP del 2 de septiembre: dos herramientas transversales nuevas y varios cambios de contrato del servidor. Los detalles y las fechas de caducidad de las redes de compatibilidad están en la sección de cambios de contrato.

• sdk.mcp.search y sdk.mcp.notifications, nuevos. El buscador global del ecosistema y los avisos de la persona que autorizó el token. Tienen página propia.
• El cliente MCP deja de tragarse el mensaje de los errores de una herramienta. Ahora lee las tres formas que conviven, añade la pista al mensaje y conserva el código original en errorCode.

Novedades de la versión 2.23.0

La 2.23.0 (2026-08-05) cierra el lote de medición y atribución de Marketing: sdk.mcp.marketing pasa de 20 a 87 métodos por lenguaje y cubre enteras marketing_campaigns (35 operaciones), marketing_lists (17) y marketing_deliverability (10).

• Comportamiento de la audiencia y segundos intentos: engagementBreakdown (siete grupos, dos niveles, y el recuento es gratuito), resendPreview, createResend y listResends.
• Interés de los suscriptores: listSubscribers —que no existía en MCP—, engagementSummary, setAsideInactive y reactivateSubscriber. Apartar no es dar de baja y el consentimiento no se toca.
• Quejas por correo no deseado: reports.complaints, deliverability.getComplaintPolicy y setComplaintPolicy. La tasa es null cuando no hay forma de medirla, nunca 0 %.
• Medición del correo: reports.linkHeatmap y reports.audienceTech. El país es aproximado y sale de una base local.

Novedades de la versión 2.22.0

La 2.22.0 (2026-08-03) completa las imágenes de presupuesto en sdk.budgets:

• uploadImageToSection(budgetId, sectionId, file, placement?) / upload_image_to_section(...): atajo para colocar una imagen dentro de un apartado. El apartado lo fija la dirección, así que el cuerpo no puede apuntar a otro.
• scanLegacyImages(budgetId) / scan_legacy_images(...): detecta las imágenes heredadas incrustadas en el HTML de los apartados, que se ven en el editor y no salen en el PDF.
• migrateLegacyImages(budgetId) / migrate_legacy_images(...): las convierte en colocaciones reales. Es idempotente y tolera fallos parciales: cada imagen vuelve como MIGRATED o FAILED con su motivo.
• Quedan obsoletos textWrap (el generador del PDF nunca lo aplicó: la imagen siempre ocupa su propia línea) y la opción deleteFile al borrar una imagen (el borrado del binario pasó a ser automático por recuento de referencias). Los dos se siguen aceptando y el servidor los ignora.

Novedades de la versión 2.21.0

La 2.21.0 (2026-07-28) hace que sdk.oauth.getAuthorizedApps() / get_authorized_apps() devuelva los permisos ya traducidos y recortados por el plan de la organización: permissions, permissionCount, unavailablePermissionCount y unavailableModules, todos opcionales para no romper contra un backend anterior.

AuthorizedApp.scope cambió de significado en la 2.21.0. El campo queda obsoleto (retirada prevista el 2027-02-01) y, sobre todo, ya no es el universo de scopes concedidos a la aplicación, sino ese universo recortado por el plan. Un scope que sigue vivo en el token puede no aparecer en el campo si su aplicativo no está contratado, así que quien lo use para decidir qué puede hacer la aplicación verá menos de lo que hay. Sustitúyelo por permissions (lo ejercible) y unavailablePermissionCount (lo que quedó fuera).

Novedades de la versión 2.18.0

La 2.18.0 (2026-07-05) incorpora los grupos de empresas del CRM (matriz y filiales) a la API externa de clientes:

• El tipo ExternalClient incluye parentClientId (escalar, presente en todas las respuestas) y parent { id, name, slug } (solo en el detalle).
• Nuevo método sdk.externalClients.getGroup(id) / sdk.external_clients.get_group(client_id): rol del cliente en su grupo (PARENT / SUBSIDIARY / STANDALONE), referencia a la matriz y lista de filiales. Requiere el scope crm:clients:read.
• update acepta parentClientId para vincular una filial a su matriz o desvincularla (null en JavaScript; None explícito en Python). Requiere el sub-scope nuevo crm:clients:write:hierarchy además de crm:clients:write.
• Webhooks nuevos CLIENT_LINKED_TO_GROUP y CLIENT_UNLINKED_FROM_GROUP (payload de solo identificadores).
• El espejo del catálogo de scopes pasa a 36 entradas con crm:clients:write:hierarchy.

La 2.17.0 (2026-07-02) añadió sdk.mcp.opportunities.listStages() / list_stages() para las etapas de oportunidad configurables por organización.

Cambios aditivos, sin breaking changes. Detalle completo en Endpoints de clientes del CRM.

Novedades de la versión 2.16.0, y por qué quedó rota

La 2.16.0 (5 de junio de 2026) añadió sdk.subscriptions y sdk.mandates envolviendo rutas internas de /finance/*, no la API externa.

Esas rutas exigen la sesión de un usuario del panel, que el SDK no sabe obtener: con clave de API devolvían 401 y con OAuth también, porque el token OAuth es opaco y solo se resuelve en el carril MCP. Hasta el 4 de agosto de 2026 esta página y los comentarios del SDK decían que bastaba con OAuth, y era falso.

Se arregló en la 3.0.0, que reescribe esos servicios sobre /external/v1/* con la clave de API. Si tu código quedó escrito contra la 2.16.0, revisa la tabla de rupturas de arriba: las firmas cambian.

Hitos por versión

Resumen de las versiones más relevantes de ambos SDK, de la rama 1.x a la actual. La numeración es compartida entre JavaScript y Python.

Los dos SDK admiten OAuth 2.1 con PKCE como alternativa a la clave de la aplicación. El parámetro theme para elegir tema claro u oscuro en la pantalla de consentimiento llegó en las versiones 1.8.0 (JavaScript) y 0.7.0 (Python). Ver OAuth con el SDK.

Catálogo de scopes de la API externa

El catálogo de scopes que una ExternalApp puede tener concedidos se expone en el endpoint:

La fuente de verdad es la lista EXTERNAL_API_SCOPES_LIST del backend, que tiene 61 permisos. Las cifras que aparecen en la tabla de hitos (35, 36, 40, 45, 56, 57) son el tamaño del catálogo en aquella versión, no el de hoy. El conteo canónico y su desglose viven en Catálogo de permisos de la API:

El cuarto scope del dominio Clientes es crm:clients:write:hierarchy (2.18.0): gestiona el vínculo matriz-filial de los grupos de empresas y se concede por separado del write genérico. El dominio Chat aporta nueve scopes con la plataforma de chat extensible: chat:messages:send (v1, publicar); chat:channels:view, chat:messages:view y chat:events:subscribe (v2: leer canales y mensajes, y recibir webhooks); chat:channels:create, chat:channels:manage y chat:members:manage (v3: crear, editar y archivar canales y gestionar sus miembros); y chat:agents:view y chat:agents:manage:external (v4: gestión de agentes de IA por apps). De todos ellos, solo chat:agents:manage:external exige SUPER_ADMIN y queda fuera de todo paquete.

Los scopes de gobierno del canal (v3) tienen ya sus métodos en sdk.chat: createChannel, updateChannel, archiveChannel, addMember y removeMember (en Python, en snake_case). La gestión de agentes de IA de la v4 (sdk.chat.agents) se documenta en Gestionar agentes de IA.

El cuarto scope de Analítica y telemetría es analytics:errors:manage (4.6.0): resolver, reabrir y silenciar los errores que ha enviado la propia aplicación. Los dos de Instalaciones del catálogo, apps:installations:read y apps:installations:exchange, llegan con la 4.7.0 y son de la aplicación que publica una ficha en el catálogo.

De esos 61 permisos, 17 solo puede concederlos un Super Administrador, con un motivo razonado de al menos veinte caracteres. Nueve lo son por datos personales críticos (contactos en derecho de oposición, notas internas de contactos, leads y clientes, conversión de leads, datos fiscales de clientes y de usuarios, envío de datos de tickets a proveedores de IA y verificación de firmas), uno por permitir que una aplicación gestione agentes de IA (chat:agents:manage:external) y siete por ser críticos financieros: billing:charge, billing:refund, billing:subscriptions:cancel, billing:payment-authorizations:write, billing:scheduled-charges:write (desde el 21 de octubre de 2026), crm:invoices:cancel y crm:invoices:rectify (4.3.0). crm:users:read:fiscal-data llegó con la 4.6.0.

La categoría de críticos financieros es nueva en la 3.0.0. Existe porque quien revisa la solicitud de una aplicación necesita saber por qué un permiso está blindado: no es lo mismo «leerá notas sobre personas» que «podrá cobrar y devolver dinero de tus clientes».

Cambio de catálogo en la 2.15.1. El scope fm:files:delete se retiró del catálogo porque ningún endpoint de la API externa lo aplicaba (no existe DELETE /external/v1/files/:id), de modo que concederlo generaba una falsa sensación de seguridad. Las aplicaciones que ya lo tuvieran concedido seguirán mostrándolo hasta que el operador lo retire desde el panel, pero nunca habilitó ninguna operación real. Volverá al catálogo cuando se exponga el endpoint correspondiente.

Política de compatibilidad

1. La API externa es estable en v1

   Todos los endpoints de la API externa viven bajo /external/v1. Mientras tu integración consuma esa versión, los contratos publicados se mantienen. Las novedades se añaden de forma aditiva.

2. Los SDK siguen versionado semántico

   La rama actual de ambos SDK es la 4.x. Los cambios menores (segundo número) añaden funcionalidad de forma compatible; los de parche (tercer número) corrigen o ajustan sin romper. Fija una versión mínima conocida y revisa el changelog antes de subir de versión menor.

3. Las retiradas se anuncian con antelación

   Los métodos que se van a eliminar se marcan primero como @deprecated y se mantienen durante una ventana de coexistencia antes de desaparecer en una versión mayor. Por ejemplo, generateSigningLink quedó obsoleto en favor de forceSendSignature: hoy lanza siempre un error que remite al método nuevo y se conserva solo para que el código antiguo compile.

4. Mantén SDK y backend alineados

   Algunas funcionalidades nuevas del SDK dependen de endpoints que deben existir en tu instancia de UTILIA OS. Si llamas a un método nuevo contra un backend más antiguo, recibirás un error de endpoint no encontrado. Actualiza ambos lados de forma coordinada.

Siguiente paso

• Instalar el SDKRequisitos e instalación en JavaScript y Python.
• Cambios de la APIRegistro completo de cambios del ecosistema de integración.