README

一个 Concrete CMS 扩展，为社区商店数据提供 RESTful API，返回和接收 JSON 数据。

当前功能

获取订单列表和单个订单详情
更新订单的履行状态
获取产品列表和单个产品
通过产品 ID 或 SKU 更新产品和变体的库存水平
获取履行状态

此功能未来可能会扩展。

设置

安装后，社区商店 API 通过 concrete5 的内置 API 访问，该 API 使用 OAuth2 进行身份验证。要配置集成

请访问 concrete5 控制面板，系统 & 设置 -> API
如果尚未启用，请通过复选框启用 API，并确保在 启用授权类型 下选中 客户端凭据
通过 添加集成 按钮
为集成提供一个合适的名称，例如 'Community Store API'
记录生成的 客户端 ID 和 客户端密钥 值

缺少授权头

当使用 Apache 和 CGI/FastCGI 运行 concrete5 时，授权头可能不会传递给 PHP，导致出现 '缺少授权头' 错误消息。在 .htaccess 文件中添加以下行可以纠正此问题

SetEnvIf Authorization .+ HTTP_AUTHORIZATION=$0

与 PHP 一起使用

如果您需要通过 PHP 访问社区商店 API，您可能会发现此项目有用。

通用用法

通过 concrete5 控制面板创建集成后，可以使用客户端 ID 和客户端密钥生成访问令牌，然后使用这些令牌访问 API。

通过向 URL 发送 POST 请求来请求访问令牌：/oauth/2.0/token，在正文中发送

grant_type: "client_credentials"
scope: "cs:orders:read cs:products:write cs:products:read cs:products:write cs:config:read"
client_id
client_secret

传递的权限可以减少到只包含集成所需的权限。

JSON 响应将包含一个 access_token 值。访问令牌通常有效期为 1 小时。

然后可以使用访问令牌执行对 API 的请求，并将其作为授权头发送。授权头需要以 'Bearer ' 开头。

响应遵循典型的 RESTful 风格 HTTP 响应代码，例如 404 表示未找到记录，200 表示找到记录，等等，以及错误消息。

订单相关端点

GET /cs/api/v1/orders

获取分页订单

所需权限：cs:orders:read
示例响应

{
    "data": [
        {
            "id": 3,
            "date_placed": {
                "date": "2020-10-06 12:12:37.000000",
                "timezone": "America/Phoenix"
            },
            "total": 100.50,
            "payment_method": "Invoice",
            "payment_date": null,
            "payment_reference": null,
            "shipping_method": "",
            "fulfilment": {
                "status": "Delivered",
                "handle": "Delivered",
                "tracking_id": '123',
                "tracking_code": 'ABC1234',
                "tracking_url": null
            },
            "locale": "en_US",
            "customer": {
                "email": "test@test.com,
                "username": null,
                "billing": {
                    "phone": "123123123",
                    "first_name": "Joe",
                    "last_name": "Smith",
                    "company": "ABC Company",
                    "address": {
                        "address1": "123 Street",
                        "address2": "",
                        "address3": null,
                        "city": "Phoenix",
                        "state_province": "AZ",
                        "country": "US",
                        "postal_code": "55555"
                    }
                },
                "shipping": {
                    "first_name": "Joe",
                    "last_name": "Smith",
                    "company": "ABC Company", 
                    "address": {
                          "address1": "123 Street",
                          "address2": "",
                          "address3": null,
                          "city": "Phoenix",
                          "state_province": "AZ",
                          "country": "US",
                          "postal_code": "55555"
                      }
                }
            },
            "items": [
                {
                    "id": 123,
                    "name": "Example Product",
                    "sku": "ABCD",
                    "quantity": 1,
                    "price": 100.50
                }
            ]
        }

        // ... addition 19 orders would be included here

    ],
    "meta": {
        "pagination": {
            "total": 25,
            "count": 20,
            "per_page": 20,
            "current_page": 1,
            "total_pages": 2,
            "links": {
                "next": "http://concrete5.test/cs/api/v1/orders?page=2"
            }
        }
    }
}

分页订单

订单按最近创建的顺序返回，这与订单 ID 的降序排列相同。

订单已分页显示，每次返回20条订单。注意响应中存在一个meta -> pagination部分，其中包含表示分页位置的值。分页数据中的links包括适用时的前一页和下一页URL，用于导航订单页面。当没有返回next值时，表示没有更多页面。在API调用中，使用GET属性page来选择返回哪一页。

过滤订单

您可以使用查询字符串参数来过滤结果。以下是接受的查询字符串参数列表

