Como configurar as ferramentas de desenvolvedor no ONLYOFFICE Apps

Ferramentas de desenvolvedor

A seção Ferramentas de desenvolvedor é usada para integrar, estender e automatizar o ONLYOFFICE Docs e o Apps: conecte os editores à sua própria plataforma com o Docs Connect, integre o ONLYOFFICE Apps em sua própria aplicação web com o Embed SDK, use o Plugin SDK, webhooks, adicione aplicações OAuth e chaves de API.

A página Visão geral é aberta por padrão. Ela lista todas as ferramentas de desenvolvedor disponíveis com uma breve descrição de cada uma. Clique no link do cartão correspondente para começar.

Por padrão, o acesso à seção Ferramentas de desenvolvedor está habilitado para todos os usuários, exceto convidados, para que qualquer usuário possa acessar esta página, criar seus próprios webhooks ou suas próprias aplicações OAuth 2.0, etc. Se você deseja tornar a página de Ferramentas de desenvolvedor acessível apenas ao proprietário do espaço de trabalho e aos administradores, desative a configuração da seção Ferramentas de desenvolvedor na seção Segurança.

Docs Connect

A seção Docs Connect permite executar o mecanismo de edição de documentos do ONLYOFFICE na nuvem e incorporá-lo ao seu próprio produto. Em vez de instalar e manter o ONLYOFFICE Docs em seu próprio servidor, você cria uma instância hospedada para você, que fornece aos seus usuários os editores de documentos, planilhas, apresentações e PDF.

A instância não depende de um armazenamento específico: ela pode ser vinculada às plataformas que você já usa por meio de conectores prontos, ou à sua própria aplicação por meio da API. Uma única instância pode atender várias plataformas ao mesmo tempo, portanto não é necessário criar uma separada para cada integração.

O Dev Pack amplia a instância com a Automation API para automatizar ações nos editores e com as opções de marca que permitem substituir a marca padrão pela sua. Use o link Ler a documentação da API para abrir a documentação do desenvolvedor com os detalhes da integração.

A instância pode ser testada gratuitamente por 30 dias, com os recursos do Dev Pack incluídos e sem necessidade de dados de pagamento. Para criar sua primeira instância, clique no botão Iniciar teste gratuito de 30 dias.

observação

O Docs Connect também pode ser ativado na seção Cobrança -> Complementos.

Depois que a instância é criada, as guias Estatísticas, Configurações e Visualização ficam disponíveis. Enquanto o teste está em andamento, o número de dias gratuitos restantes é exibido ao lado do título Docs Connect. Use o botão Assinar para mudar para uma assinatura paga antes que o teste expire.

Use o ícone de opções ao lado do título Docs Connect para copiar a chave secreta, atualizar a assinatura ou visualizar o histórico de transações.

Estatísticas

A guia Estatísticas exibe as informações sobre a sua instância:

• Visão geral do sistema - o Endereço, o Cabeçalho JWT e a Chave secreta da instância. Use os ícones correspondentes para copiar os valores ou para mostrar a chave secreta oculta.
• Licença - a data de início da licença, a data até a qual a licença é válida e o número de dias restantes.
• Build - o tipo de build, a versão e a data de lançamento.
• Atividade dos usuários no último mês - a atividade de usuários únicos para Editores (editores de documentos com permissões totais) e Live Viewer (visualizadores de documentos somente leitura). Para cada um deles, são exibidos o uso, bem como o número de usuários ativos, internos, externos e restantes.

Clique no botão Baixar relatório para baixar o relatório de atividade dos usuários.

Configurações

A guia Configurações permite configurar a sua instância. Na seção Geral, as seguintes configurações estão disponíveis:

• Cabeçalho JWT, Chave secreta - visualize ou altere o cabeçalho JWT e a chave secreta. Use os ícones correspondentes para mostrar a chave secreta oculta ou copiá-la.
• WOPI - ative o alternador Ativar protocolo WOPI para permitir integrações com provedores de armazenamento compatíveis com WOPI.
• Suporte anônimo - selecione Sim para permitir que usuários sem autenticação acessem os documentos, ou Não se somente usuários autenticados puderem acessar os documentos.
• Limites de tamanho de arquivo - especifique o número máximo de bytes que podem ser baixados para o processamento de documentos (por exemplo, 104857600 = 100 MB).

