Como integrar o ONLYOFFICE Docs com um aplicativo PHP personalizado

Comecemos pela fronteira de integração: uma aplicação PHP personalizada não envia bytes do documento diretamente para o editor. Sua aplicação autentica o usuário, armazena o arquivo, fornece uma URL que o servidor ONLYOFFICE Docs pode buscar e expõe um endpoint de retorno de chamada onde o Docs envia as atualizações de salvamento. O navegador carrega o script da API do Docs e cria um editor em um elemento da página. Esse padrão funciona com um servidor Docs auto-hospedado quando o navegador e ambos os servidores conseguem acessar as URLs necessárias.

Nota importante sobre a versão: A ONLYOFFICE anunciou o Docs 9.4 em 19 de maio de 2026. O anúncio informa que a Community Edition de código aberto removeu o limite anterior de 20 conexões simultâneas a partir da versão 9.4. Isso altera uma consideração de implantação para usuários da Community Edition; não elimina a necessidade de armazenamento acessível e endpoints de retorno de chamada, assinatura JWT ou revisão de licenciamento. Verifique os termos de lançamento e licença da versão exata do Docs que você planeja implantar. A integração abaixo segue o fluxo da API do Docs documentado atualmente.

As quatro ilustrações de tela são exemplos conceituais, não capturas de tela reais do produto. A lista de documentos e o layout do projeto PHP são específicos da aplicação, e a interface do editor pode variar de acordo com a versão e configuração do Docs.

Antes de conectar qualquer coisa

Você precisa de um aplicativo PHP, um servidor ONLYOFFICE Docs e um armazenamento de documentos controlado pelo seu aplicativo. O Docs e o aplicativo PHP podem ser executados em hosts ou contêineres separados. O navegador do usuário precisa acessar o servidor Docs para baixar os recursos do editor. Separadamente, o servidor Docs precisa acessar a URL do documento e a URL de retorno de chamada do seu aplicativo. Um nome de host como `https://` localhostgeralmente falha em uma configuração de contêiner porque aponta de volta para o contêiner que faz a solicitação, e não para o outro serviço.

Use HTTPS para endpoints públicos, mantenha seu segredo JWT fora do controle de versão e defina como as permissões de documentos são mapeadas para os usuários do seu aplicativo. Para desenvolvimento local, uma rede privada ou um túnel pode ser necessário para que o Docs possa buscar um arquivo de desenvolvimento; em produção, devem ser usadas rotas estáveis ​​e autenticadas. O guia oficial de instalação do Docker do ONLYOFFICE Docs explica a instalação e a configuração do JWT. Os segredos de exemplo são apenas ilustrativos — substitua-os por um segredo privado e mantenha-o consistente com a sua configuração do Docs.

Etapa 1: Defina as rotas de documentos e de rede.

Comece disponibilizando o documento em uma URL absoluta e estável que o Docs possa acessar. Não direcione o editor para um caminho de sessão PHP ou uma URL relativa exclusiva do navegador. Em vez disso, crie uma rota de aplicativo autenticada, como `/ https://app.example.com/docs/42/downloaddocument.php`. Antes de retornar bytes, essa rota deve verificar o acesso do usuário autenticado ao documento 42. Se o servidor do Docs não puder reutilizar a sessão do navegador do usuário, forneça uma URL de download com escopo limitado e de curta duração ou utilize outro mecanismo de autorização servidor para servidor.

Crie também uma rota de retorno de chamada, como por exemplo: `/` https://app.example.com/onlyoffice/callback?document=42. Ela deve aceitar uma requisição POST do servidor Docs, identificar o arquivo de destino com segurança e ser acessível a partir da rede do servidor Docs. O parâmetro da URL que o Docs retorna é um link temporário para download do documento editado; não é o arquivo salvo no seu banco de dados. Sua rota de retorno de chamada deve buscar esses bytes e gravá-los no seu armazenamento.

A ONLYOFFICE descreve o editor e o serviço de armazenamento de documentos como componentes separados: o Docs fornece o serviço de edição, enquanto o integrador fornece o gerenciador e o armazenamento de documentos. Consulte a visão geral oficial "Como funciona" antes de escolher seu endpoint e projeto de rede.

Etapa 2: Criar a configuração do editor em PHP

Para um documento do Word, a configuração identifica o tipo de arquivo de origem, uma chave de documento exclusiva, o título, o URL para download, o modo de edição e o URL de retorno de chamada. A chave é importante: ela permite que o Docs identifique a sessão de edição e reutilize um documento em cache. Gere uma nova chave quando o arquivo for editado e salvo; reutilize a mesma chave para clientes que devem acessar a mesma sessão de documento ativa. Mantenha a chave dentro dos limites de caracteres e comprimento documentados.

O exemplo abaixo pressupõe o uso do Composer e da biblioteca Firebase PHP-JWT. Substitua todos os exemplos de URL e consultas de armazenamento pelos seus próprios serviços com suporte à autorização.

<?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');

O token document.urldeve ser legível pelo servidor de documentação, não apenas pelo navegador. Ele document.keydeve rastrear uma revisão salva: se você reutilizar uma chave obsoleta após alterações no arquivo de origem, a documentação poderá abrir conteúdo em cache. O token é um JSON Web Token (JWT) assinado, um formato padrão para comprovar que a configuração veio de um servidor que detém o segredo compartilhado. O segredo de assinatura permanece no servidor PHP; nunca o coloque em JavaScript ou HTML.

