PHP接入Walmart退货API：流程与参数全解析

本教程详细阐述如何使用PHP cURL集成Walmart Returns API，包括获取访问令牌和执行退货查询的完整流程。文章重点讲解了API请求中关键头信息（如`WM_QOS.CORRELATION_ID`）的正确生成方式，纠正了常见的`MD5`误用，并提供了示例代码和错误排查指南，旨在帮助开发者顺利完成API对接。

Walmart Returns API 集成指南

Walmart Returns API 为商家提供了一种程序化方式来管理和查询其在 Walmart Marketplace 上的退货信息。本文将详细介绍如何利用 PHP cURL 实现与该 API 的集成，并着重解决在请求过程中可能遇到的常见认证和请求格式问题。

与大多数 RESTful API 类似，Walmart API 的交互通常包括两个核心步骤：首先通过认证服务获取一个有效的访问令牌（Access Token），然后使用此令牌对实际的业务 API（如 Returns API）发起请求。

步骤一：获取访问令牌 (Access Token)

在调用任何 Walmart 业务 API 之前，您必须先获取一个访问令牌。此令牌是进行后续授权请求的凭证。

1.1 API 端点与请求方法

• API 端点: https://marketplace.walmartapis.com/v3/token
• HTTP 方法: POST
• 请求体 (Request Body): grant_type=client_credentials

1.2 必要的请求头 (Headers)

以下是获取访问令牌时必须包含的 HTTP 请求头：

• Authorization: 采用 HTTP Basic 认证。将您的 Client ID 和 Secret Key 以 Client_ID:Secret_Key 格式拼接后进行 Base64 编码，然后以 Basic {Base64编码字符串} 的形式发送。
• WM_SVC.NAME: Walmart Marketplace。这是一个固定值，用于标识服务。
• WM_QOS.CORRELATION_ID: 一个全局唯一标识符 (GUID)。这是确保请求唯一性和可追踪性的关键参数，也是许多请求失败的常见原因。
• Content-Type: application/x-www-form-urlencoded。

1.3 WM_QOS.CORRELATION_ID 的正确生成方式

重要提示： WM_QOS.CORRELATION_ID 必须是一个 GUID (Globally Unique Identifier)，而不是简单的 MD5 哈希值或其他非标准字符串。Walmart API 依赖 GUID 来确保请求的唯一性，从而正确追踪和处理每个 API 调用。

在 PHP 中，您可以编写一个函数来生成符合要求的 GUID。以下是一个示例函数：

<?php
/**
 * 生成一个符合 RFC 4122 标准的 GUID (UUID v4)。
 *
 * @return string 生成的 GUID 字符串。
 */
function generateGuid() {
    if (function_exists('com_create_guid') === true) { // 适用于 Windows 环境
        return trim(com_create_guid(), '{}');
    }

    // 适用于非 Windows 环境或未启用 com_create_guid 的情况
    mt_srand((double)microtime() * 10000); // 播种随机数生成器
    $charid = strtoupper(md5(uniqid(rand(), true)));
    $hyphen = chr(45); // ASCII 45 是 '-'
    $uuid = substr($charid, 0, 8) . $hyphen
          . substr($charid, 8, 4) . $hyphen
          . substr($charid, 12, 4) . $hyphen
          . substr($charid, 16, 4) . $hyphen
          . substr($charid, 20, 12);
    return $uuid;
}
?>

1.4 PHP cURL 示例代码（获取令牌）

<?php
// 请替换为您的实际 Client ID 和 Secret Key
define('CLIENT_ID', 'YOUR_WALMART_CLIENT_ID');
define('SECRET_KEY', 'YOUR_WALMART_SECRET_KEY');

// 包含上面定义的 generateGuid 函数
// ... (generateGuid 函数代码) ...

$getTokenUrl = 'https://marketplace.walmartapis.com/v3/token';
$client_id