Public API

Hướng dẫn sử dụng Web hook

1. Giới thiệu

IKITECH Public API được phát triển để hỗ trợ việc tích hợp và trao đổi dữ liệu giữa IKITECH và các nền tảng website, thương mại điện tử, CRM… IKITECH Public API hiện tại cung cấp cơ chế đọc và ghi các đối tượng sau:

- Sản phẩm: lấy danh sách nhóm hàng hóa với các thông tin về tên nhóm hàng và quan hệ giữa các nhóm hàng

- Hàng hóa: lấy thông tin sản phẩm, tạo mới, sửa, xóa sản phẩm, thuộc tính của sản phẩm

- Đơn hàng: lấy thông tin hóa đơn, tạo hóa đơn, cập nhật và hủy hóa đơn

- Khách hàng: lấy danh sách khách hàng và thao tác trên thông tin khách hàng

2. Xác thực tài khoản

Request đến service API sẽ được xác thực theo giá trị Token trong header của request

GET /authentication-request-sample HTTP/1.1
host: main.doapp.vn
token: your-API-token-key
store_code: your storecode

Token, Store_code Thông tin này được truy cập vào “Cài đặt” bằng tài khoản public => Chọn Thiết lập kết nối API

• URL môi trường thật, production: https://main.doapp.vn

3. Sản phẩm

3.1 Danh sách sản phẩm

GET /store/{{store_code}}/products

- Request:

page: int? //Trang cần lấy limit: int? //Giới hạn items mỗi api

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
        "total_stoking": int, //Tổng số lượng trong kho
        "total_out_of_stock": int, //Sản phẩm sắp hết hành
        "total_hide": int, //Tổng số sản phẩm bị ẩn
        "current_page": int, //page hiện tại
        "data": [ //Mảng danh sách sản phẩm
            {
                "id": int, //id sản phẩm
                "name": string, //Tên sản phẩm
                "name_str_filter": string, //Tên sản phẩm theo slug
                "sku": string, //Mã SKU của sản phẩm
                "description": string, //Mô tả sản phẩm
                "video_url": string, //Url video sản phẩm
                "stars": double, //Điểm đánh giá
                "count_stars": int, //Số lượng người đánh giá
                "view": int, //Số lượt xem
                "sold": int, //Số lượng đã bán
                "likes": int, //Số lượt thích
                "content_for_collaborator": string, //Nội dung dành cho cộng tác viên
                "price": double, //Giá bán lẻ sản phẩm
                "min_price": double, //Giá thấp nhất 
                "max_price": double, //Giá lớn nhất nhất 
                "import_price": double, //Giá nhập
                "default_price": double, //Giá mặc định
                "weight": double, //Khối lượng
                "quantity_in_stock": int, //Số lượng tồn kho
                "percent_collaborator": double, //Hoa hồng cho cộng tác viên
                "barcode": string, //Mã barcode
                "status": int, //Trạng thái 0 Hiển thị - 1 Đã ẩn 
                "check_inventory": boolean, //Sản phẩm theo dõi tồn kho hay không
                "seo_title": string, //Tiêu đề SEO
                "seo_description": string, //Mô tả SEO
                "point_for_agency": int, //Điểm cho đại lý
                "is_medicine": false, //Sản phẩm có phải là thuốc hay không
                "created_at": datetime, //Ngày thêm
                "updated_at": datetime, // Ngày cập nhật
                "distributes": [ //Mảng phân loại
                    {
                        "id": int, //id phân loại chính
                        "product_id": int, //id sản phẩm 
                        "name": string, //Tên phân loại
                        "sub_element_distribute_name": string?, //Tên phân loại phụ
                        "created_at": datetime,  //Ngày tạo
                        "updated_at": datetime, //Ngày cập nhật
                        "element_distributes": [
                            {
                                "id": int,
                                "product_id": int,
                                "name": string,
                                "image_url": string?,
                                "price": double,
                                "position": int,
                                "default_price": double,
                                "import_price": double,
                                "barcode": string?,
                                "sku": string?,
                                "quantity_in_stock": int,
                                "created_at": datetime,
                                "updated_at": datetime,
                                "sub_element_distributes": []
                            }
                        ]
                    }
                ],
                "attributes": [ //Mảng thuộc tính
                    {
                        "name": string, //Kiểu thuộc tính
                        "value": string, //Tên thuộc tính
                        "id": int //id thuộc tính
                    }
                ],
                "images": [ //Mảng ảnh sản phẩm
                    {
                        "image_url": string
                    }
                ],
            }
        ],
        "per_page": int, //số lượng sản phẩm mỗi page
        "total": int, //Tổng sản phẩm
    }
}

