Comparar arquivos Word programaticamente é uma necessidade frequente para serviços de backend que precisam detectar alterações, gerar relatórios de revisão ou aplicar políticas de documentos. GroupDocs.Comparison Cloud SDK for Node.js fornece uma API poderosa que simplifica essa tarefa para aplicações Node.js. Neste guia, você aprenderá como configurar o SDK, executar uma comparação completa de dois arquivos DOCX, usar comandos cURL equivalentes, entender cada parte da implementação e seguir recomendações de boas práticas para manter sua solução confiável e segura.

Exemplo de Código Completo: Comparar Documentos Word no Node.JS

O exemplo a seguir demonstra um fluxo de trabalho completo de ponta a ponta para comparar dois documentos Word usando o GroupDocs.Comparison Cloud SDK for Node.js.

const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

// ==== Authentication =========================================================
const clientId = "YOUR_CLIENT_ID";
const clientSecret = "YOUR_CLIENT_SECRET";

const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

// ==== File definitions =======================================================
const sourceFileName = "document1.docx";
const targetFileName = "document2.docx";
const resultFileName = "comparison_result.docx";

const sourceFilePath = path.resolve(__dirname, sourceFileName);
const targetFilePath = path.resolve(__dirname, targetFileName);

// ==== Main async function ====================================================
(async () => {
    try {
        // ---- Upload source document -----------------------------------------
        const sourceData = fs.readFileSync(sourceFilePath);
        const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: sourceFileName,
            file: sourceData
        });
        await storageApi.uploadFile(uploadSourceReq);

// ---- Upload target document -----------------------------------------
        const targetData = fs.readFileSync(targetFilePath);
        const uploadTargetReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: targetFileName,
            file: targetData
        });
        await storageApi.uploadFile(uploadTargetReq);

// ---- Prepare comparison options --------------------------------------
        const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
            sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
            targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
            outputPath: resultFileName,
            // optional: you can set settings like generateSummaryPage, showDeletedContent, etc.
        });

const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
            compareOptions: compareOptions
        });

// ---- Execute comparison -----------------------------------------------
        const compareResult = await compareApi.compareDocument(compareRequest);
        console.log("Comparison completed. Result stored at:", compareResult.path);

// ---- (Optional) Clean up uploaded files --------------------------------
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));
        // Note: result file remains in storage; you can download it if needed.
    } catch (error) {
        console.error("Error during comparison:", error);
    }
})();

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar quaisquer caminhos de arquivo e valores de configuração para corresponder ao seu ambiente real, verifique se todas as dependências necessárias estão corretamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter assistência.

Executar Comparação de Documentos com cURL e a API REST

Se você preferir uma abordagem independente de linguagem, pode obter o mesmo resultado com solicitações HTTP simples. Abaixo estão os comandos cURL essenciais.

  1. Autenticar e obter um token de acesso
    Substitua YOUR_CLIENT_ID e YOUR_CLIENT_SECRET pelas suas credenciais.
curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. Carregue o arquivo DOCX de origem
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document1.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document1.docx"
  1. Carregue o arquivo DOCX de destino
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document2.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document2.docx"
  1. Execute a operação de comparação
curl -X POST "https://api.groupdocs.cloud/v2.0/comparison/compare" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFile": { "filePath": "document1.docx" },
           "targetFiles": [{ "filePath": "document2.docx" }],
           "outputPath": "comparison_result.docx"
         }'
  1. Baixe o arquivo de comparação resultante
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/comparison_result.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o comparison_result.docx

Para obter mais detalhes sobre os payloads de solicitação e os formatos de resposta, consulte a documentação oficial da API.

Entendendo a Comparação de Documentos Word no Código Node.JS

Abaixo está uma análise passo a passo do exemplo completo:

  1. Importar SDK e módulos Node.js
const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

O namespace GroupDocsComparisonCloud fornece acesso a todas as classes da API.

  1. Criar configuração com credenciais do cliente
const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);

Este objeto autentica todas as chamadas subsequentes da API.

  1. Instanciar CompareApi e StorageApi
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