Os nomes de código `onlyoffice.jwt` docsDownloadUrl(), callbackUrl()`onlyoffice.jwt` e ` editingKey()onlyoffice.jwt` são métodos de aplicação, não funções PHP integradas do ONLYOFFICE. A implementação exata depende do seu sistema de armazenamento, framework web e modelo de controle de acesso. O ONLYOFFICE publica um SDK de integração PHP oficial e exemplos multilíngues, mas o repositório descreve explicitamente seus aplicativos de demonstração como exemplos de teste que precisam de alterações para produção. Consulte o guia oficial de assinatura JWT e os exemplos de integração oficiais .

Etapa 3: Carregue a API de Documentação e renderize o editor.

Exiba a configuração assinada na página somente após a rota PHP ter autorizado o usuário. Escape o JSON para um contexto JavaScript e defina a altura do contêiner do editor para que seja utilizável. O navegador busca os dados api.jsno servidor de documentação; o construtor substitui o elemento de espaço reservado por um iframe do 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>

As tags acima são mostradas como exemplos de marcação escapada para que possam ser lidas como código. Na sua página real, carregue o script da API a partir da URL do servidor Docs que hospeda seu editor. Se a área do editor estiver em branco, primeiro confirme se o navegador consegue abrir essa URL, se o aplicativo e o Docs usam certificados HTTPS compatíveis e se as ferramentas de desenvolvedor do navegador não mostram nenhum conteúdo misto ou solicitação de rede bloqueada. A documentação do DocsAPI.DocEditor explica o comportamento do espaço reservado e do iframe.

Etapa 4: Salvar atualizações por meio do retorno de chamada

Quando a edição termina, o Docs envia um POST para editorConfig.callbackUrl. O statusvalor determina o que seu manipulador deve fazer. O status 2 significa que o documento está pronto para ser salvo após o fechamento da edição. O status 6 significa que o estado atual foi salvo por meio de uma operação de salvamento forçado, enquanto a sessão de edição pode continuar. Outros valores indicam estados de conexão, sem alterações ou erro; não trate cada retorno de chamada como um novo arquivo.

Um manipulador de retorno de chamada deve analisar o corpo JSON, validar a solicitação de acordo com as configurações de caixa de saída JWT habilitadas no seu servidor Docs, mapear o retorno de chamada para um documento pertencente à integração atual e lidar com os estados de salvamento de forma deliberada. No status 2 ou 6, faça o download do documento enviado urldo servidor Docs, verifique se o download foi bem-sucedido e substitua o arquivo armazenado atomicamente, de forma que um download parcial não corrompa o original. Retorne a resposta de retorno de chamada esperada pela API atual, normalmente um objeto JSON com o errorvalor definido como verdadeiro 0após o processamento bem-sucedido.

<?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()e replaceAtomically()são espaços reservados, não rotinas de produção completas. Use um cliente HTTP com tempos limite, verificação TLS, limites de tamanho de resposta e destinos de saída controlados; não busque uma URL arbitrária sem salvaguardas. Verifique a assinatura/token do retorno de chamada usando o método documentado para a versão e configuração exatas da documentação que você está executando. A referência oficial do manipulador de retorno de chamada lista os status e indica quando a URL do arquivo editado está presente.

Teste o caminho de salvamento completo

1. Abra um arquivo DOCX pequeno como um usuário que tenha permissão para editá-lo.
2. Faça uma alteração visível, aguarde até que o editor indique que ela foi salva e feche o documento.
3. Inspecione os logs do PHP e do Docs. Confirme se o callback chegou e se sua rota de armazenamento baixou o arquivo retornado.
4. Reabra o arquivo no aplicativo e confirme se a alteração persiste. Teste fechar o arquivo sem alterações e, em seguida, usar um segundo editor simultaneamente.

O guia oficial de fluxo de salvamento observa que, na maioria dos casos, o salvamento é concluído cerca de 10 segundos após o término da edição; o tamanho do arquivo, a complexidade, o tempo de conversão e o desempenho do servidor podem afetar o atraso. Não informe ao usuário que o arquivo foi salvo apenas porque o iframe do editor foi fechado — verifique o retorno de chamada e a revisão armazenada.

Falhas comuns de integração

• O editor abre, mas não consegue carregar o arquivo: teste document.urla partir da rede do servidor de documentação, não apenas do navegador do seu computador.
• JWT rejeitado: compare o segredo e a configuração HS256 em ambos os lados; confirme se o token assina o objeto de configuração exato que está sendo enviado.
• As alterações desaparecem: verificação de acessibilidade de retorno de chamada, tratamento de status, busca de URL de download temporário e permissões de substituição de arquivo.
• A versão antiga reaparece: emita uma nova chave de documento após uma revisão salva e evite servir URLs de origem em cache involuntariamente.
• Funciona localmente, mas falha em produção: inspecione os caminhos do proxy reverso, os certificados TLS, o DNS do contêiner, as regras do firewall e o nome do host público versus o interno usado em cada URL.

Este é o caminho principal para integrar o ONLYOFFICE Docs com um aplicativo PHP personalizado: autorizar e disponibilizar o arquivo de origem, assinar uma configuração de editor por documento, renderizar o editor da API oficial e, em seguida, processar com segurança os retornos de chamada de salvamento. Os detalhes de produção — autenticação, armazenamento, assinatura de URL, verificação de retorno de chamada e política de concorrência — devem corresponder ao seu próprio aplicativo e à versão exata do Docs que você implantar.