3.2 Thông tin 1 sản phẩm

GET /store/{{store_code}}/products/{{product_id}}

- Request:

product_id: int? //product id cần lấy thông tin

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
                "id": int, //id sản phẩm
                "name": string, //Tên sản phẩm
                "name_str_filter": string, //Tên sản phẩm theo slug
                "sku": string, //Mã SKU của sản phẩm
                "description": string, //Mô tả sản phẩm
                "video_url": string, //Url video sản phẩm
                "stars": double, //Điểm đánh giá
                "count_stars": int, //Số lượng người đánh giá
                "view": int, //Số lượt xem
                "sold": int, //Số lượng đã bán
                "likes": int, //Số lượt thích
                "content_for_collaborator": string, //Nội dung dành cho cộng tác viên
                "price": double, //Giá bán lẻ sản phẩm
                "min_price": double, //Giá thấp nhất 
                "max_price": double, //Giá lớn nhất nhất 
                "import_price": double, //Giá nhập
                "default_price": double, //Giá mặc định
                "weight": double, //Khối lượng
                "quantity_in_stock": int, //Số lượng tồn kho
                "percent_collaborator": double, //Hoa hồng cho cộng tác viên
                "barcode": string, //Mã barcode
                "status": int, //Trạng thái 0 Hiển thị - 1 Đã ẩn 
                "check_inventory": boolean, //Sản phẩm theo dõi tồn kho hay không
                "seo_title": string, //Tiêu đề SEO
                "seo_description": string, //Mô tả SEO
                "point_for_agency": int, //Điểm cho đại lý
                "is_medicine": false, //Sản phẩm có phải là thuốc hay không
                "created_at": datetime, //Ngày thêm
                "updated_at": datetime, // Ngày cập nhật
                "distributes": [ //Mảng phân loại
                    {
                        "id": int, //id phân loại chính
                        "product_id": int, //id sản phẩm 
                        "name": string, //Tên phân loại
                        "sub_element_distribute_name": string?, //Tên phân loại phụ
                        "created_at": datetime,  //Ngày tạo
                        "updated_at": datetime, //Ngày cập nhật
                        "element_distributes": [
                            {
                                "id": int,
                                "product_id": int,
                                "name": string,
                                "image_url": string?,
                                "price": double,
                                "position": int,
                                "default_price": double,
                                "import_price": double,
                                "barcode": string?,
                                "sku": string?,
                                "quantity_in_stock": int,
                                "created_at": datetime,
                                "updated_at": datetime,
                                "sub_element_distributes": []
                            }
                        ]
                    }
                ],
                "attributes": [ //Mảng thuộc tính
                    {
                        "name": string, //Kiểu thuộc tính
                        "value": string, //Tên thuộc tính
                        "id": int //id thuộc tính
                    }
                ],
                "images": [ //Mảng ảnh sản phẩm
                    {
                        "image_url": string
                    }
                ],
            }
}

4. Khách hàng

4.1 Danh sách khách hàng

GET /store/{{store_code}}/customers

- Request:

