mtrdesign/cottoncart-api-php-client

Cotton Cart API 客户端库使您能够在服务器上与 Cotton Cart API 进行交互。此库支持 JSON 和 API 输出格式。

维护者

详细信息

github.com/mtrdesign/cottoncart-api-php-client

主页

源代码

问题

安装: 175

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 7

分支: 0

开放问题: 0

dev-master 2019-06-25 14:52 UTC

Requires

  • php: >=5.3.2
  • ext-curl: *

MIT e0c84826413c436a895d00bbe320f17f61667bf4

api clientcotton cart

This package is auto-updated.

Last update: 2024-09-26 02:24:03 UTC

README

关于

Cotton Cart API 客户端库使您能够在服务器上与 Cotton Cart API 进行交互。此库支持 JSON 和 XML API 输出格式。

欢迎反馈和错误报告。

要求

要使用此客户端，您需要

入门

如果您遇到任何问题或有任何疑问，请通过电子邮件 support@cottoncart.com 联系我们。

一般信息

Cotton Cart 使用基于 https://www.cottoncart.com/api/ 的 RESTful API。每个 API 调用都有一个对应的 URL。每个 API URL 符合以下模式：

$versionID/$method_group/$method.$format

其中

  • $versionID 是一个标识 API 版本的短字符串（例如，'v1'）
  • $method_group 是一个表示功能组的单词（例如，'catalogue'）
  • $method 是功能组内的 API 调用名称（例如，'stores'）
  • $format 是期望的响应格式，可以是 "xml" 或 "json"

示例 URL

https://www.cottoncart.com/api/v1/catalogue/stores.xml https://www.cottoncart.com/api/v1/catalogue/stores.json

认证调用

某些 API 调用需要认证，而其他则是匿名的。认证的 API 调用必须包含以下讨论的 auth_id、auth_ts 和 auth_sig 参数。没有 auth_id 的 API 调用是匿名的，即使它们包含 auth_ts 和 auth_sig，这些参数也不会被处理或验证。

每个 Cotton Cart 用户都可以通过 Web 界面创建和删除多个 API 密钥。每个密钥都有一个由 '@' 后缀附加到商店 ID 上的小写字母数字 ID（例如，'user123@mystore'），以及一个共享密钥值（16 个字符，大小写混合字母数字）。

要认证，每个调用都必须包含 3 个参数：

  • 认证 ID（auth_id，例如 'user123@mystore'）
  • 请求生成的时间戳（auth_ts）。这是一个表示准确 Unix 时间的整数值
  • 计算出的认证签名（auth_sig）

要生成有效的请求，客户端需要执行以下操作：

  • 创建签名基础字符串，由 API 版本标识符组成，后面跟一个斜杠字符，然后是 API 方法组，然后是斜杠字符，然后是 API 方法，然后是问号字符，然后是请求的所有参数（除了 "auth_sig" 参数），按键按字典顺序排序并格式化为查询字符串，但不对参数执行任何百分号转义，并且没有文件附件名称/值。
    • 注意：请求的格式不包括在签名中。
    • 示例签名基础字符串：v1/catalogue/store_info?auth_id=user123@mystore&auth_ts=1329130234&store_id=some_store
  • 生成基础字符串与 API_KEY（请参阅 PHP HMAC 文档）一起的十六进制 SHA256 HMAC。必须使用 Sha256 作为散列函数。
  • 将该十六进制值附加到参数列表中作为 auth_sig。最终的请求将如下所示：
    catalogue/store_info?store_id=some_store&auth_id=user123mystore&auth_ts=1329130234

上述方案允许服务器和客户端之间进行安全、无状态的通信。

一般响应格式

HTTP 状态码

棉布车API总是返回带有200 OK HTTP状态的响应。任何错误都包含在响应体中，不会影响HTTP头。

成功状态和错误

每个响应都包含一个success键，可以是"true"或"false"（作为字符串值）。如果success为false，则响应将包含关于错误的信息。

{
	"success": false,
	"errorCode": 400,
	"error": "Required parameter missing",
	"errorDetails": {
		"param": "store_id"
	}
}

errorDetails键是可选的，其内容因错误而异；它旨在供人类调试，而不是用于自动处理。

分页

一些请求支持分页响应，使用count和start请求参数。默认情况下，列出所有可用的记录。count可以在没有start的情况下使用（在这种情况下，将列出前count条记录）；但是，如果提供了start，则必须使用count。

如果请求分页响应，则响应将包含一个分页结构。

{
	"success": true,
	"pagination": {
		"start": 0,
		"count": 10,
		"total": 150
		"pages": 15,
		"prev_page": null,
		"next_page": 10
	}
}
  • start - 标记分页的起始点。
  • count - 每页的项目数。
  • total - 可用于列出的记录总数。
  • pages - 可用页数。
  • prev_page - 上一个页面的起始索引。
  • next_page - 下一个页面的起始索引。

start和count键与请求中的值相对应。total包含可列出的记录总数，pages包含每页count个项目数的可用页数，而prev_page和next_page分别包含上一个和下一个页面的起始索引（用于start请求参数的值，以便显示上一页/下一页）。如果无法在相应方向上进行进一步导航，则prev_page和next_page将为null。

安装

1. 使用Composer

推荐安装方法是使用Composer，它是PHP的依赖管理器。只需将mtrdesign/cottoncart-api-php-client添加到项目的composer.json文件中

"require": {
  "mtrdesign/cottoncart-api-php-client": "dev-master"
}

然后运行composer install。有关详细信息，您可以在Packagist上找到此包。

2. 从GitHub克隆

该库可在GitHub上找到。您可以使用git clone命令将其克隆到本地存储库中。

git clone https://github.com/mtrdesign/cottoncart-api-php-client.git

3. 手动方式

或者，您可以手动安装该包

  • 复制并将src文件夹重命名为您的代码库，例如到vendor目录。
  • 将新文件夹添加到自动加载器或将文件直接引入。

基本示例

1. 管理调用

2. 目录调用

3. 订单调用