Clique no botão Salvar para aplicar as alterações ou no botão Cancelar para descartá-las.

A seção Filtragem de IP permite configurar as Regras de acesso que definem quais endereços podem acessar a sua instância. Cada regra permite ou nega o acesso para um endereço IP, um intervalo de IP ou um host, e é listada com o seu tipo e valor.

observação

Por padrão, a lista contém uma única regra Permitir com o valor *, que permite o acesso a partir de qualquer endereço.

Clique no botão Adicionar regra para adicionar uma nova regra. Para excluir uma única regra, use o ícone correspondente à direita.

Para remover todas as regras de uma vez, clique no botão Redefinir e confirme a ação na janela Redefinir regras de acesso que se abre. Todas as regras de permissão e negação são excluídas permanentemente, e o acesso é permitido a partir de qualquer endereço IP até que você adicione novas regras.

Visualização

A guia Visualização permite verificar como os editores funcionam:

• Editor - abra um documento de exemplo no editor incorporado. Durante o período de teste, o editor é aberto no modo de teste.
• Código de demonstração - visualize o código de exemplo para incorporar o editor com o endereço e a configuração da sua instância. Use o ícone correspondente para copiar o código.

Embed SDK

Use o SDK do ONLYOFFICE Apps baseado em JavaScript, que permite aos desenvolvedores utilizar todas as possibilidades do ONLYOFFICE Apps com o api.js. Você pode integrar o ONLYOFFICE Apps em sua própria aplicação web, permitindo que os usuários criem e enviem documentos diretamente do seu site. Para saber mais sobre o uso do Embed SDK, leia este guia

Para mais detalhes sobre o Embed SDK, consulte api.onlyoffice.com.

Plugin SDK

Use o Plugin SDK para ampliar a funcionalidade do seu espaço de trabalho, conectar serviços de terceiros ou aprimorar a experiência do usuário com recursos personalizados. A página do Plugin SDK também oferece uma coleção de exemplos de plugins prontos com o código-fonte disponível no GitHub.

Para começar a criar seu próprio plugin, use o link Leia as instruções na página do Plugin SDK para acessar um guia passo a passo.

observação

Os plugins de exemplo não são habilitados automaticamente. Acesse a página Plugins para habilitá-los no seu espaço de trabalho.

Exemplos de plugins

A seção Exemplos de plugins lista os plugins com suporte oficial. Para cada plugin, são exibidos a sua versão e uma breve descrição. Clique no botão Ir para o repositório no cartão correspondente para abrir o seu código-fonte no GitHub. Os seguintes plugins estão disponíveis:

• codemirror — visualizar e editar arquivos com código de programação em uma ampla variedade de formatos.
• markdown — visualizar, editar e criar arquivos Markdown (.md) diretamente no seu espaço de trabalho.
• convert-to-markdown — converter arquivos DOCX, TXT e HTML para o formato Markdown sem sair do seu espaço de trabalho.
• zip-archives — abrir e extrair arquivos ZIP armazenados no seu espaço de trabalho.
• speech-to-text — transcrever áudio em texto usando reconhecimento de voz diretamente no seu espaço de trabalho.
• pdf-converter — converter documentos, planilhas, apresentações e formulários para o formato PDF.
• url — criar, editar e abrir arquivos URL com links externos a partir da lista de arquivos.
• book-reader — abrir os arquivos compatíveis em um visualizador de leitura dedicado em tela cheia.
• draw.io — criar e editar diagramas usando a ferramenta de diagramas draw.io.
• image-editor — editar imagens diretamente no seu espaço de trabalho.

Recursos dos plugins

Os plugins criados com o Plugin SDK podem usar os seguintes recursos:

• Localização — os plugins oferecem suporte a vários idiomas por meio do mecanismo de localização integrado.
• Personalização com CSS — aplique estilos personalizados à interface do seu plugin usando CSS padrão.
• Ações do menu de grupo — adicione ações personalizadas ao menu de seleção de grupo para arquivos, pastas e salas.
• Seletores personalizados — exiba os seletores integrados do espaço de trabalho (básico, arquivo, sala, grupos, usuários) dentro do seu plugin.
• Botão de ação flutuante — adicione operações personalizadas com ícones personalizados ao botão de ação flutuante, incluindo indicador de progresso.
• Slots da barra lateral — coloque os pontos de entrada do plugin na barra lateral usando ícones de 32×32 px. Há até 5 slots disponíveis.
• Ações do menu de contexto — exiba ações específicas do plugin no menu de contexto de um arquivo, pasta ou sala específicos.
• Integração com o visualizador de mídia — incorpore seu plugin diretamente no visualizador de mídia integrado.
• Componentes de interface — use os componentes integrados IconButton e Link para manter uma aparência consistente.

