Adicionar marca d'água de imagem a documentos PDF em Java

Adicionar um identificador visual a arquivos PDF é essencial para proteger a propriedade intelectual e marcar documentos. GroupDocs.Watermark Cloud SDK for Java oferece uma API simples para incorporar marcas d’água de imagem diretamente em PDFs a partir da sua aplicação Java. Neste tutorial, você aprenderá como adicionar marca d’água de imagem a documentos PDF em Java, verá um exemplo completo em funcionamento e explorará as chamadas REST equivalentes em cURL para integração na nuvem.

Adicionar Marca d’água de Imagem a Documentos PDF em Java em 5 Etapas

Inicializar o cliente da API: Crie uma instância ApiClient com seu ID de cliente e segredo.

ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(apiClient);

Esta etapa conecta seu código Java ao serviço GroupDocs.Watermark Cloud. Consulte a referência da API para mais detalhes.

Especifique o arquivo PDF de origem: Crie um objeto FileInfo que aponta para o PDF que você deseja marcar com marca d’água.

FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("input.pdf");

O arquivo deve ser enviado para o seu armazenamento GroupDocs antes da solicitação.

Configure a marca d’água de imagem: Defina o caminho da imagem, opacidade, fator de escala, rotação e alinhamento.

ImageWatermark imageWatermark = new ImageWatermark();
imageWatermark.setImagePath("watermark.png");
imageWatermark.setOpacity(0.5);
imageWatermark.setScaleFactor(0.3);
imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
imageWatermark.setMargin(new Margin(10, 10, 10, 10));

Ajuste esses valores para obter a aparência desejada; a opacidade controla a transparência, enquanto o scaleFactor determina o tamanho relativo à página.

Defina as opções de marca d’água e o caminho de saída: Combine as informações do arquivo e a marca d’água em um objeto WatermarkOptions.
```
WatermarkOptions options = new WatermarkOptions();
options.setFileInfo(fileInfo);
options.setImageWatermark(imageWatermark);
options.setOutputPath("output.pdf");
```
O outputPath indica ao serviço onde armazenar o PDF resultante.
Execute a solicitação: Crie um AddWatermarkRequest e chame a API. Trate respostas de sucesso ou erro.

AddWatermarkRequest request = new AddWatermarkRequest(options);
try {
    AddWatermarkResponse response = watermarkApi.addWatermark(request);
    System.out.println("Watermark added successfully. Output file: " + response.getPath());
} catch (Exception e) {
    System.err.println("Error adding watermark: " + e.getMessage());
}

Após a execução, o PDF com marca d’água está disponível no local que você especificou.

Exemplo de Código Completo: Adicionar Marca d’água de Imagem a Documentos PDF em Java

O exemplo a seguir demonstra a implementação completa, desde a inicialização do cliente até a gravação do PDF com marca‑d’água.

import com.groupdocs.cloud.watermark.api.WatermarkApi;
import com.groupdocs.cloud.watermark.client.ApiClient;
import com.groupdocs.cloud.watermark.model.AddWatermarkRequest;
import com.groupdocs.cloud.watermark.model.AddWatermarkResponse;
import com.groupdocs.cloud.watermark.model.FileInfo;
import com.groupdocs.cloud.watermark.model.ImageWatermark;
import com.groupdocs.cloud.watermark.model.Margin;
import com.groupdocs.cloud.watermark.model.WatermarkOptions;
import com.groupdocs.cloud.watermark.model.enums.HorizontalAlignment;
import com.groupdocs.cloud.watermark.model.enums.VerticalAlignment;

