Sử dụng API thông qua yêu cầu HTTP

Quy trình gọi API

Địa chỉ yêu cầu gọi API

Xport cung cấp một môi trường sản xuất trực tuyến trên toàn cầu, trong đó dữ liệu được tạo ra là dữ liệu thực tế và hợp lệ. Địa chỉ yêu cầu như sau:

Địa chỉ yêu cầu API: https://www.xportcn.com

Yêu cầu và phản hồi

API nền tảng mở toàn cầu Xport hỗ trợ cả giao thức truyền thông HTTP và HTTPS. Để đảm bảo an toàn dữ liệu, khuyến nghị sử dụng giao thức HTTPS để gửi yêu cầu API.

Tất cả các yêu cầu API đều trả về một kết quả phản hồi, kết quả phản hồi này hiển thị trạng thái trả về (thành công hoặc lỗi), cũng như có thể cung cấp kết quả hoặc dữ liệu chi tiết liên quan đến yêu cầu cụ thể, định dạng dữ liệu trả về là JSON.

Tham số yêu cầu

Tất cả các tham số yêu cầu của API bao gồm hai phần: tham số hệ thống và tham số kinh doanh.

Tham số hệ thống

Tất cả các yêu cầu API đều cần các tham số hệ thống sau đây, xem chi tiết trong bảng dưới đây:

Tên	Kiểu	Bắt buộc	Như một tham số của người phát	Mô tả
access-key	String	yes	yes	AccessKey được Xport cấp cho nhà phát triển
timestamp	String	yes	yes	Vui lòng sử dụng dấu thời gian UTC cho thời gian gửi yêu cầu, lưu ý thời gian yêu cầu và thời gian UTC không được vượt quá 600 giây
nonce-str	String	yes	yes	Chuỗi ngẫu nhiên 32 bit
user-id	String	no	no	Để kiểm soát quyền truy cập tài khoản con
signature	String	yes	no	Chữ ký giao diện, được sử dụng để xác minh tính hợp lệ của yêu cầu, chi tiết quy tắc cụ thể xem trong chữ ký tham số.

Cần lưu ý rằng tất cả các tham số hệ thống phải được lưu trữ trong phần đầu yêu cầu HTTP.

Tham số kinh doanh

Ngoài các tham số hệ thống bắt buộc, tất cả các yêu cầu API đều phải bao gồm các tham số kinh doanh tương ứng, chi tiết về các tham số kinh doanh của mỗi API xem trong Tài liệu tham khảo API。

Phản hồi yêu cầu

Định dạng dữ liệu phản hồi yêu cầu của tất cả các API là JSON, định dạng tham khảo như sau:

Tên	Kiểu	Mô tả
requestId	String	ID yêu cầu, có thể tra cứu nhật ký tương ứng dựa trên ID yêu cầu
code	Integer	Mã trả về
developId	String	ID nhà phát triển
msg	String	Thông tin tương ứng với mã trả về
data	Object	Nội dung trả về

Ví dụ về phản hồi yêu cầu:

{
    "requestId": "4cfda0b725184ab8a1e3ee3b9051ec35",
    "code": 200,
    "developId": "1014533973088404335",
    "msg": "成功",
    "data": {
        "quantity": 400,
        "categoryPath": "童装/婴儿装/亲子装->裙子(新)->连衣裙",
        "shopName": "u[2206891060210]",
        "description": "测试",
        "productUnit": null,
        "picUrls": [
            "https://img.alicdn.com/bao/uploaded/i1/263669477/O1CN01fH0cbf2JsW8fvHFwx_!!263669477.jpg"
        ],
        "title": "天穹发布商品，测试请不要拍",
        "mpId": "2048057995392326",
        "categoryName": "连衣裙",
        "itemId": 672991141190,
        "userNick": "测试账号tbc003",
        "price": 1,
        "beginAmount": 0,
        "status": "active",
        "promotionPrice": 1,
        "shopId": 268763467,
        "categoryId": "121452038",
        "itemType": "HAVE_MATERIAL",
        "skuList": [
            {
                "picUrl": null,
                "quantity": 200,
                "price": 1,
                "skuId": "3452545926724",
                "status": "active",
                "promotionPrice": "1",
                "postFee": 0,
                "mpSkuld": null,
                "properties": [
                    {
                        "valueId": 28326,
                        "valueName": "红色",
                        "propId": 1627207,
                        "propName": "颜色分类"
                    },
                    {
                        "valueId": 3273546,
                        "valueName": "52cm",
                        "propId": 122216343,
                        "propName": "参考身高"
                    }
                ]
            },
            {
                "picUrl": null,
                "quantity": 200,
                "price": 1,
                "skuId": "3452545926725",
                "status": "active",
                "promotionPrice": "1",
                "postFee": 0,
                "mpSkuld": null,
                "properties": [
                    {
                        "valueId": 28324,
                        "valueName": "黄色",
                        "propId": 1627207,
                        "propName": "颜色分类"
                    },
                    {
                        "valueId": 3273546,
                        "valueName": "52cm",
                        "propId": 122216343,
                        "propName": "参考身高"
                    }
                ]
            }
        ]
    }
}

Chữ ký tham số

Nền tảng mở toàn cầu Xport sẽ xác minh danh tính của mỗi yêu cầu API và máy chủ cũng sẽ xác minh tính hợp lệ của các tham số yêu cầu. Do đó, mỗi yêu cầu HTTP phải bao gồm dữ liệu chữ ký, các yêu cầu có chữ ký không hợp lệ sẽ bị từ chối.

Nền tảng mở toàn cầu Xport xác minh danh tính yêu cầu thông qua AccessKey và khóa bí mật (AccessSecret) được cấp cho nhà phát triển. Khóa bí mật (AccessSecret) được sử dụng để tạo chuỗi chữ ký trong yêu cầu HTTP, vui lòng bảo mật khóa bí mật (AccessSecret) của bạn một cách nghiêm ngặt.

Quá trình tạo chữ ký là như sau:
Bước 1: bấm 'truy cập', 'timestamp', 'nonce_str', 'truy cập secret' trực tiếp ghép;
Bước 2: ghép chuỗi hoàn thành trong bước đầu tiên, được mã hóa bằng md5;
Bước 3: chuyển đổi tất cả các chuỗi được mã hóa thành chữ hoa để có chữ ký cuối cùng;

Ví dụ kinh doanh:

Đoạn mã ví dụ JAVA：

Mã ví dụ PHP

Sách hướng dẫn phát triển

Sử dụng API thông qua yêu cầu HTTP#

Quy trình gọi API#

Địa chỉ yêu cầu gọi API#

Yêu cầu và phản hồi#

Tham số yêu cầu#

Tham số hệ thống#

Tham số kinh doanh#

Phản hồi yêu cầu#

Chữ ký tham số#