Para mais detalhes sobre o Plugin SDK, consulte api.onlyoffice.com.

Webhooks

Use webhooks para realizar ações personalizadas no lado de qualquer aplicação ou site que você esteja usando com base em vários eventos no ONLYOFFICE Apps. Você pode criar e gerenciar todos os seus webhooks, configurá-los e navegar no histórico de cada webhook para auditar seu desempenho. Para saber mais sobre o uso de webhooks, leia este guia.

Para criar um webhook, clique no botão Criar webhook e preencha o formulário:

• Nome do webhook - especifique o nome do webhook.
• URL de payload - especifique a URL para a qual o payload do webhook será enviado.
• Chave secreta - insira a chave secreta ou use o link Gerar para criá-la automaticamente.
• Verificação SSL - selecione a opção Ativar verificação SSL ou a opção Desativar (não recomendado).
• Evento que aciona este webhook - selecione a opção Enviar tudo, ou Eventos individuais para especificar somente os eventos necessários.
• ID de destino - especifique o ID de destino.

Clique no botão Criar.

Para mais detalhes sobre a API do Apps, consulte api.onlyoffice.com.

OAuth 2.0

Use o OAuth 2.0 para acessar a API do ONLYOFFICE Apps para autorização e outras ações, como o acesso a arquivos, etc.

Para criar uma nova aplicação:

1. Clique no botão Registrar uma nova aplicação. A página Nova aplicação é aberta;

   

2. Preencha a seção Informações básicas:

   • Nome do aplicativo – um nome de aplicação que será exibido em todas as telas de consentimento e na lista de aplicações. Parâmetro obrigatório;
   • URL do site – um link para a página inicial do site. Parâmetro obrigatório;
   • Ícone do aplicativo – uma imagem que será exibida em todas as telas de consentimento e na lista de aplicações. Use a opção Selecionar nova imagem para carregar um arquivo JPG, PNG ou SVG de 32x32. Parâmetro obrigatório;
   • Descrição – uma breve descrição da aplicação;
   • Método de autenticação – um método de verificação ao receber um token JWT. Para receber um token, é necessário enviar a chave SHA. Marque a caixa Permitir cliente público (PKCE) se necessário.

3. Preencha a seção URLs do OAuth:

   • URLs de redirecionamento – links para os quais o usuário pode ser redirecionado após passar com sucesso pela tela de consentimento. Insira o endereço e clique no botão de mais. Você pode adicionar vários links, por exemplo, para versões de teste e produção. Parâmetro obrigatório;
   • Origens permitidas – URLs de fontes que podem fazer solicitações à API do Apps sem bloqueio CORS. Insira o endereço e clique no botão de mais. Você pode adicionar vários links. Parâmetro obrigatório.

4. Na seção Escopos de acesso, defina as capacidades de uma aplicação de terceiros em relação à API do Apps. Os escopos são usados para limitar o acesso do seu aplicativo a todos os dados relacionados ao usuário, e eles permitem que você especifique exatamente que tipo de acesso você precisa. Marque a caixa Ler ou Escrever ao lado das opções necessárias. Ao selecionar uma capacidade para escrever dados, automaticamente habilita a leitura de dados. Parâmetro obrigatório;

   

   • Perfil – accounts.self:read para visualizar informações básicas do seu perfil, accounts.self:write para visualizar e gerenciar informações básicas do seu perfil;
   • Contatos – accounts:read para visualizar todos os contatos, accounts:write para visualizar e gerenciar todos os contatos;
   • Salas – rooms:read para visualizar todas as salas, rooms:write para visualizar e gerenciar todas as salas;
   • Arquivos e Pastas – files:read para visualizar todos os arquivos e pastas, files:write para visualizar e gerenciar todos os arquivos e pastas;
   • Open ID – openid para visualizar seus dados pessoais. Este escopo está disponível somente para leitura.

