Cómo integrar ONLYOFFICE Docs con una aplicación PHP personalizada

Comencemos con el límite de integración: una aplicación PHP personalizada no envía los bytes del documento directamente al editor. Su aplicación autentica al usuario, almacena el archivo, proporciona una URL que el servidor de ONLYOFFICE Docs puede obtener y expone un punto final de devolución de llamada donde Docs publica las actualizaciones guardadas. El navegador carga el script de la API de Docs y crea un editor en un elemento de la página. Este patrón funciona con un servidor Docs autohospedado cuando tanto el navegador como ambos servidores pueden acceder a las URL requeridas.

Nota importante sobre la versión: ONLYOFFICE anunció Docs 9.4 el 19 de mayo de 2026. El anuncio indica que la edición comunitaria de código abierto eliminó su anterior límite de 20 conexiones simultáneas a partir de la versión 9.4. Esto modifica una consideración de implementación para los usuarios de la edición comunitaria; sin embargo, no elimina la necesidad de almacenamiento accesible y puntos finales de devolución de llamada, firma JWT ni revisión de licencias. Consulte los términos de la versión y la licencia para la compilación exacta de Docs que planea implementar. La integración que se muestra a continuación sigue el flujo de la API de Docs documentada actualmente.

Las cuatro ilustraciones de pantalla son ejemplos conceptuales, no capturas de pantalla del producto. La lista de documentos y el diseño del proyecto PHP son específicos de la aplicación, y la interfaz del editor puede variar según la versión y la configuración de Docs.

Antes de conectar nada

Necesitas una aplicación PHP, un servidor ONLYOFFICE Docs y almacenamiento de documentos controlado por tu aplicación. Docs y la aplicación PHP pueden ejecutarse en hosts o contenedores separados. El navegador del usuario debe acceder al servidor Docs para descargar los recursos del editor. Por otro lado, el servidor Docs debe acceder a la URL del documento y a la URL de devolución de llamada de tu aplicación. Un nombre de host como este localhostsuele fallar en una configuración de contenedor porque apunta al contenedor que realiza la solicitud, no al otro servicio.

Utilice HTTPS para los puntos de acceso públicos, almacene su secreto JWT fuera del control de versiones y defina cómo se asignan los permisos de los documentos a los usuarios de su aplicación. Para el desarrollo local, puede ser necesario un túnel o red privada para que Docs pueda acceder a un archivo de desarrollo; en producción, utilice rutas estables y autenticadas. La guía oficial de instalación de Docker de ONLYOFFICE Docs explica la instalación y la configuración de JWT. Los secretos de ejemplo son solo eso: ejemplos; reemplácelos con un secreto privado y asegúrese de que sea coherente con la configuración de Docs.

Paso 1: Definir las rutas de los documentos y de la red.

Comience por poner el documento a disposición en una URL absoluta y estable que Docs pueda obtener. No dirija el editor a una ruta de sesión PHP ni a una URL relativa solo para navegadores. En su lugar, cree una ruta de aplicación autenticada, como https://app.example.com/docs/42/download. Antes de devolver bytes, esa ruta debe verificar el acceso del usuario autenticado al documento 42. Si el servidor de Docs no puede reutilizar la sesión del navegador del usuario, emita una URL de descarga temporal y con ámbito, u otro mecanismo de autorización de servidor a servidor.

También crea una ruta de devolución de llamada, como por ejemplo https://app.example.com/onlyoffice/callback?document=42. Debe aceptar una solicitud POST del servidor de Docs, identificar el archivo de destino de forma segura y ser accesible desde la red del servidor de Docs. El parámetro URL que Docs envía es un enlace de descarga temporal para el documento editado; no es el archivo guardado en tu base de datos. Tu devolución de llamada debe recuperar esos bytes y escribirlos en tu almacenamiento.

ONLYOFFICE describe el editor y el servicio de almacenamiento de documentos como componentes separados: Docs proporciona el servicio de edición, mientras que el integrador proporciona el gestor y el almacenamiento de documentos. Consulte la descripción general oficial de «Cómo funciona» antes de elegir su dispositivo y el diseño de su red.

Paso 2: Cree la configuración del editor en PHP.

