👨‍💻技术 - shopify店铺管理API

🌹 shopify店铺管理API

`<!DOCTYPE html>

店铺API接口文档

接口认证说明

重要提示： 本文档中的所有数据修改接口 (POST, PUT, DELETE方法) 都需要认证。

认证方式： 使用Bearer Token认证，在请求头中添加 Authorization: Bearer {your_token}。

获取Token： 通过登录接口获取认证Token。

只读接口： 只读接口 (GET方法) 可以不需要认证直接访问。

认证机制

所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。认证采用Bearer Token方式，Token需要通过登录接口获取。

只有获取数据的API接口(GET方法)可以不需要认证直接访问。

POST /api/auth/login

使用用户名和密码登录，获取访问令牌(Token)。

请求体

{
  "username": "admin@example.com",
  "password": "your_password"
}

请求参数

参数名	类型	必填	描述
username	string	是	用户名或邮箱
password	string	是	密码

响应示例

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin@example.com",
      "name": "Admin User",
      "role": "admin"
    },
    "expires_in": 86400
  }
}

使用认证头

获取Token后，在所有其他API请求中，需要在HTTP头部添加以下认证信息：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

如果未提供有效的Token或Token已过期，API将返回401 Unauthorized响应。

{
  "success": false,
  "message": "未授权访问",
  "error": "token_invalid"
}

错误响应

API可能返回以下错误响应：

401 - 未授权

当未提供Token、Token无效或已过期时返回。

{
  "success": false,
  "message": "未授权访问",
  "error": "token_invalid"
}

403 - 禁止访问

当用户没有权限访问特定资源时返回。

{
  "success": false,
  "message": "没有权限访问该资源",
  "error": "forbidden"
}

404 - 资源不存在

当请求的资源不存在时返回。

{
  "success": false,
  "message": "资源不存在",
  "error": "404 Not Found: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again."
}

422 - 请求参数错误

当请求参数验证失败时返回。

{
  "success": false,
  "message": "请求参数错误",
  "errors": {
    "name": ["店铺名称不能为空"],
    "domain": ["域名格式不正确"]
  }
}

500 - 服务器错误

当服务器内部发生错误时返回。

{
  "success": false,
  "message": "服务器内部错误",
  "error": "internal_server_error"
}

测试接口

测试404错误

GET /api/test/404

此接口始终返回404错误，用于测试客户端对404响应的处理。

认证要求

此接口不需要认证，可直接访问。

响应示例

{
  "success": false,
  "message": "资源不存在",
  "error": "404 Not Found: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again."
}

1. 店铺管理

认证要求： 所有以下接口都需要认证头部 Authorization: Bearer {token}

权限要求： 用户必须具有店铺管理权限

错误处理： 如未提供有效的Token，将返回401错误；如无权限访问，将返回403错误；如请求的资源不存在，将返回404错误

获取店铺列表

GET /api/shops

获取系统中所有店铺的列表。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

Authorization: Bearer {your_token}

请求参数

参数名	类型	必填	描述
page	int	否	当前页码，默认为1
pageSize	int	否	每页数量，默认为10

响应示例

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "测试店铺",
        "shopify_domain": "example.myshopify.com",
        "status": "active",
        "created_at": "2023-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  }
}

获取店铺详情

GET /api/shops/{shop_id}

获取指定店铺的详细信息。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "name": "测试店铺",
    "shopify_domain": "example.myshopify.com",
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z"
  }
}

创建店铺

POST /api/shops

创建新的店铺。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

请求体

{
  "name": "新店铺",
  "domain": "new-shop.myshopify.com",
  "status": "active"
}

请求参数

参数名	类型	必填	描述
name	string	是	店铺名称
domain	string	是	店铺域名
status	string	否	店铺状态，可选值: active, inactive, pending, suspended，默认为active

响应示例

{
  "success": true,
  "data": {
    "id": 2,
    "name": "新店铺",
    "domain": "new-shop.myshopify.com",
    "status": "active"
  }
}

更新店铺

PUT /api/shops/{shop_id}

更新指定店铺的信息。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

请求体

{
  "name": "更新的店铺名称",
  "status": "inactive"
}

请求参数

参数名	类型	必填	描述
name	string	否	店铺名称
domain	string	否	店铺域名
status	string	否	店铺状态

响应示例

{
  "success": true,
  "data": {
    "id": 2,
    "name": "更新的店铺名称",
    "domain": "new-shop.myshopify.com",
    "status": "inactive"
  }
}

删除店铺

DELETE /api/shops/{shop_id}

删除指定的店铺。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "message": "店铺删除成功"
}

2. 店铺设置

认证要求： 所有以下接口都需要认证头部 Authorization: Bearer {token}

权限要求： 用户必须具有店铺设置管理权限

错误处理： 如未提供有效的Token，将返回401错误；如无权限访问，将返回403错误；如请求的资源不存在，将返回404错误

获取店铺设置

GET /api/shops/{shop_id}/settings

获取指定店铺的所有设置信息。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": {
    "payment": {
      "paypal": {
        "enabled": true,
        "clientId": "xxxx",
        "secret": "xxxx",
        "sandbox_mode": true
      },
      "credit_card": {
        "enabled": true,
        "gateway": "stripe",
        "stripe_publishable_key": "xxxx",
        "stripe_secret_key": "xxxx",
        "stripe_webhook_secret": "xxxx"
      }
    },
    "tax": {
      "enabled": true,
      "rate": 0.05,
      "included_in_prices": false
    },
    "shipping": {
      "enabled": true,
      "default_rate": 5.0,
      "free_shipping_threshold": 50.0,
      "shipping_methods": [
        {
          "code": "standard",
          "name": "Standard Shipping",
          "description": "Standard delivery",
          "price": 5.0
        }
      ],
      "available_countries": [
        {
          "code": "US",
          "name": "United States"
        }
      ]
    }
  }
}

更新店铺设置

PUT /api/shops/{shop_id}/settings

更新指定店铺的设置信息。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

请求体

{
  "payment": {
    "paypal": {
      "enabled": true,
      "clientId": "new-client-id",
      "secret": "new-secret",
      "sandbox_mode": false
    }
  },
  "tax": {
    "enabled": true,
    "rate": 0.06
  }
}

响应示例

{
  "success": true,
  "message": "店铺设置更新成功"
}

创建默认设置

POST /api/shops/{shop_id}/settings/default

为新店铺创建默认设置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "message": "默认设置创建成功"
}

获取支付设置

GET /api/shops/{shop_id}/settings/payment

获取指定店铺的支付设置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": {
    "paypal": {
      "enabled": true,
      "clientId": "xxxx",
      "secret": "xxxx",
      "sandbox_mode": true
    },
    "credit_card": {
      "enabled": true,
      "gateway": "stripe",
      "stripe_publishable_key": "xxxx",
      "stripe_secret_key": "xxxx",
      "stripe_webhook_secret": "xxxx"
    }
  }
}

获取税务设置

GET /api/shops/{shop_id}/settings/tax

获取指定店铺的税务设置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": {
    "enabled": true,
    "rate": 0.05,
    "included_in_prices": false
  }
}

获取运输方式

GET /api/shops/{shop_id}/settings/shipping/methods

获取指定店铺的运输方式。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": [
    {
      "code": "standard",
      "name": "Standard Shipping",
      "description": "Standard delivery",
      "price": 5.0
    },
    {
      "code": "express",
      "name": "Express Shipping",
      "description": "Express delivery",
      "price": 15.0
    }
  ]
}

获取运输国家

GET /api/shops/{shop_id}/settings/shipping/countries

获取指定店铺支持的运输国家。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "data": [
    {
      "code": "US",
      "name": "United States"
    },
    {
      "code": "CA",
      "name": "Canada"
    }
  ]
}

3. 像素跟踪

认证要求： 所有以下接口都需要认证头部 Authorization: Bearer {token}

权限要求： 用户必须具有像素跟踪管理权限

错误处理： 如未提供有效的Token，将返回401错误；如无权限访问，将返回403错误；如请求的资源不存在，将返回404错误

通用像素

获取像素列表

GET /api/shops/{shop_id}/pixels

获取店铺的所有像素配置(Applovin和GTM)。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "shop_id": 101,
      "pixel_id": "APP-123456",
      "type": "applovin",
      "description": "Applovin主追踪像素",
      "is_active": true,
      "events": {
        "purchase": true,
        "view_item": true
      },
      "created_at": "2023-05-10T08:30:00Z"
    },
    {
      "id": 2,
      "shop_id": 101,
      "pixel_id": "GTM-ABCDEF",
      "type": "gtm",
      "description": "Google Tag Manager",
      "is_active": true,
      "events": {},
      "created_at": "2023-05-11T10:15:00Z"
    }
  ]
}

获取像素详情

GET /api/shops/{shop_id}/pixels/{pixel_id}

获取指定的像素配置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "APP-123456",
    "type": "applovin",
    "description": "Applovin主追踪像素",
    "is_active": true,
    "events": {
      "purchase": true,
      "view_item": true
    },
    "created_at": "2023-05-10T08:30:00Z"
  }
}

创建像素

POST /api/shops/{shop_id}/pixels

创建新的像素跟踪配置。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

请求体

{
  "pixel_id": "APP-123456",
  "type": "applovin",
  "description": "Applovin主追踪像素",
  "is_active": true,
  "events": {
    "purchase": true,
    "view_item": true
  }
}

请求参数

参数名	类型	必填	描述
pixel_id	string	是	像素ID
type	string	是	像素类型，例如 "applovin" 或 "gtm"
description	string	否	像素描述
is_active	boolean	否	是否激活，默认为true
events	object	否	事件配置

响应示例

{
  "success": true,
  "message": "创建成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "APP-123456",
    "type": "applovin",
    "description": "Applovin主追踪像素",
    "is_active": true,
    "events": {
      "purchase": true,
      "view_item": true
    },
    "created_at": "2023-05-10T08:30:00Z"
  }
}

更新像素

PUT /api/shops/{shop_id}/pixels/{pixel_id}

更新像素配置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

请求体

{
  "pixel_id": "APP-654321",
  "description": "更新的描述",
  "is_active": false,
  "events": {
    "purchase": true,
    "view_item": false,
    "add_to_cart": true
  }
}

响应示例

{
  "success": true,
  "message": "更新成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "APP-654321",
    "type": "applovin",
    "description": "更新的描述",
    "is_active": false,
    "events": {
      "purchase": true,
      "view_item": false,
      "add_to_cart": true
    },
    "created_at": "2023-05-10T08:30:00Z"
  }
}

删除像素

DELETE /api/shops/{shop_id}/pixels/{pixel_id}

删除像素配置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

响应示例

{
  "success": true,
  "message": "删除成功"
}

Facebook像素

获取Facebook像素列表

GET /api/shops/{shop_id}/facebook-pixels

获取店铺的所有Facebook Pixel ID。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "shop_id": 101,
      "pixel_id": "123456789012345",
      "description": "Facebook主跟踪像素",
      "is_active": true,
      "created_at": "2023-05-10T08:30:00Z"
    },
    {
      "id": 2,
      "shop_id": 101,
      "pixel_id": "987654321098765",
      "description": "Facebook二级跟踪像素",
      "is_active": true,
      "created_at": "2023-05-11T10:15:00Z"
    }
  ]
}

获取Facebook像素详情

GET /api/shops/{shop_id}/facebook-pixels/{pixel_id}

获取指定的Facebook Pixel ID。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "123456789012345",
    "description": "Facebook主跟踪像素",
    "is_active": true,
    "created_at": "2023-05-10T08:30:00Z"
  }
}

创建Facebook像素

POST /api/shops/{shop_id}/facebook-pixels

创建新的Facebook像素跟踪配置。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

请求体

{
  "pixel_id": "123456789012345",
  "description": "Facebook主跟踪像素",
  "is_active": true
}

请求参数

参数名	类型	必填	描述
pixel_id	string	是	Facebook Pixel ID
description	string	否	像素描述
is_active	boolean	否	是否激活，默认为true

响应示例

{
  "success": true,
  "message": "创建成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "123456789012345",
    "description": "Facebook主跟踪像素",
    "is_active": true,
    "created_at": "2023-05-10T08:30:00Z"
  }
}

更新Facebook像素

PUT /api/shops/{shop_id}/facebook-pixels/{pixel_id}

更新指定的Facebook像素配置。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

请求体

{
  "pixel_id": "987654321098765",
  "description": "更新的Facebook像素描述",
  "is_active": false
}

响应示例

{
  "success": true,
  "message": "更新成功",
  "data": {
    "id": 1,
    "shop_id": 101,
    "pixel_id": "987654321098765",
    "description": "更新的Facebook像素描述",
    "is_active": false,
    "created_at": "2023-05-10T08:30:00Z"
  }
}

删除Facebook像素

DELETE /api/shops/{shop_id}/facebook-pixels/{pixel_id}

删除指定的Facebook像素配置。

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID
pixel_id	int	是	像素配置ID

响应示例

{
  "success": true,
  "message": "删除成功"
}

批量创建Facebook像素

POST /api/shops/{shop_id}/facebook-pixels/bulk

批量创建多个Facebook像素配置。

认证要求

需要认证： 此接口需要在请求头中包含有效的认证Token。

注意： 所有修改数据的API接口(POST, PUT, DELETE方法)都需要认证。

Authorization: Bearer {your_token}

路径参数

参数名	类型	必填	描述
shop_id	int	是	店铺ID

请求体

{
  "pixels": [
    {
      "pixel_id": "123456789012345",
      "description": "Facebook主跟踪像素",
      "is_active": true
    },
    {
      "pixel_id": "987654321098765",
      "description": "Facebook二级跟踪像素",
      "is_active": true
    }
  ]
}

响应示例

{
  "success": true,
  "message": "批量创建成功",
  "data": {
    "created_count": 2,
    "pixels": [
      {
        "id": 1,
        "shop_id": 101,
        "pixel_id": "123456789012345",
        "description": "Facebook主跟踪像素",
        "is_active": true,
        "created_at": "2023-05-10T08:30:00Z"
      },
      {
        "id": 2,
        "shop_id": 101,
        "pixel_id": "987654321098765",
        "description": "Facebook二级跟踪像素",
        "is_active": true,
        "created_at": "2023-05-10T08:31:00Z"
      }
    ]
  }
}

搜索结果

店铺API接口文档

接口认证说明

目录

认证机制

登录获取Token

请求体

请求参数

响应示例

使用认证头

错误响应

401 - 未授权

403 - 禁止访问

404 - 资源不存在

422 - 请求参数错误

500 - 服务器错误

测试接口

测试404错误

认证要求

响应示例

1. 店铺管理

获取店铺列表

认证要求

请求参数

响应示例

获取店铺详情

认证要求

路径参数

响应示例

创建店铺

认证要求

请求体

请求参数

响应示例

更新店铺

认证要求

路径参数

请求体

请求参数

响应示例

删除店铺

认证要求

路径参数

响应示例

2. 店铺设置

获取店铺设置

路径参数

响应示例

更新店铺设置

认证要求

路径参数

请求体

响应示例

创建默认设置

路径参数

响应示例

获取支付设置

路径参数

响应示例

获取税务设置

路径参数

响应示例

获取运输方式

路径参数

响应示例

获取运输国家

路径参数

响应示例

3. 像素跟踪

通用像素

获取像素列表

路径参数

响应示例

获取像素详情

路径参数

响应示例

创建像素

认证要求

路径参数

请求体