status：订单的状态（预定义状态包括incomplete、processing、shipped、delivered、nodelivery和returned）
paymentStatus：订单支付的状态（paid、unpaid、cancelled、refunded或incomplete）
fromDate：订单的初始日期（格式：YYYY-MM-DD）
toDate：订单的最终日期（格式：YYYY-MM-DD）
paid：对于未支付或已退款的订单设置为0，对于已支付且未退款的订单设置为1
cancelled：设置为0以排除已取消的订单，设置为1以仅检索已取消的订单
refunded：设置为0以排除已退款的订单，设置为1以仅检索已退款的订单
shippable：设置为0以排除可发货的订单，设置为1以仅检索可发货的订单
id：订单ID。您还可以使用数组查询多个ID（例如：orders?id[]=1&id[]=2）（需要社区商店以及这个请求）

GET /cs/api/v1/orders/oID

获取订单

所需权限：cs:orders:read
URL参数：oID = 订单ID
响应：在data值中代表单个订单的JSON

PATCH /cs/api/v1/orders/oID

更新单个订单的履行细节

必需的作用域：'cs:orders:write
可更新字段：tracking_id、tracking_code、tracking_url、handle
期望原始正文：JSON数据，例如

{
"data":
  { 
      "fulfilment": { 
          "handle": "shipped",
          "tracking_id": "123123123",
          "tracking_code": "AAABBCCC",
          "tracking_url": "https://trackmyparcel.com"
      }
  }
}

响应：在更新执行后，在data值中代表单个订单的JSON

GET /cs/api/v1/fulfilmentstatuses

获取所有履行状态

所需权限：cs:orders:read
示例响应

{
    "data": [
        {
            "id": "1",
            "handle": "incomplete",
            "name": "Awaiting Processing"
        },
        {
            "id": "2",
            "handle": "processing",
            "name": "Processing"
        },
        {
            "id": "3",
            "handle": "shipped",
            "name": "Shipped"
        },
        {
            "id": "4",
            "handle": "delivered",
            "name": "Delivered"
        },
        {
            "id": "5",
            "handle": "nodelivery",
            "name": "Will not deliver"
        },
        {
            "id": "6",
            "handle": "returned",
            "name": "Returned"
        }
    ]
}

与产品相关的端点

GET /cs/api/v1/products

获取所有产品

必需的作用域：cs:products:read
响应：在data值中代表产品的JSON数组

分页产品

产品以最近添加的产品为优先返回。

产品已分页显示，每次返回20个产品。注意响应中存在一个meta -> pagination部分，其中包含表示分页位置的值。分页数据中的links包括适用时的前一页和下一页URL，用于导航产品页面。当没有返回next值时，表示没有更多页面。在API调用中，使用GET属性page来选择返回哪一页。

过滤产品

可以通过使用filter参数过滤产品，格式如下：?filter=date_added gt '2021-01-01T20:00'。目前，可以过滤date_added和date_updated字段，使用gt、lt和eq比较。

GET /cs/api/v1/products/pID

获取产品

必需的作用域：cs:products:read
URL参数：pID = 产品ID
响应：在data值中代表单个产品的JSON
示例响应

{
    "data": {
        "id": 123,
        "name": "Example Product",
        "sku": "ABCD",
        "barcode": "",
        "active": true,
        "stock_unlimited": false,
        "stock_level": 10,
        "short_description": "Short description HTML",
        "description": "Extended description HTML",
        "brand": null,
        "price": 100.50,
        "primary_image": "https://domain.com/product.jpg",
        "additional_images": [
            "https://domain.com/product2.jpg"
        ],
        "groups": [
            "Product Group 1"
        ],
        "categories": [
            {
                "name": "Product Category 1",
                "url": "https://domain.com/category1"
            } 
        ],
        "variations": [],
        "date_added": {
            "date": "2020-10-05 15:41:00.000000",
            "timezone": "America/Phoenix"
        },
       "date_updated": {
            "date": "2020-10-05 15:41:00.000000",
            "timezone": "America/Phoenix"
        }
    }
}

PATCH /cs/api/v1/products/pID

更新产品

可更新字段：stock_unlimited（布尔值）、stock_level（浮点数）
必需的作用域：cs:products:write
URL参数：pID = 产品ID
期望原始正文：JSON数据，例如

{
  "data":
    { 
        "stock_level": 5,
        "stock_unlimited": true
    }
}

响应：在更新执行后，在data值中代表单个产品的JSON

GET /cs/api/v1/skus/sku

通过SKU获取产品或变体的库存水平

必需的作用域：cs:products:read
URL参数：sku = 产品或变体的SKU

PATCH /cs/api/v1/skus/sku

通过SKU更新产品或变体的库存水平

可更新字段：stock_unlimited（布尔值）、stock_level（浮点数）
必需的作用域：cs:products:write
URL参数：sku = 产品或变体的SKU
期望原始正文：JSON数据，例如

{
"data":
    { 
        "stock_level": 5,
        "stock_unlimited": true
    }
}

其他端点

GET /cs/api/v1/config

获取一些社区商店配置值

必需的作用域：cs:config:read
响应：JSON对象，其键是配置键，值是它们的值

示例响应

{
    "currency": {
        "code": "EUR",
        "symbol": "€",
        "decimal_digits": 2
    }
}

concretecms-community-store / community_store_api

维护者

详细信息