Para un documento de Word, la configuración identifica el tipo de archivo de origen, una clave única, el título, la URL de descarga, el modo de edición y la URL de devolución de llamada. La clave es importante: permite a Docs identificar la sesión de edición y reutilizar un documento almacenado en caché. Genere una clave nueva cuando el archivo se haya editado y guardado; reutilice la misma clave para los clientes que deban unirse a la misma sesión de documento activa. Mantenga la clave dentro de los límites de caracteres y longitud documentados.

El siguiente ejemplo asume el uso de Composer y la biblioteca Firebase PHP-JWT. Reemplace cada URL y búsqueda de almacenamiento de ejemplo con sus propios servicios que admitan autorización.

<?php
use Firebase\JWT\JWT;

$document = $documents->findForUser($documentId, $currentUser);

$config = [
    'document' => [
        'fileType' => 'docx',
        'key' => $document->editingKey(),
        'title' => $document->filename(),
        'url' => $document->docsDownloadUrl(),
        'permissions' => [
            'edit' => true,
        ],
    ],
    'documentType' => 'word',
    'editorConfig' => [
        'mode' => 'edit',
        'callbackUrl' => $document->callbackUrl(),
        'user' => [
            'id' => (string) $currentUser->id(),
            'name' => $currentUser->displayName(),
        ],
    ],
];

$config['token'] = JWT::encode($config, $onlyOfficeJwtSecret, 'HS256');

El archivo document.urldebe ser legible por el servidor de Docs, no solo por el navegador. document.keyDebe registrar una revisión guardada: si se reutiliza una clave obsoleta después de que cambie el archivo fuente, Docs podría abrir contenido almacenado en caché. El token es un JSON Web Token (JWT) firmado, un formato estándar para demostrar que la configuración proviene de un servidor que contiene el secreto compartido. El secreto de firma permanece en el servidor PHP; nunca lo incluya en JavaScript ni en HTML.

Los nombres en clave docsDownloadUrl(), callbackUrl(), y editingKey()son métodos de aplicación, no funciones PHP integradas de ONLYOFFICE. La implementación exacta depende de su sistema de almacenamiento, marco web y modelo de control de acceso. ONLYOFFICE publica un SDK de integración PHP oficial y ejemplos en varios idiomas, pero el repositorio describe explícitamente sus aplicaciones de demostración como ejemplos de prueba que necesitan cambios para producción. Consulte la guía oficial de firmas JWT y los ejemplos de integración oficiales .

Paso 3: Cargar la API de Docs y renderizar el editor.

Renderiza la configuración firmada en la página solo después de que la ruta PHP haya autorizado al usuario. Escapa el JSON para un contexto JavaScript y haz que el contenedor del editor tenga la altura suficiente para que sea utilizable. El navegador obtiene los datos api.jsde tu servidor Docs; el constructor reemplaza el elemento de marcador de posición con un iframe del editor.

<div id="onlyoffice-editor" style="width:100%;height:900px"></div>
<script src="https://docs.example.com/web-apps/apps/api/documents/api.js"></script>
<script>
  const config = /* safely encoded JSON rendered by PHP */;
  const editor = new DocsAPI.DocEditor('onlyoffice-editor', config);
</script>

Las etiquetas anteriores se muestran como código de ejemplo con caracteres escapados para que puedan interpretarse como código. En tu página real, carga el script de la API desde la URL del servidor Docs que aloja tu editor. Si el área del editor está en blanco, primero verifica que el navegador pueda abrir esa URL, que la aplicación y Docs utilicen certificados HTTPS compatibles y que las herramientas para desarrolladores del navegador no muestren solicitudes de red o de contenido mixto bloqueadas. La documentación de DocsAPI.DocEditor explica el comportamiento de los marcadores de posición y los iframes.

Paso 4: Guardar las actualizaciones mediante la función de devolución de llamada.

Cuando finaliza la edición, Docs envía una solicitud POST a editorConfig.callbackUrl. El statusvalor determina qué debe hacer su controlador. El estado 2 significa que el documento está listo para guardarse después de que finalice la edición. El estado 6 significa que el estado actual se ha guardado mediante una operación de guardado forzado mientras la sesión de edición puede continuar. Otros valores indican estados de conexión, sin cambios o de error; no trate cada devolución de llamada como un archivo nuevo.