CompareApi lida com a comparação, enquanto StorageApi gerencia uploads e exclusões de arquivos. Consulte a referência da API para detalhes dos métodos.

  1. Carregar arquivos DOCX de origem e destino
const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
    path: sourceFileName,
    file: sourceData
});
await storageApi.uploadFile(uploadSourceReq);

O mesmo padrão é repetido para o arquivo de destino.

  1. Configure CompareOptions e execute a comparação
const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
    sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
    targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
    outputPath: resultFileName,
});
const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
    compareOptions: compareOptions
});
const compareResult = await compareApi.compareDocument(compareRequest);

CompareOptions permite que você ajuste finamente a operação (por exemplo, gerar uma página de resumo). O objeto de resultado contém o caminho para o documento de comparação gerado.

  1. Limpar arquivos temporários (opcional)
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));

Remover os originais enviados mantém o armazenamento organizado.

Pré-requisitos e Configuração para GroupDocs.Comparison

  1. Versão do Node.js - Certifique-se de que está executando o Node 14 ou superior.
  2. Obtenha credenciais do cliente - Registre‑se no portal GroupDocs Cloud para obter clientId e clientSecret.
  3. Instale o SDK
npm install groupdocs-comparison-cloud
  1. (Opcional) Baixe o projeto de exemplo - Você pode clonar o repositório a partir da página do GitHub.
  2. Configure seu ambiente - Defina as credenciais como variáveis de ambiente ou substitua os marcadores de posição no código.

Para obter uma lista completa de binários disponíveis para download, veja a página de download.

Melhores Práticas para Comparação Eficiente de Documentos Word

  • Validar arquivos de entrada - Verifique o tamanho e o formato do arquivo antes de fazer o upload para evitar chamadas de API desnecessárias.
  • Reutilizar sessões de armazenamento - Faça upload dos arquivos uma única vez e reutilize seus caminhos para várias comparações, reduzindo a latência.
  • Habilitar página de resumo somente quando necessário - Gerar uma página de resumo adiciona tempo de processamento; desative-a para verificações de diff simples.
  • Manipular documentos grandes de forma assíncrona - Para arquivos DOCX maiores que 10 MB, considere consultar o status do trabalho em vez de aguardar de forma síncrona.
  • Proteger credenciais - Armazene clientId e clientSecret em variáveis de ambiente ou em um gerenciador de segredos; nunca os codifique diretamente.

Conclusão

Comparar documentos Word no Node.JS torna‑se simples com o GroupDocs.Comparison Cloud SDK for Node.js. Seguindo as etapas de instalação, usando o exemplo de código fornecido e, opcionalmente, aproveitando a API REST com cURL, você pode integrar a comparação robusta de documentos em qualquer serviço backend. Lembre‑se de proteger suas credenciais, limpar arquivos temporários e ajustar as opções de comparação para desempenho. Para implantações em produção, você precisará de uma versão licenciada; detalhes de preços estão disponíveis na página do produto, e você pode obter uma licença temporária para avaliação na página de licença temporária. Comece a experimentar hoje e traga recursos confiáveis de diff de documentos para suas aplicações Node.js.

FAQs

  • Como comparar documentos Word no Node.JS sem escrever código?
    Você pode usar a mesma operação via chamadas REST. Os exemplos cURL neste artigo mostram a sequência exata: autenticar, enviar arquivos, chamar o endpoint de comparação e baixar o resultado.

  • Quais formatos de arquivo são suportados para comparação?
    O SDK suporta DOCX, DOC, ODT, RTF, e TXT entre outros. Todos os nomes de formato não diferenciam maiúsculas de minúsculas, mas são documentados em maiúsculas (por exemplo, DOCX) na referência da API.

  • Posso comparar mais de dois documentos de uma vez?
    Sim. O array targetFiles em CompareOptions pode conter vários objetos FileInfo, permitindo comparar um arquivo de origem com vários destinos em uma única solicitação.

  • Existe uma maneira de personalizar o estilo visual do resultado da comparação?
    O SDK oferece configurações como showDeletedContent, showInsertedContent e generateSummaryPage. Ajuste essas propriedades em CompareOptions para controlar como as alterações são destacadas. Consulte a documentação oficial para a lista completa de opções.

Leia Mais