如何通过Java向HelloSign模板签名请求填充签名者图片？

业务场景 #

我在HelloSign平台存储了一份文档，需要先预填充部分数据后发送给签名者，同时要将数据库中的签名者图片填充到文档指定的“Picture”区域。

已完成操作 #

已编写Java代码创建TemplateSignatureRequest并发送模板签名请求，代码如下：

TemplateSignatureRequest request = new TemplateSignatureRequest();
request.setTitle(title);
request.setSubject(emailSubject);
request.setMessage(message);
request.setSigner("ROLE", "<<email_id>>", name);
request.setClientId(CLIENT_ID);
request.setTemplateId(TEMPLATE_ID);
request.setTestMode(true);
request.setCustomFields(customFields);
HelloSignClient client = new HelloSignClient(API_KEY);
client.sendTemplateSignatureRequest(request);

问题说明 #

是否可以通过类似request.setDocuments(docs);的方式直接在请求对象中填充图片？或者有其他可行的实现方法？

注意：无法在HelloSign上将图片区域标记为自定义字段，目标区域如下：

解决方案 #

关于request.setDocuments(docs)的可行性 #

request.setDocuments(docs)方法不可行，该方法的作用是向签名请求中添加全新的文档文件，而非填充现有模板内已指定的图片区域。

可行实现方案 #

方案1：预先生成带图片的PDF，替换原模板后发起请求

1. 从数据库读取签名者的图片文件；
2. 使用Java PDF处理库（如Apache PDFBox、iText）将图片插入到原始模板PDF的“Picture”指定坐标位置；
3. 将修改后的PDF上传至HelloSign，替换原模板或直接作为新文档使用；
4. 基于修改后的文档创建并发送签名请求。

示例代码（Apache PDFBox插入图片）：

// 加载原始模板PDF
PDDocument document = PDDocument.load(new File("original_template.pdf"));
PDPage targetPage = document.getPage(0); // 假设目标区域在第一页
PDImageXObject signerImage = PDImageXObject.createFromFile("signer_picture.png", document);
PDPageContentStream contentStream = new PDPageContentStream(document, targetPage, PDPageContentStream.AppendMode.APPEND, true);

// 根据模板内“Picture”区域的实际坐标调整x、y、宽高参数
float x = 120;
float y = 480;
float imgWidth = 140;
float imgHeight = 140;
contentStream.drawImage(signerImage, x, y, imgWidth, imgHeight);

contentStream.close();
document.save("pre_filled_template.pdf");
document.close();

// 后续将修改后的PDF上传至HelloSign，获取新的模板ID或直接作为文档发起签名请求

方案2：调整模板配置后使用自定义字段预填充（若后续可修改模板）

如果之后允许修改HelloSign模板配置，可将“Picture”区域设置为图片类型的自定义字段，然后通过customFields传入图片的Base64编码实现预填充：

List<CustomField> customFields = new ArrayList<>();
CustomField pictureField = new CustomField();
pictureField.setName("Picture");
pictureField.setType("image");

// 将图片文件转换为Base64字符串
byte[] imageBytes = Files.readAllBytes(Paths.get("signer_picture.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
pictureField.setValue(base64Image);

customFields.add(pictureField);
request.setCustomFields(customFields);

但由于当前无法标记该区域为自定义字段，此方案暂时无法使用。

内容的提问来源于stack exchange，提问作者FAIZAN