page: int? //Trang cần lấy limit: int? //Giới hạn items mỗi api

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
        "debt": double, //Tổng công nợ của khách hàng
        "current_page": 1,
        "data": [
            {
                "id": int,
                "area_code": string, //Mã vùng số điện thoại 
                "phone_number": string, //Số điện thoại
                "email": string, //Email khách hàng
                "referral_phone_number": string?, //Số điện thoại người giới thiệu
                "name": string, //Tên
                "name_str_filter": string, //Tên theo dạng slug
                "date_of_birth": datetime, //Ngày sinh
                "avatar_image": string?, //Ảnh avater
                "points": int, //Số điểm
                "sex": int, //Giới tính 0 chưa xác định, 1 nam , 2 nữ
                "debt": double, //Số nợ
                "is_collaborator": boolean, // Là cộng tác viên
                "is_agency": boolean, //Là đại lý
                "is_sale": boolean, //Là sale
                "province": int?, //id tỉnh
                "district": int?, //id huyện
                "wards": int?, //id xã
                "province_name": string?, //Tỉnh/TP
                "district_name": string?, //Quận/Huyện
                "wards_name": string?, //Phường/Xã
                "address_detail": string?, //Địa chỉ chi tiết
                "created_at": datetime,
                "updated_at": datetime,
                "total_referrals": int, //Tổng người đã giới thiệu
                "total_final_without_refund": double, //Doanh số đơn hàng không tính hoàn
                "total_final_all_status": double, //Doanh số đơn hàng tất cả trạng thái
                "total_after_discount_no_bonus": double //Doanh số chưa tính giảm giá
            }
        ],
        "per_page": int, //số lượng sản phẩm mỗi page
        "total": int, //Tổng sản phẩm
    }
}

4.2 Thông tin 1 khách hàng

GET /store/{{store_code}}/customers/{{customer_id}}

- Request:

customer_id: int? // id khách hàng cần lấy thông tin

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
                "id": int,
                "area_code": string, //Mã vùng số điện thoại 
                "phone_number": string, //Số điện thoại
                "email": string, //Email khách hàng
                "referral_phone_number": string?, //Số điện thoại người giới thiệu
                "name": string, //Tên
                "name_str_filter": string, //Tên theo dạng slug
                "date_of_birth": datetime, //Ngày sinh
                "avatar_image": string?, //Ảnh avater
                "points": int, //Số điểm
                "sex": int, //Giới tính 0 chưa xác định, 1 nam , 2 nữ
                "debt": double, //Số nợ
                "is_collaborator": boolean, // Là cộng tác viên
                "is_agency": boolean, //Là đại lý
                "is_sale": boolean, //Là sale
                "province": int?, //id tỉnh
                "district": int?, //id huyện
                "wards": int?, //id xã
                "province_name": string?, //Tỉnh/TP
                "district_name": string?, //Quận/Huyện
                "wards_name": string?, //Phường/Xã
                "address_detail": string?, //Địa chỉ chi tiết
                "created_at": datetime,
                "updated_at": datetime,
                "total_referrals": int, //Tổng người đã giới thiệu
                "total_final_without_refund": double, //Doanh số đơn hàng không tính hoàn
                "total_final_all_status": double, //Doanh số đơn hàng tất cả trạng thái
                "total_after_discount_no_bonus": double //Doanh số chưa tính giảm giá
            }
}

5. Đơn hàng

5.1 Danh sách đơn hàng

GET /store/{{store_code}}/orders

- Request:

page: int? //Trang cần lấy limit: int? //Giới hạn items mỗi api time_from: date? //Thời gian bắt đầu time_to: date? //Thời gian kết thúc search: string? //Chuỗi tìm kiếm SĐT, Tên, Mã đơn hàng

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
        "debt": double, //Tổng công nợ của khách hàng
        "current_page": 1,
        "data": [
            {
                "id": int,//Order id
                "customer_id": int?,//Id khách hàng
                "logged": boolean,
                "phone_number": string?, //Số điện thoại của người đặt
                "points_awarded_to_customer": int?, //Số xu thưởng cho khách
                "order_code": string, //Mã đơn hàng
                "order_status": int, //Order status
                "payment_status": int, //Payment status
                "payment_method_id": int, //0 Tiền mặt, 1 Quẹt thẻ, 2 COD, 3 Chuyển khoản, 4 Ví điện tử
                "partner_shipper_id": int, // 0 GHTK, 1 GHN, 3 VIETTELPOST
                "shipper_type": int, // 0 tiêu chuẩn - 1 siêu tốc
                "ship_discount_amount": double, //Tiền giảm giá bởi voucher ship
                "total_shipping_fee": double, //Tổng tiền ship
                "vat": double,// Tiền VAT
                "cod": double, // Tiền thu hộ
                "total_before_discount": double,//Tổng tiền hàng trước khi giảm giá
                "bonus_points_amount_used": int,//Số xu đã sử dụng
                "is_use_points": boolean,//Đơn hàng có dùng xu hay không
                "is_order_for_customer": boolean, //Đơn này có phải đại lý đặt hàng hộ hay không
                "combo_discount_amount": double, //Số tiền được giảm bởi combo
                "product_discount_amount": double, //Số tiền được giảm bởi giảm giá sp
                "voucher_discount_amount": double,//Số tiền được giảm bởi voucher
                "total_after_discount": double, // Tổng tiền hàng sau khi giảm giá
                "discount": double,//Chiết khấu
                "total_final": double, //Tổng tiền cần thanh toán
                "customer_name": string, //Tên người nhận hàng
                "customer_province": int, //id tỉnh người nhận
                "customer_province_name": string, //Tên tỉnh/TP
                "customer_district": int, //id Quận/Huyện
                "customer_district_name": string,//Tên Quận/Huyện
                "customer_wards": int, //id xã
                "customer_wards_name": string, //Tên xã
                "customer_email": string, //Email người nhận
                "customer_phone": "string", //Số điện thoại người nhận
                "customer_address_detail": string, //Địa chỉ người nhận
                "customer_note": string, //Ghi chú
                "remaining_amount": double,//Số tiền cần thanh toán còn lại
                "package_weight": double,//Khối lượng của gói hàng
                "package_length": double, //Chiều cao hàng
                "package_width": double,//Chiều rộng gói hàng
                "package_height": double,//Chiều cao gói hàng
                "description_shipper": string, //Mô tả cho shiper
                "created_at": datetime, //Ngày tạo đơn
                "updated_at": datetime,//Ngày cập nhật đơn
                "line_items_at_time": [ //Danh sách sản phẩm trong đơn
                    {
                        "id": int, //Id 
                        "quantity": int, //Số lượng
                        "name": string,//Tên sản phẩm
                        "image_url": string, //Đường dẫn ảnh
                        "item_price": double, //Giá cuối cùng
                        "price_before_override": double, //Giá cho đại lý
                        "main_price": 0, //Giá gốc
                        "before_discount_price": double, //Giá trước khi giảm giá
                        "before_discount_price_override": double, //Giá cho đại lý trước khi giảm giá
                        "after_discount": double, //Giá sau khi giảm giá
                        "after_discount_override": double,//Giá cho đại lý sau khi giảm giá
                        "distributes_selected": [ //Phân loại
                            {
                                "name": string,
                                "value": string
                            }
                        ],
                        "money_amount_collaborator": double, //hoa hồng cho CTV

                        "is_bonus": boolean, //Có phải sản phẩm thưởng hay không
                        "note": string//Ghi chú đi kèm
                    }
                   
                ],
                "partner_shipper_name": "Giao Hàng Trực Tiếp",
                "customer": {...} //Tương tự json thông tin 1 khách hàng
            }
        ],
        "per_page": int, //số lượng sản phẩm mỗi page
        "total": int, //Tổng sản phẩm
    }
}

5.2 Thông tin 1 đơn hàng

GET /store/{{store_code}}/orders/{{order_id}}

- Request:

order_id: int? // id đơn hàng cần lấy thông tin

- Response:

{
    "code": 200,
    "success": true,
    "msg_code": "SUCCESS",
    "msg": "THÀNH CÔNG",
    "data": {
                "id": int,//Order id
                "customer_id": int?,//Id khách hàng
                "logged": boolean,
                "phone_number": string?, //Số điện thoại của người đặt
                "points_awarded_to_customer": int?, //Số xu thưởng cho khách
                "order_code": string, //Mã đơn hàng
                "order_status": int, //Order status
                "payment_status": int, //Payment status
                "payment_method_id": int, //0 Tiền mặt, 1 Quẹt thẻ, 2 COD, 3 Chuyển khoản, 4 Ví điện tử
                "partner_shipper_id": int, // 0 GHTK, 1 GHN, 3 VIETTELPOST
                "shipper_type": int, // 0 tiêu chuẩn - 1 siêu tốc
                "ship_discount_amount": double, //Tiền giảm giá bởi voucher ship
                "total_shipping_fee": double, //Tổng tiền ship
                "vat": double,// Tiền VAT
                "cod": double, // Tiền thu hộ
                "total_before_discount": double,//Tổng tiền hàng trước khi giảm giá
                "bonus_points_amount_used": int,//Số xu đã sử dụng
                "is_use_points": boolean,//Đơn hàng có dùng xu hay không
                "is_order_for_customer": boolean, //Đơn này có phải đại lý đặt hàng hộ hay không
                "combo_discount_amount": double, //Số tiền được giảm bởi combo
                "product_discount_amount": double, //Số tiền được giảm bởi giảm giá sp
                "voucher_discount_amount": double,//Số tiền được giảm bởi voucher
                "total_after_discount": double, // Tổng tiền hàng sau khi giảm giá
                "discount": double,//Chiết khấu
                "total_final": double, //Tổng tiền cần thanh toán
                "customer_name": string, //Tên người nhận hàng
                "customer_province": int, //id tỉnh người nhận
                "customer_province_name": string, //Tên tỉnh/TP
                "customer_district": int, //id Quận/Huyện
                "customer_district_name": string,//Tên Quận/Huyện
                "customer_wards": int, //id xã
                "customer_wards_name": string, //Tên xã
                "customer_email": string, //Email người nhận
                "customer_phone": "string", //Số điện thoại người nhận
                "customer_address_detail": string, //Địa chỉ người nhận
                "customer_note": string, //Ghi chú
                "remaining_amount": double,//Số tiền cần thanh toán còn lại
                "package_weight": double,//Khối lượng của gói hàng
                "package_length": double, //Chiều cao hàng
                "package_width": double,//Chiều rộng gói hàng
                "package_height": double,//Chiều cao gói hàng
                "description_shipper": string, //Mô tả cho shiper
                "created_at": datetime, //Ngày tạo đơn
                "updated_at": datetime,//Ngày cập nhật đơn
                "line_items_at_time": [ //Danh sách sản phẩm trong đơn
                    {
                        "id": int, //Id 
                        "quantity": int, //Số lượng
                        "name": string,//Tên sản phẩm
                        "image_url": string, //Đường dẫn ảnh
                        "item_price": double, //Giá cuối cùng
                        "price_before_override": double, //Giá cho đại lý
                        "main_price": 0, //Giá gốc
                        "before_discount_price": double, //Giá trước khi giảm giá
                        "before_discount_price_override": double, //Giá cho đại lý trước khi giảm giá
                        "after_discount": double, //Giá sau khi giảm giá
                        "after_discount_override": double,//Giá cho đại lý sau khi giảm giá
                        "distributes_selected": [ //Phân loại
                            {
                                "name": string,
                                "value": string
                            }
                        ],
                        "money_amount_collaborator": double, //hoa hồng cho CTV

                        "is_bonus": boolean, //Có phải sản phẩm thưởng hay không
                        "note": string//Ghi chú đi kèm
                    }
                   
                ],
                "partner_shipper_name": "Giao Hàng Trực Tiếp",
                "customer": {...} //Tương tự json thông tin 1 khách hàng
            }
}