如何通过QuickBooks Online PHP SDK将发票标记为已付？

直接修改Balance字段是行不通的——QuickBooks Online的发票状态是通过创建关联的付款记录来更新的，而不是手动修改余额。因为你是用纸质支票收款，只需要在QBO里创建一笔对应发票的付款，系统就会自动把发票标记为已付，同时清零余额。

下面是具体的实现步骤和代码示例：

核心思路 #

要标记发票已付，你需要创建一个Payment对象，将其关联到目标发票上，指定付款金额、付款方式（比如Check）以及交易日期等信息。当这笔付款被成功创建后，QBO会自动关联发票并更新它的状态和余额。

代码示例 #

假设你已经有了要标记已付的发票ID（比如从之前创建发票的返回结果中获取$invoice->Id），可以用以下代码创建付款：

use QuickBooksOnline\API\DataService\DataService;
use QuickBooksOnline\API\Facades\Payment;
use QuickBooksOnline\API\Data\IPPLinkedTxn;

// 初始化DataService（这里假设你已经完成了SDK的配置，和创建发票时的配置一致）
$dataService = DataService::Configure([
    'auth_mode' => 'oauth2',
    'ClientID' => "YOUR_CLIENT_ID",
    'ClientSecret' => "YOUR_CLIENT_SECRET",
    'accessTokenKey' => "YOUR_ACCESS_TOKEN",
    'refreshTokenKey' => "YOUR_REFRESH_TOKEN",
    'QBORealmID' => "YOUR_REALM_ID",
    'baseUrl' => "https://sandbox-quickbooks.api.intuit.com" // 生产环境换成正式环境url
]);

// 要标记已付的发票ID
$invoiceId = "YOUR_INVOICE_ID";
// 发票的总金额（确保和发票的Total字段完全一致）
$paymentAmount = 100.00;

// 创建LinkedTxn对象，关联到目标发票
$linkedTxn = new IPPLinkedTxn();
$linkedTxn->TxnId = $invoiceId;
$linkedTxn->TxnType = "Invoice";

// 创建Payment对象
$payment = Payment::create([
    "TotalAmt" => $paymentAmount,
    "CustomerRef" => [
        "value" => "YOUR_CUSTOMER_ID" // 必须和发票的CustomerRef保持一致
    ],
    "PaymentRefNum" => "CHECK-123", // 纸质支票的编号，可选但建议填写方便记账
    "PaymentMethodRef" => [
        "value" => "CHECK" // 付款方式为支票，需确保QBO账号已配置该付款方式，也可使用对应ID
    ],
    "LinkedTxn" => [$linkedTxn],
    "TxnDate" => date("Y-m-d") // 付款日期，按需调整
]);

// 提交付款到QBO
$result = $dataService->Add($payment);

// 检查操作结果
if ($dataService->getLastError() == null) {
    echo "付款已创建成功，发票已标记为已付！付款ID: " . $result->Id;
} else {
    echo "创建付款失败: " . $dataService->getLastError()->getResponseBody();
}

关键注意事项 #

• 付款金额必须匹配发票总金额：如果只付了部分金额，发票会显示部分已付；只有全额付款才会被标记为完全已付。
• 付款方式要准确：PaymentMethodRef的值可以是QBO中付款方式的名称（比如"CHECK"）或者对应的ID，确保你的QBO账号里已配置该付款方式。
• 关联发票要精准：LinkedTxn必须正确设置发票ID和类型，否则付款无法关联到目标发票，发票状态也不会更新。
• 客户Ref需一致：付款的CustomerRef必须和发票的CustomerRef完全相同，否则会触发QBO的校验报错。

这样操作后，你就能在QBO后台看到发票状态变为已付，余额自动清零，完全满足你的记账需求。

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