使用DocuSign REST API设置复选框为必填项失败问题排查

我尝试将复选框标记为必填项，但始终无法生效。发送信封后这些字段仍处于可选状态。我参考了相关示例但问题仍未解决，到底哪里出错了？

我已添加了Tab Group，以下是部分JSON代码：

tabs: class Tabs {
        approveTabs: null
        checkboxTabs: [class Checkbox {
            anchorAllowWhiteSpaceInCharacters: null
            anchorAllowWhiteSpaceInCharactersMetadata: null
            anchorCaseSensitive: null
            anchorCaseSensitiveMetadata: null
            anchorHorizontalAlignment: null
            anchorHorizontalAlignmentMetadata: null
            anchorIgnoreIfNotPresent: true
            anchorIgnoreIfNotPresentMetadata: null
            anchorMatchWholeWord: null
            anchorMatchWholeWordMetadata: null
            anchorString: /cbx_1_1/
            anchorStringMetadata: null
            anchorTabProcessorVersion: null
            anchorTabProcessorVersionMetadata: null
            anchorUnits: pixels
            anchorUnitsMetadata: null
            anchorYOffset: null
            anchorYOffsetMetadata: null
            boldMetadata: null
            conditionalParentLabel: null
            conditionalParentLabelMetadata: null
            conditionalParentValue: on
            conditionalParentValueMetadata: null
            customTabId: null
            customTabIdMetadata: null
            documentId: 1
            mergeFieldXml: null
            name: Salario Pro/Labore
            nameMetadata: null
            originalValue: null
            pageNumber: null
            pageNumberMetadata: null
            recipientId: 1
            recipientIdGuid: null
            recipientIdGuidMetadata: null
            recipientIdMetadata: null
            required: null
            requiredMetadata: null
            requireInitialOnSharedChange: null
            requireInitialOnSharedChangeMetadata: null
            selected: false
            selectedMetadata: null
            source: null
            status: null
            statusMetadata: null
            tabGroupLabels: [checkbox group]
            tabGroupLabelsMetadata: null
            tabId: /cbx_1_1/
            tabIdMetadata: null
            tabLabel: Salario Pro/Labore
        }

my tabgrop:

    tabGroups: [class TabGroup {
                anchorAllowWhiteSpaceInCharacters: null
                anchorAllowWhiteSpaceInCharactersMetadata: null
                anchorCaseSensitive: null
                anchorCaseSensitiveMetadata: null
                anchorHorizontalAlignment: null
                anchorHorizontalAlignmentMetadata: null
                anchorIgnoreIfNotPresent: null
                anchorIgnoreIfNotPresentMetadata: null
                anchorMatchWholeWord: null
                anchorMatchWholeWordMetadata: null
                anchorString: null
                anchorStringMetadata: null
                anchorTabProcessorVersion: null
                anchorTabProcessorVersionMetadata: null
                anchorUnits: null
                anchorUnitsMetadata: null
                anchorXOffset: null
                anchorXOffsetMetadata: null
                anchorYOffset: null
                anchorYOffsetMetadata: null
                conditionalParentLabel: null
                conditionalParentLabelMetadata: null
                conditionalParentValue: null
                conditionalParentValueMetadata: null
                customTabId: null
                customTabIdMetadata: null
                documentId: null
                documentIdMetadata: null
                errorDetails: null
                formOrder: null
                formOrderMetadata: null
                formPageLabel: null
                formPageLabelMetadata: null
                formPageNumber: null
                formPageNumberMetadata: null
                groupLabel: checkbox group
                groupLabelMetadata: null
                groupRule: SelectAtLeast
                groupRuleMetadata: null
                height: null
                heightMetadata: null
                maximumAllowed: 50
                maximumAllowedMetadata: null
                mergeField: null
                mergeFieldXml: null
                minimumRequired: 50
                minimumRequiredMetadata: null
                pageNumber: null
                pageNumberMetadata: null
                recipientId: null
                recipientIdGuid: null
                recipientIdGuidMetadata: null
                recipientIdMetadata: null
                smartContractInformation: null
                source: null
                status: null
                statusMetadata: null
                tabGroupLabels: null
                tabGroupLabelsMetadata: null
                tabId: null
                tabIdMetadata: null
                tabOrder: null
                tabOrderMetadata: null
                tabScope: document
                tabScopeMetadata: null
                tabType: null
                tabTypeMetadata: null
                templateLocked: null
                templateLockedMetadata: null
                templateRequired: null
                templateRequiredMetadata: null
                tooltip: null
                toolTipMetadata: null
                validationMessage: Please check to indicate your agreement
                validationMessageMetadata: null
                width: null
                widthMetadata: null
                xPosition: null
                xPositionMetadata: null
                yPosition: null
                yPositionMetadata: null
}]

Java调用代码：

List<Tabs> tabs = this.getCheckbox(numProposta, rs.getString("seq_envelope"));
for(Tabs t : tabs ){
    signerTabs.setCheckboxTabs(t.getCheckboxTabs());
    signerTabs.setTabGroups(t.getTabGroups());
}

private List<Tabs> getCheckbox(String numProposta, String seq_envelope) throws Exception {
String GET_CHECKBOXES =
        "SELECT eac.cd_envelope, " +
                "       eac.seq_envelope, " +
                "       eac.seq_arq_env, " +
                "       eac.tag, " +
                "       eac.ds_valor, " +
                "       eac.cd_arquivo, " +
                "       eac.cd_checkbox, " +
                "       eac.is_checked " +
                "  FROM envelope_assinatura_checkbox eac " +
                " WHERE eac.cd_envelope = ? " +
                "   AND eac.seq_envelope = ? ";

PreparedStatement ps = connection.getConnection().prepareStatement(GET_CHECKBOXES);
List<Checkbox> checkboxList = new ArrayList<>();
List<String> tabGroupLabels1 = Arrays.asList("checkbox");
List<TabGroup> tabGroups = new ArrayList<>();
List<Tabs> tabsList = new ArrayList<>();

ps.setString(1, numProposta);
ps.setString(2, seq_envelope);
ResultSet rs = ps.executeQuery();
while (rs.next()) {
    Checkbox checkboxTab1 = new Checkbox();
    checkboxTab1.setAnchorString(rs.getString("tag").trim());
    checkboxTab1.setName(rs.getString("ds_valor"));
    checkboxTab1.setRecipientId(rs.getString("seq_envelope"));
    checkboxTab1.setTabLabel(rs.getString("ds_valor"));
    checkboxTab1.setTabId(rs.getString("tag").trim());
    checkboxTab1.setSelected(rs.getBoolean("is_checked") ? "true" : "false");
    checkboxTab1.setRequired("true");  // Tornando o checkbox obrigatório
    checkboxTab1.setAnchorUnits("pixels");
    checkboxTab1.setAnchorIgnoreIfNotPresent("true");
    checkboxTab1.documentId(rs.getString("seq_envelope"));
    checkboxTab1.setTabGroupLabels(tabGroupLabels1);
    checkboxList.add(checkboxTab1);
}

TabGroup tabGroup1 = new TabGroup();
tabGroup1.setGroupLabel("checkbox");
tabGroup1.setGroupRule("SelectAtLeast");
tabGroup1.setMinimumRequired("1"); // Requer pelo menos 1 checkbox selecionado
tabGroup1.setMaximumAllowed("1"); // Limita a 1 checkbox selecionado
tabGroup1.tabScope("document");
tabGroup1.setValidationMessage("Por favor, selecione pelo menos um checkbox.");

tabGroups.add(tabGroup1);
Tabs tabs = new Tabs();
tabs.setCheckboxTabs(checkboxList);
tabs.setTabGroups(tabGroups);
tabsList.add(tabs);
return tabsList;
}

问题分析与修复方案 #

1. 必填字段赋值类型错误

从JSON输出可以看到required: null，说明Java代码里的setRequired("true")没有正确生效。DocuSign SDK的Checkbox类中required属性是布尔类型，而非字符串。传递字符串"true"会导致序列化失败，最终API请求中该字段缺失。

修复：

// 替换字符串赋值为布尔值
checkboxTab1.setRequired(true);

2. Tab Group标签不匹配

你的复选框tabGroupLabels设置为["checkbox"]，但Tab Group的groupLabel是"checkbox group"，两者标签不一致，导致复选框无法被关联到分组，分组的必填规则自然不会生效。

修复：

// 确保分组标签和复选框的分组标签一致
tabGroup1.setGroupLabel("checkbox");

3. Tab Group的必填数量配置矛盾

JSON中Tab Group的minimumRequired: 50，但Java代码里设置的是1，这说明配置没有正确同步。如果实际只有1个复选框，要求选至少50个显然不合理，会导致规则失效。

修复：
确保Java代码中minimumRequired的数值符合实际复选框数量，并且检查SDK是否需要传递数值类型而非字符串：

// 如果SDK支持数值类型，直接传整数
tabGroup1.setMinimumRequired(1);
tabGroup1.setMaximumAllowed(1);

4. DocumentId赋值错误

你将documentId设置为seq_envelope的值，但documentId应该对应信封内文档的ID（通常是"1"、"2"这类标识文档顺序的字符串/整数），错误的ID会导致复选框无法绑定到正确文档，规则失效。

修复：

// 替换为实际文档的ID，比如第一个文档传"1"
checkboxTab1.setDocumentId("1");

5. Selected字段赋值类型错误

同样，selected属性应为布尔类型，传递字符串"true"/"false"会导致序列化问题。

修复：

// 直接传递布尔值
checkboxTab1.setSelected(rs.getBoolean("is_checked"));

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