WooCommerce集成Broker ID遇认证及请求格式错误排查求助

问题背景 #

我编写了用于将Broker ID与WooCommerce集成的脚本，预期用户在商店完成购买后，自动启动Broker ID认证流程，并在订单感谢页获取并展示Broker ID链接。

初始脚本代码 #

page.add_action('woocommerce_before_thankyou', '');
function after_purchase_completed($order_id) {
    $order = wc_get_order($order_id);
    $process_id = 'AUT_' . $order->get_order_number() . '_' . uniqid();
    $data = array(
        'identification_channel_id' => '651d17427587d47324c683e3',
        'state' => $process_id,
    );
    
    $username = 'API Client';
    $password = 'API Key';
    $auth_token = base64_encode($username . ':' . $password);

    $response = wp_remote_post('http://i.broker.id/api/v1.0/oauth2/authorize', array(
        'headers' => array(
            'Content-Type' => 'application/json',
            'Authorization' => 'Basic ' . $auth_token
        ),
        'body' => json_encode($data)
    ));
    if (!is_wp_error($response)) {
        $response_code = wp_remote_retrieve_response_code($response);
        $response_body = wp_remote_retrieve_body($response);
        $error_message = '';
        if ($response_code !== 200) {
            $error_message = ' Error code: ' . $response_code . '. Error message: ' . $response_body;
        }
        $result = json_decode($response_body, true);
        if (isset($result['link'])) {
            echo '<p>URL: <a href="' . $result['link'] . '">' . $result['link'] . '</a></p>';
        } else {
            echo '<p>Sorry, the Broker ID authorization link could not be retrieved. Contact us for help.' . $error_message . '</p>';
        }
    } else {
        echo '<p>Sorry, there was a problem retrieving your Broker ID authorization link. Contact us for help.' . $error_message . '</p>';
    }
}

第一阶段错误：401未授权 #

替换正确的API Client和API Key后，仍返回错误：

抱歉，无法获取Broker ID授权链接。请联系我们寻求帮助。错误代码：401。错误信息：{"timestamp":"2024-05-05T15:00:53.172684169+02:00[Europe/Warsaw]","exceptionId":"bad.credentials","traceId":"66378305d5ef962325c0e06ec7ca4c97","errorCode":"66378305d5ef962325c0e06ec7ca4c97","message":"Bad Authorization"}

第二阶段错误：400请求参数错误 #

添加必填参数后，出现新的400错误，错误指向preliminary_verifications字段：
添加的参数片段：

$data = array(
        'identification_channel_id' => '651d17427587d47324c683e3', // 正确的身份验证渠道ID
        'state' => $process_id,
        'redirect_uri' => 'https://example.com/',
        'assertions' => array(
            array(
                'type' => 'PERSON_GIVEN_NAME',
                'value' => 'John'
            ),
            array(
                'type' => 'PERSON_FAMILY_NAME',
                'value' => 'Smith'
            ),
        ),
        'preliminary_verifications' => array(
            "PHONE_NUMBER",
            "EMAIL_ADDRESS"
        ),
        'identification_reason' => array(
            'pl' => 'W celu identyfikacji osoby na żądanie firmy X',
            'en' => 'In order to identify person on demand company X'
        ),
        'custom_consent_definitions' => array(
            array(
                'type' => 'CUSTOM_CONSENT_TYPE',
                'texts' => array(
                    'pl' => 'Treść zgody niestandardowej w języku polskim',
                    'en' => 'Custom consent content in English'
                )
            ),
        )
    );

返回错误：

抱歉，无法获取Broker ID授权链接。请联系我们寻求帮助。错误代码：400。错误信息：{"timestamp":"2024-05-05T16:55:22.646784829+02:00[Europe/Warsaw]","exceptionId":"bad.request","traceId":"66379ddaef08bd05c9ffb60e22ea9f20","errorCode":"66379ddaef08bd05c9ffb60e22ea9f20","message":"Bad request. Request body contains incorrect data."}

排查与解决方案 #

1. 修复401未授权错误 #

