Shopline QL

Admin API
1

仅限 Enterprise 客户使用，当前内测中。如需开通请联系客户经理。

概览

SHOPLINE QL 是一种专为 SHOPLINE 平台业务场景设计的数据查询语言。它提供了一种基于代码的方法，用于从 SHOPLINE 数据库中检索与订单相关的数据。该语言旨在帮助用户高效地访问、分析和操作数据，以支持业务增长和决策。

应用场景

数据检索
SHOPLINE QL 允许用户从其 SHOPLINE 数据库中提取订单信息和其他相关数据。这对于希望深入分析订单的企业尤其有用。

自定义报告
企业可以使用通过 SHOPLINE QL 检索的数据创建自定义报告和仪表盘，根据其特定需求定制分析内容。

业务增长
通过基于 SHOPLINE QL 获取的数据做出明智决策，企业可以规划和执行支持其增长和扩展的策略。

SHOPLINE QL API

1. 概述

通过调用 SHOPLINE QL API，您可以查询自己店铺的数据。

2. 快速开始

curl --location --request POST 'https://test.myshopline.com/admin/openapi/v20231201/shoplineQL.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ5c291bCIsInNlbGxlcklkIjoiMzMwMDAwMzY2NyIsInN0b3JlSWQiOiIxNjM0ODg2MjAzMjk5IiwidXVpZCI6IjFkNWI1YWJkLTRmNjMtNDZiZi04YzFjLWFmNTgzZGI3ZjRlMSIsImFwcElkIjoiMjYzMjY3IiwiZG9tYWluIjoiaHR0cDovL29wLXRlc3QuZHVvd2FuLmNvbSJ9.GgQPYOKHvNIy8_mYYYu0nLQWbiRseqlUz5wmKcRslz0vLjIXE_eExeLgjlloEkUicNMEW4pvNQ0yTD6mabM' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shopline_ql":"select city, sum(adjust_amount) as adjustAmount, sum(gross_sales) as gross_sales, sum(total_sales) as total_sales from orders where date_time>='2023-01-02' group by city limit 2000"
}'

{
  "data": {
    "result": "[{\"adjustAmount\":0,\"city\":\"广州市\",\"gross_sales\":59800,\"total_sales\":60286}]"
  }
}

3. 集成流程

  1. 配置具有“read_store_metrics”权限的 AppKey（token）
  • 公共应用&自定义应用，如何获取机制授权，请点击
  • 私有应用配置，请点击
  1. 填写请求 URL：{store_host}/admin/openapi/{api_version}/shoplineQL.json
  • {store_host} 替换为您的店铺域名，{api_version} 替换为您使用的 API 版本号，例如：https://test.myshopline.com/admin/openapi/v20231201/shoplineQL.json
  1. 在请求头中填写 AppKey（token）
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ5c291bCIsInNlbGxlcklkIjoiMzMwMDAwMzY2NyIsInN0b3JlSWQiOiIxNjM0ODg2MjAzMjk5IiwidXVpZCI6IjFkNWI1YWJkLTRmNjMtNDZiZi04YzFjLWFmNTgzZGI3ZjRlMSIsImFwcElkIjoiMjYzMjY3IiwiZG9tYWluIjoiaHR0cDovL29wLXRlc3QuZHVvd2FuLmNvbSJ9.GgQPYOKHvNIy8_mYYYu0nLQWbiRseqlUz5wmKcRslz0vLjIXE_eExeLgjlloEkUicNMEW4pvNQ0yTD6mabM0Ww
  1. 在请求体中填写 SHOPLINE QL 查询语句
  • 基于标准 SQL 的查询语言
{
  "shopline_ql":"select city, sum(adjust_amount) as adjustAmount, sum(gross_sales) as gross_sales, sum(total_sales) as total_sales from orders where date_time>='2023-01-02' group by city limit 2000"
}

  1. 发起 HTTP 请求

  2. 获取响应

  • 查询结果（JSON 格式）
{
  "data": {
    "result": "[{\"adjustAmount\":0,\"city\":\"广州市\",\"gross_sales\":59800,\"total_sales\":60286}]"
  }
}

数据集

1. 订单数据集（orders）

说明：此数据集的每一行代表一个订单在 1 小时内的相关变动。所有价格均以店铺货币（单位：分）表示。

1.1. 数值

数值是数据集中的基础数字，通常使用 SHOPLINE QL 函数（如 sum）进行聚合。

名称 类型 定义
gross_sales 数字 订单中售出商品的总价值
discounts 数字 应用于订单的折扣价值
net_sales 数字 售出商品的总价值，减去应用的折扣和退货商品价值
tax 数字 基于商品收取的税费总额
express_tax_amount 数字 基于运费收取的税费总额
member_point_amount 数字 使用会员积分支付的金额
shipping 数字 收取的运费金额，减去运费折扣或退款
tips 数字 小费金额
refunds 数字 退款的订单金额
total_sales 数字 售出商品的总价值，减去应用的折扣、退货、税费、小费、运费、adjust_amount 等
order_quantity 数字 订购的商品数量，减去退货
return_quantity 数字 退货的商品数量
adjust_amount 数字 根据店铺货币四舍五入到最接近面额的金额
refund_adjust_amt 数字 退款的 adjust_amount 金额

1.2. 维度属性

名称 类型 定义
order_seq 字符串 SHOPLINE 中使用的唯一订单标识符
region 字符串 订单发货的地区/国家
province 字符串 订单发货的省/州
city 字符串 订单发货的城市
sales_channel 字符串 销售来源的渠道，例如在线商店
date_time 日期时间 变动发生的对应小时，以店铺时区表示，格式为 YYYY-MM-DD HH:mm:ss

2. 产品数据集（products）

说明：此数据集的每一行代表一个产品在 1 小时内的销售和会话数据。所有价格均以店铺货币（单位：分）表示。

2.1. 数值

数值是数据集中的基础数字，通常使用 SHOPLINE QL 函数（如 sum）进行聚合。

名称 类型 定义
view_sessions 数字 产品被浏览的会话次数
add_to_cart_sessions 数字 产品被加入购物车的会话次数
checkout_sessions 数字 产品到达结算页面的会话次数
purchase_sessions 数字 产品被购买的会话次数
product_subtotal_sales 数字 在计算折扣、退货、运费或税费之前的销售额
product_quantity 数字 订购的商品数量，减去退货
discounts 数字 从产品常规价格中扣除的金额
net_sales 数字 在计算折扣和退货之后的销售额，但不包括税费
product_taxes 数字 收取的税费总额
product_shipping_taxes 数字 收取的运费税费总额
product_sales 数字 在计算折扣、税费、小费、运费、adjust_amount、退货等之后的销售额

2.2. 维度属性

名称 类型 定义
product_id 数字 SHOPLINE 中使用的唯一产品标识符
product_title 字符串 产品的名称
product_type 字符串 描述产品性质的标签
date_time 日期 变动发生的对应小时，以店铺时区表示，格式为 YYYY/MM/DD HH:mm:ss