---
title: "设置 Cookie 授权状态"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/ajax-api/cookie-consent'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/ajax-api/cookie-consent.md'
---
# 设置 Cookie 授权状态

用于记录或更新客户对 Cookies 的授权状态。

当客户在 GDPR Cookie Consent 弹窗中保存 Cookie 偏好设置后，可以调用此接口更新客户对 Cookies 的授权状态。

## 请求信息

### API 路径

`POST` `https://{handle}.myshopline.com/api/privacy/set_tracking_consent`

> **备注**
>
> `handle` 表示店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001`。

### 请求头

| **参数名** | **参数类型** | **是否必填** | **描述** |
| ------------ | -------- | -------- | --------------- |
| Content-Type | String   | 是        | 值固定为 `application/json`。 |
| Cookie       | String   | 是        | 商家网页 Cookies，必须包含 `_tracking_consent` 和 `_cmp_a`。以上两个 Cookies 的值必须为合法且经过 URL 编码的 JSON 格式字符串。 |

### 请求体

| **参数名** | **参数类型** | **是否必填** | **描述** |
| ----------- | -------- | -------- | --------------- |
| preferences | Boolean  | 是        | 是否同意使用功能型 Cookies（Functionality Cookies）。<ul><li>`true`：同意使用功能型 Cookies</li><li>`false`：拒绝使用功能型 Cookies</li></ul>该类 Cookies 用于让网站记住用户名和个性化选择，如国家、地区和语言，以提供个性化的功能。 |
| analytics   | Boolean  | 是        | 是否同意使用分析型 Cookies（Performance Cookies）。<ul><li>`true`：同意使用分析型 Cookies</li><li>`false`：拒绝使用分析型 Cookies</li></ul>该类 Cookies 用于匿名收集客户与网站的互动数据，以分析和优化网站性能。 |
| marketing   | Boolean  | 是        | 是否同意使用个性化与广告 Cookies（Targeting and Advertising Cookies）。<ul><li>`true`：同意使用个性化与广告 Cookies</li><li>`false`：拒绝使用个性化与广告 Cookies</li></ul>该类 Cookies 用于允许广告商跨站追踪客户以展示广告，并衡量广告效果。 |
| max\_age    | Integer  | 否        | 设置客户授权状态 Cookies（`_tracking_consent` 和 `_cmp_a`）的有效期。单位：秒。<br />取值范围：1-31536000<br />默认值：`31536000`（365 天） |

## 响应信息

### 响应头

| **参数名** | **参数类型** | **描述** |
| ---------- | -------- | --------------- |
| Set-Cookie | String   | 更新后的 `_tracking_consent` Cookie，用于记录客户授权状态。Cookie 的值为 URL 编码后的 JSON 格式字符串。<br />例子：`_tracking_consent=%7B%22con%22%3A%7B%22CMP%22%3A%7B%22a%22%3A%221%22%2C%22p%22%3A%221%22%2C%22s%22%3A%221%22%2C%22m%22%3A%221%22%7D%7D%2C%22lim%22%3A%5B%22GDPR%22%5D%2C%22v%22%3A%222.1%22%7D; Path=/; Max-Age=3600` |
| Set-Cookie | String   | 更新后的 `_cmp_a` Cookie，用于记录客户授权明细。Cookie 的值为 URL 编码后的 JSON 格式字符串。<br />例子：`_cmp_a=%7B%22purposes%22%3A%7B%22a%22%3Atrue%2C%22p%22%3Atrue%2C%22m%22%3Atrue%2C%22t%22%3Atrue%7D%2C%22display_banner%22%3Atrue%2C%22merchant_geo%22%3A%22DE%22%2C%22sale_of_data_region%22%3Afalse%7D; Path=/; Max-Age=3600; SameSite=Lax` |

### 响应体

| **参数名** | **参数类型** | **描述** |
| ------- | ------------ | --------------- |
| code    | String   | 返回码，表示请求的处理结果。有效枚举值包含：<ul><li>`SUCCESS`：接口调用成功</li><li>`INVALID_ARGUMENT`：请求参数错误</li><li>`COOKIE_INVALID`：请求中的 Cookies 缺失或无效</li></ul> |
| success | Boolean  | 表示接口调用是否成功。有效枚举值包含：<ul><li>`true`：接口调用成功</li><li>`false`：接口调用失败</li></ul> |
| data    | Boolean  | 表示客户授权状态 Cookies 是否已更新以及被客户拒绝使用的 Cookies 是否已删除。<ul><li>`true`：客户授权状态 Cookies 已更新且被客户拒绝使用的 Cookies 已删除。</li><li>`false`：客户授权状态 Cookies 未更新且被客户拒绝使用的 Cookies 未删除。错误原因可查看响应体中的 `code` 字段。</li></ul> |

## 样例

### 成功样例

如下为请求成功的样例，其中 `_tracking_consent` 和 `_cmp_a` Cookies 已更新，且被客户拒绝授权的 Cookies 已删除。

#### 请求

```bash
curl --location --request POST 'https://your-handle.myshopline.com/api/privacy/set_tracking_consent' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: _tracking_consent=%7B%22con%22%3A%7B%22CMP%22%3A%7B%22a%22%3A%221%22%2C%22p%22%3A%221%22%2C%22s%22%3A%221%22%2C%22m%22%3A%221%22%7D%7D%2C%22lim%22%3A%5B%22GDPR%22%5D%2C%22v%22%3A%222.1%22%7D; _cmp_a=%7B%22purposes%22%3A%7B%22a%22%3Atrue%2C%22p%22%3Atrue%2C%22m%22%3Atrue%2C%22t%22%3Atrue%7D%2C%22display_banner%22%3Atrue%2C%22merchant_geo%22%3A%22DE%22%2C%22sale_of_data_region%22%3Afalse%7D' \
  --data-raw '{
    "preferences": true,
    "analytics": false,
    "marketing": false,
    "max_age": 86400
}'
```

#### 响应头

```json
Set-Cookie
_tracking_consent=%7B%22con%22%3A%7B%22CMP%22%3A%7B%22a%22%3A%220%22%2C%22p%22%3A%221%22%2C%22s%22%3A%22%22%2C%22m%22%3A%220%22%7D%7D%2C%22lim%22%3A%5B%22GDPR%22%5D%2C%22v%22%3A%222.1%22%2C%22reg%22%3A%22GDPR%22%7D; Path=/; Max-Age=86400

