使用Telegram Stars(XTR)发发票失败，API提示providerToken不能为空

问题描述 #

我基于最新版Java SDK开发Kotlin Telegram机器人，尝试通过Telegram内部货币Stars（XTR）发送发票。根据Telegram官方文档，只需指定currency="XTR"且providerToken=""即可创建Stars发票，但操作后Telegram API抛出TelegramApiValidationException，提示providerToken参数不能为空。不想配置外部支付提供商获取令牌，请问：

1. 是否有人遇到过该错误？
2. 如何解决此问题？

相关代码：

fun invoice(
        chatId: String,
        text: String,
        starsAmount: Int,
        isFlexible: Boolean = true
    ) = SendInvoice.builder()
        .chatId(chatId)
        .title(text)
        .description("Пожертвование")
        .prices(listOf(LabeledPrice.builder().label("Пожертвование").amount(starsAmount).build()))
        .currency("XTR")
        .providerToken("")
        .payload("test")
        .startParameter("")
        .build()
}

问题解答 #

1. 是否有人遇到过该错误？ #

是的，不少使用Java/Telegram Bots SDK开发Stars发票的开发者都碰到过这个问题。核心原因是SDK内部的校验逻辑和Telegram官方API规则不匹配：官方API允许providerToken传空字符串，但SDK的校验代码会强制要求该参数非空，从而触发异常。

2. 如何解决此问题？ #

直接跳过providerToken参数的设置即可。SDK在检测到使用XTR作为货币时，会自动适配Stars发票的逻辑，无需手动传入空值。

修正后的代码如下：

fun invoice(
        chatId: String,
        text: String,
        starsAmount: Int,
        isFlexible: Boolean = true
    ) = SendInvoice.builder()
        .chatId(chatId)
        .title(text)
        .description("Пожертвование")
        .prices(listOf(LabeledPrice.builder().label("Пожертвование").amount(starsAmount).build()))
        .currency("XTR")
        .payload("test")
        .startParameter("")
        .build()
}

额外注意事项：

• 确保你的Java SDK是v6.7.0及以上版本，旧版本未适配Stars发票的特殊逻辑；
• starsAmount的单位是微Stars，比如要收取1 Stars，需要传入1000000，直接传整数1实际仅会收取0.000001 Stars，这点要严格匹配Telegram官方的金额规则。

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