public class AddImageWatermarkExample {
    public static void main(String[] args) {
        // Initialize API client (replace with your actual credentials)
        ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
        WatermarkApi watermarkApi = new WatermarkApi(apiClient);

// Input PDF file information
        FileInfo fileInfo = new FileInfo();
        fileInfo.setFilePath("input.pdf");

// Image watermark configuration
        ImageWatermark imageWatermark = new ImageWatermark();
        imageWatermark.setImagePath("watermark.png");          // Path to watermark image
        imageWatermark.setOpacity(0.5);                        // 50% opacity
        imageWatermark.setScaleFactor(0.3);                    // 30% of page size
        imageWatermark.setRotationAngle(0);                    // No rotation
        imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
        imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
        imageWatermark.setMargin(new Margin(10, 10, 10, 10));  // 10 points margin on all sides

// Watermark options
        WatermarkOptions options = new WatermarkOptions();
        options.setFileInfo(fileInfo);
        options.setImageWatermark(imageWatermark);
        options.setOutputPath("output.pdf"); // Resulting PDF with watermark

// Create request and call API
        AddWatermarkRequest request = new AddWatermarkRequest(options);
        try {
            AddWatermarkResponse response = watermarkApi.addWatermark(request);
            System.out.println("Watermark added successfully. Output file: " + response.getPath());
        } catch (Exception e) {
            System.err.println("Error adding watermark: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar os caminhos dos arquivos (input.pdf, watermark.png, output.pdf) para corresponderem às suas localizações reais, 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.

Aplicar Marca d’Água de Imagem em Documentos PDF via cURL e API REST

Abaixo estão as chamadas REST que você pode usar com cURL para obter o mesmo resultado sem escrever código Java.

Obtenha um token de acesso

curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

A resposta contém um access_token usado nas chamadas subsequentes.

Carregue o PDF de origem

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/input.pdf"

Carregue a imagem da marca d’água

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=watermark.png" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/watermark.png"

Adicionar a marca d’água de imagem

curl -X POST "https://api.groupdocs.cloud/v2.0/watermark/add" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfo": { "filePath": "input.pdf" },
           "imageWatermark": {
               "imagePath": "watermark.png",
               "opacity": 0.5,
               "scaleFactor": 0.3,
               "horizontalAlignment": "Center",
               "verticalAlignment": "Center",
               "margin": { "top": 10, "right": 10, "bottom": 10, "left": 10 }
           },
           "outputPath": "output.pdf"
         }'

Esta solicitação reflete a lógica do código Java, aplicando as mesmas configurações de opacidade, escala e alinhamento.

Baixe o PDF com marca d’água

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download?path=output.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.pdf

Para mais detalhes sobre os corpos de solicitação e parâmetros suportados, veja a documentação oficial da API.

Instalando e Configurando GroupDocs.Watermark Cloud SDK for Java

Adicione a dependência Maven ao seu pom.xml (ou o trecho equivalente do Gradle). A biblioteca está hospedada no Maven Central.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-watermark-cloud</artifactId>
    <version>23.8</version>
</dependency>

Você também precisa de uma conta válida do GroupDocs Cloud. Recupere seu Client ID e Client Secret no portal do GroupDocs. Nenhuma instalação adicional de tempo de execução é necessária porque o SDK se comunica com o serviço em nuvem.

Ajuste fino das opções de marca d’água de imagem para documentos PDF

O SDK expõe várias propriedades que permitem controlar a aparência visual da marca d’água.

Ajustar Opacidade

imageWatermark.setOpacity(0.75); // 75% opacity for a more visible watermark

Os valores de opacidade variam de 0.0 (totalmente transparente) a 1.0 (totalmente opaco).

Alterar Fator de Escala

imageWatermark.setScaleFactor(0.5); // Watermark occupies 50% of the page width

O fator de escala determina o tamanho da marca d’água em relação às dimensões da página.

Definir alinhamento e margens

imageWatermark.setHorizontalAlignment(HorizontalAlignment.RIGHT);
imageWatermark.setVerticalAlignment(VerticalAlignment.BOTTOM);
imageWatermark.setMargin(new Margin(20, 20, 20, 20));

Essas configurações posicionam a marca d’água no canto inferior direito com uma margem de 20 pontos.

Para obter uma lista completa de propriedades configuráveis, consulte a referência da API.

Conclusão

Adicionar uma marca d’água de imagem a documentos PDF em Java é uma tarefa simples quando você usa o GroupDocs.Watermark Cloud SDK for Java. O SDK lida com toda a manipulação de PDF de baixo nível, permitindo que você se concentre nos aspectos visuais, como opacidade, dimensionamento e posicionamento. Seja qual for a sua preferência por uma implementação Java nativa ou um fluxo de trabalho baseado em cURL na nuvem, os mesmos resultados de alta qualidade são alcançáveis sem sacrificar o desempenho. Lembre‑se de obter uma licença adequada para uso em produção; detalhes de preços estão disponíveis na página do produto e uma página de licença temporária pode ser usada para avaliação.

Perguntas Frequentes

Como adiciono marca d’água de imagem a um PDF em Java sem perder qualidade?
Use a propriedade scaleFactor para dimensionar a marca d’água em relação à página e manter o DPI original do PDF de origem. O SDK preserva a resolução do PDF, de modo que a marca d’água permanece nítida em qualquer nível de zoom.
Posso adicionar várias marcas d’água ao mesmo PDF?
Sim. Crie objetos ImageWatermark separados com configurações diferentes e adicione‑os sequencialmente chamando addWatermark várias vezes ou adicionando‑os a uma lista na solicitação.
Quais são os formatos de imagem suportados para a marca d’água?
A API aceita tipos de imagem comuns, como PNG, JPG, BMP, GIF e TIFF. PNG é recomendado para qualidade sem perdas e suporte a transparência.
Existe uma maneira de visualizar a marca d’água antes de aplicá‑la?
Você pode usar o GroupDocs.Watermark Cloud SDK for Java para gerar um PDF temporário com a marca d’água e baixá‑lo para revisão. Isso usa a mesma chamada addWatermark com um caminho de saída apontando para um local temporário.

Adicionar Marca d’água de Imagem a Documentos PDF em Java em 5 Etapas#

Exemplo de Código Completo: Adicionar Marca d’água de Imagem a Documentos PDF em Java#

Aplicar Marca d’Água de Imagem em Documentos PDF via cURL e API REST#

Instalando e Configurando GroupDocs.Watermark Cloud SDK for Java#

Ajuste fino das opções de marca d’água de imagem para documentos PDF#

Ajustar Opacidade#

Alterar Fator de Escala#

Definir alinhamento e margens#

Conclusão#

Perguntas Frequentes#

Read More#