Un controlador de devolución de llamada debe analizar el cuerpo JSON, validar la solicitud según la configuración de la bandeja de salida JWT habilitada en su servidor Docs, asignar la devolución de llamada a un documento que la integración actual posee y manejar los estados de guardado de manera específica. En estado 2 o 6, descargue el publicado urldesde el servidor Docs, verifique que la descarga se haya realizado correctamente y reemplace el archivo almacenado de forma atómica para que una descarga parcial no pueda corromper el original. Devuelva la respuesta de devolución de llamada esperada por la API actual, normalmente un objeto JSON con errorestablecido en 0después del procesamiento exitoso.

<?php
$payload = json_decode(file_get_contents('php://input'), true);

// Verify the callback token as configured for your Docs server.
// Resolve the document from your own database; do not trust a user-supplied path.
$status = (int) ($payload['status'] ?? 0);

if (in_array($status, [2, 6], true) && !empty($payload['url'])) {
    $file = $storage->downloadFromDocs($payload['url']);
    $storage->replaceAtomically($document, $file);
}

header('Content-Type: application/json');
echo json_encode(['error' => 0]);

downloadFromDocs()y replaceAtomically()son marcadores de posición, no rutinas de producción completas. Utilice un cliente HTTP con tiempos de espera, verificación TLS, límites de tamaño de respuesta y destinos de salida controlados; no acceda a una URL arbitraria sin medidas de seguridad. Compruebe la firma/token de la devolución de llamada utilizando el método documentado para la versión exacta de Docs y la configuración que esté utilizando. La referencia oficial del controlador de devolución de llamada enumera los estados y cuándo está presente la URL del archivo editado.

Prueba la ruta de guardado completa

1. Abra un archivo DOCX pequeño como un usuario que tenga permiso para editarlo.
2. Realice un cambio visible, espere a que el editor indique que se ha guardado y cierre el documento.
3. Inspeccione los registros de PHP y Docs. Confirme que la llamada de retorno se recibió y que su ruta de almacenamiento descargó el archivo devuelto.
4. Vuelva a abrir el archivo desde la aplicación y confirme que el cambio persiste. Pruebe por separado a cerrar el archivo sin cambios y a usar un segundo editor simultáneo.

La guía oficial de guardado indica que, en la mayoría de los casos, el guardado se completa unos 10 segundos después de finalizar la edición; el tamaño del archivo, su complejidad, el tiempo de conversión y el rendimiento del servidor pueden afectar la demora. No informe al usuario que el archivo se ha guardado solo porque se haya cerrado el iframe del editor; verifique la función de devolución de llamada y la revisión almacenada.

Fallos comunes de integración

• El editor se abre, pero no puede cargar el archivo: realice la prueba document.urldesde la red del servidor de Docs, no solo desde el navegador de su ordenador.
• JWT rechazado: compare la clave secreta y la configuración HS256 en ambos lados; confirme que el token firma el objeto de configuración exacto que se está enviando.
• Los cambios desaparecen: compruebe la accesibilidad de la devolución de llamada, el manejo del estado, la obtención de la URL de descarga temporal y los permisos de reemplazo de archivos.
• Aparece la versión antigua: emita una nueva clave de documento después de una revisión guardada y evite servir URL de origen almacenadas en caché de forma involuntaria.
• Funciona localmente, pero falla en producción: inspeccione las rutas del proxy inverso, los certificados TLS, el DNS del contenedor, las reglas del firewall y el nombre de host público frente al interno utilizado en cada URL.

Este es el procedimiento principal para integrar ONLYOFFICE Docs con una aplicación PHP personalizada: autorizar y servir el archivo fuente, firmar la configuración del editor por documento, renderizar el editor API oficial y, a continuación, procesar de forma segura las devoluciones de llamada para guardar. Los detalles de producción (autenticación, almacenamiento, firma de URL, verificación de devoluciones de llamada y política de concurrencia) deben coincidir con su aplicación y la versión exacta de Docs que implemente.