Set-Cookie
_cmp_a=%7B%22purposes%22%3A%7B%22a%22%3Afalse%2C%22p%22%3Atrue%2C%22m%22%3Afalse%2C%22t%22%3Afalse%7D%2C%22display_banner%22%3Atrue%2C%22merchant_geo%22%3A%22%22%2C%22sale_of_data_region%22%3Afalse%7D; Path=/; Max-Age=86400; SameSite=Lax
```

#### 响应体

```json
{
  "code": "SUCCESS",
  "success": true,
  "data": true
}
```

### 失败样例 1

如下为请求失败的样例，原因是请求体中未包含必填参数 `preferences`，`analytics` 和 `marketing`。

#### 请求

```bash
curl --location --request POST 'https://your-handle.myshopline.com/api/privacy/set_tracking_consent' \
--header 'Cookie: _tracking_consent=%7B%22con%22%3A%7B%22CMP%22%3A%7B%22a%22%3A%221%22%2C%22p%22%3A%221%22%2C%22s%22%3A%221%22%2C%22m%22%3A%221%22%7D%7D%2C%22lim%22%3A%5B%22GDPR%22%5D%2C%22v%22%3A%222.1%22%7D; _cmp_a=%7B%22purposes%22%3A%7B%22a%22%3Atrue%2C%22p%22%3Atrue%2C%22m%22%3Atrue%2C%22t%22%3Atrue%7D%2C%22display_banner%22%3Atrue%2C%22merchant_geo%22%3A%22DE%22%2C%22sale_of_data_region%22%3Afalse%7D' \
--header 'Content-Type: application/json' \
--data-raw '{}'
```

#### 响应体

```json
{
  "code": "INVALID_ARGUMENT",
  "success": false,
  "data": false
}
```

### 失败样例 2

如下为请求失败的样例，原因是请求头中未包含 `_tracking_consent` 和 `_cmp_a` Cookies。

#### 请求

```bash
curl --location --request POST 'https://your-handle.myshopline.com/api/privacy/set_tracking_consent' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: ' \
  --data-raw '{
    "preferences": true,
    "analytics": false,
    "marketing": false,
    "max_age": 86400
}'
```

#### 响应体

```json
{
  "code": "COOKIE_INVALID",
  "success": false,
  "data": false
}
```