• 修正Action绑定：初始脚本第一行page.add_action('woocommerce_before_thankyou', '');存在语法错误，正确写法为add_action('woocommerce_before_thankyou', 'after_purchase_completed');，否则函数无法被WooCommerce触发。
• 改用HTTPS端点：API请求地址从http://i.broker.id改为https://i.broker.id，绝大多数API服务拒绝HTTP明文请求，这是导致401的常见原因。
• 确保Basic Auth编码正确：去除API凭证前后的空格，避免编码错误：

  $auth_token = base64_encode(trim($username) . ':' . trim($password));
  

• 核对凭证环境：确认API Client和Key对应当前使用的测试/生产环境，不同环境的凭证不通用。

2. 修复400请求参数错误（针对preliminary_verifications） #

• 核对枚举值：严格对照Broker ID的文档，preliminary_verifications的合法枚举值应为PHONE和EMAIL，而非PHONE_NUMBER、EMAIL_ADDRESS，这是错误的核心原因。
• 使用真实订单数据：将硬编码的John/Smith替换为订单中的真实用户信息，避免触发API的验证规则：

  $billing_first_name = $order->get_billing_first_name();
  $billing_last_name = $order->get_billing_last_name();
  

• 验证白名单：确保redirect_uri已在Broker ID后台添加到允许的重定向地址白名单中，未白名单的地址会被拒绝。
• 规范参数格式：所有多语言字段（如identification_reason）需确保包含文档要求的语言版本，避免格式缺失。

修正后的完整脚本 #

add_action('woocommerce_before_thankyou', 'after_purchase_completed');

function after_purchase_completed($order_id) {
    $order = wc_get_order($order_id);
    $process_id = 'AUT_' . $order->get_order_number() . '_' . uniqid();
    
    // 从订单获取真实用户信息
    $billing_first_name = $order->get_billing_first_name();
    $billing_last_name = $order->get_billing_last_name();

    $data = array(
        'identification_channel_id' => '651d17427587d47324c683e3',
        'state' => $process_id,
        'redirect_uri' => 'https://your-actual-domain.com/thank-you/', // 替换为你的真实重定向地址
        'assertions' => array(
            array(
                'type' => 'PERSON_GIVEN_NAME',
                'value' => $billing_first_name
            ),
            array(
                'type' => 'PERSON_FAMILY_NAME',
                'value' => $billing_last_name
            ),
        ),
        // 修正为文档规定的枚举值
        'preliminary_verifications' => array(
            "PHONE",
            "EMAIL"
        ),
        'identification_reason' => array(
            'pl' => 'W celu identyfikacji osoby po zakupie w sklepie',
            'en' => 'To identify the person after purchase in the store'
        ),
        'custom_consent_definitions' => array(
            array(
                'type' => 'CUSTOM_CONSENT_TYPE',
                'texts' => array(
                    'pl' => 'Zgadzam się na przetwarzanie moich danych osobowych w celu identyfikacji',
                    'en' => 'I consent to the processing of my personal data for identification purposes'
                )
            ),
        )
    );
    
    $username = '你的API Client';
    $password = '你的API Key';
    $auth_token = base64_encode(trim($username) . ':' . trim($password));

    // 使用HTTPS端点
    $response = wp_remote_post('https://i.broker.id/api/v1.0/oauth2/authorize', array(
        'headers' => array(
            'Content-Type' => 'application/json',
            'Authorization' => 'Basic ' . $auth_token
        ),
        'body' => json_encode($data),
        'sslverify' => true,
        'timeout' => 30
    ));
    
    if (!is_wp_error($response)) {
        $response_code = wp_remote_retrieve_response_code($response);
        $response_body = wp_remote_retrieve_body($response);
        $error_message = '';
        
        if ($response_code !== 200) {
            $error_message = ' 错误代码: ' . $response_code . '. 错误信息: ' . $response_body;
        }
        
        $result = json_decode($response_body, true);
        if (isset($result['link'])) {
            // 使用WordPress安全函数处理输出
            echo '<p>Broker ID认证链接: <a href="' . esc_url($result['link']) . '" target="_blank">' . esc_html($result['link']) . '</a></p>';
        } else {
            echo '<p>抱歉，无法获取Broker ID授权链接。请联系我们寻求帮助。' . $error_message . '</p>';
        }
    } else {
        echo '<p>抱歉，获取Broker ID授权链接时出现问题。请联系我们寻求帮助。</p>';
    }
}

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