5. Preencha a seção Suporte e informações legais:

   • URL da política de privacidade – um link URL para sua Política de Privacidade que deve cumprir as leis e regulamentos aplicáveis e que esclareça como você coleta, usa, compartilha, retém e processa informações pessoais. Parâmetro obrigatório;
   • URL dos Termos de Serviço – um link URL para seus Termos e Condições que os usuários devem cumprir ao usar esta aplicação. Parâmetro obrigatório.

6. Clique no botão Salvar.

Você pode gerenciar suas aplicações criadas na lista:

• Visualizar informações sobre sua aplicação: nome do aplicativo, criador, data de modificação, escopos;
• Desativar ou ativar a aplicação usando o alternador de Estado;
• Clique com o botão direito na aplicação e selecione a opção necessária:
  • Editar – para alterar alguns parâmetros, como Nome do aplicativo, Ícone do aplicativo, Descrição, Método de autenticação. Nesta página, você também pode copiar o ID do Cliente e o Segredo ou redefinir o segredo, se necessário;
  • Botão de autenticação – para visualizar o botão de autorização, copiar o código HTML, CSS ou JavaScript para incorporá-lo em seu site, obter um link de autorização ou verificador de código. Ao clicar no botão de autorização, você também pode passar por todo o fluxo;
  • Informações – para visualizar as informações da aplicação, como criador, descrição, site, acesso, escopos, suporte e informações legais, última data de modificação;
  • Gerar token – para gerar um token para desenvolvimento (para não passar pelo fluxo a cada vez). O token gerado tem um tempo de vida limitado e será automaticamente desativado quando um novo for criado;
  • Revogar token – para revogar o token gerado;
  • Desativar – para desativar a aplicação e interromper todas as sessões ativas;
  • Excluir – para excluir a aplicação e interromper e remover todas as sessões ativas.

Ao seguir o link de autorização, há 3 cenários possíveis:

1. Se o usuário ainda não estiver autorizado no espaço de trabalho, o formulário de autorização será aberto. Após a autorização bem-sucedida, o usuário será redirecionado para o passo 2 ou 3;
2. Se o usuário tiver mais de um espaço de trabalho, será possível selecionar o necessário;
3. Se o usuário já estiver autorizado no espaço de trabalho, ele será redirecionado para a página de consentimento, que exibe as capacidades da aplicação, links para a política de segurança e termos de serviço. O usuário pode clicar no botão Permitir ou Negar, bem como escolher outro perfil.

Para mais detalhes sobre a API do Apps, consulte api.onlyoffice.com.

Chaves de API

Como proprietário ou administrador, você pode visualizar e gerenciar todas as chaves de API deste espaço de trabalho. Para saber mais, use o link Ler o guia da API.

observação

Mantenha suas chaves de API privadas – não as compartilhe nem as exponha no navegador ou em outro código do lado do cliente.

Para criar uma nova chave de API:

1. Clique no botão Criar nova chave secreta;
2. Preencha o formulário:

   • Nome – Especifique o nome da chave secreta;

   • Permissões – Selecione a opção necessária:

     • Todas – Habilitar permissões de leitura e escrita para todas as seções;

       

     • Restrito – Habilitar permissões de leitura ou escrita para certas seções. Na lista Escopos de acesso, marque a caixa Ler ou Escrever ao lado das opções necessárias: Arquivos e Pastas, Salas, Perfil, Contatos. Ao selecionar uma capacidade para escrever dados, automaticamente habilita a leitura de dados. O botão Gerar fica ativo somente depois que pelo menos um escopo de acesso é selecionado;

       

     • Apenas leitura – Habilitar permissões apenas de leitura para todas as seções.

       

   • Tempo de vida da chave – Ative este alternador para desativar automaticamente a chave secreta após um período definido e, em seguida, especifique o número de Dias (365 no máximo). O tempo de vida começa no momento em que a chave é criada.

3. Clique no botão Gerar;
4. Em uma nova janela, copie a chave gerada e clique em Concluído.

Você pode gerenciar suas chaves de API criadas na lista:

• Visualizar informações sobre sua chave: Nome, Chave secreta, Criada, Último uso, Criada por, Permissões;
• Desativar ou ativar a chave usando o interruptor Estado;
• Clique com o botão direito na chave ou use o ícone de opções à direita e selecione a opção necessária:
  • Editar – para alterar o Nome e as Permissões da chave;
  • Excluir – para excluir a chave.

Para mais detalhes sobre a API do Apps, consulte api.onlyoffice.com.