Bắt đầu

Để giúp việc kết nối thuận tiện hơn, chúng tôi cung cấp thông tin cơ bản để các developers bắt đầu.

Các khái niệm cơ bản

  • API Enpoint: Đường dẫn (URL) đầy đủ có thể sử dụng để call một API. API enpoint = https://{API host}/{API path}

  • API host: Phần URL chung của tất cả các API. Như các bên phát triển khác, chúng tôi có nhiều môi trường, trong một số trường hợp chúng tôi cung cấp cho đối tác môi trường sandbox để thử nghiệm kết quả kết nối. API host sẽ khác nhau trong các môi trường

  • Access Token: Mã xác thực mỗi truy vấn API

  • HTTPS/SSL: Call API Shippo phải sử dụng giao thức được xác thực HTTPS/SSL

  • Thành công: Việc call API thành công khi kết quả trả về cùng HTTPCode 200.

  • Thất bại: Việc call API thất bại khi kết quả trả về cùng HTTPCode >= 400.

  • Webhook: Giải pháp Shippo gửi các thay đổi theo các sự kiện khi có các thay đổi dữ liệu.

API host môi trường Product

Môi trường Product là môi trường chính thức mà dịch vụ Shippo hoạt động. Sau đây là địa chỉ API host trên môi trường product:

https://apix.shippo.vn

Verify

Để gửi request call một API, Request Header của bạn phải có các thông tin sau:

  • Accept: application/json

  • Content-Type: application/json

  • Authorization: Bearer {access token}

{access token}: dùng làm biến trong một số tình huống

Ví dụ một Request Header:

  • Với access token là: 456123789e6b9ad31477ab9a744c4de7508e4cb98765432123456789

  • Vậy Header truyền lên sẽ là:

    • Accept: application/json

    • Content-Type: application/json

    • Authorization: Bearer 456123789e6b9ad31477ab9a744c4de7508e4cb98765432123456789

Kết quả trả về từ API

JSON

Tất cả API Shippo trả về với định dạng JSON

HTTPCode

API trả về mã HTTP theo các trường hợp thành công. 200 với các trường hợp thành công và từ 400 trở lên với các trường hợp thất bại. Bạn có thể tham khảo danh sách các HTTP Code tại đây

Lỗi

Khi có lỗi, Shippo trả nội dung có cấu trúc như sau:

{
"error": {
"statusCode": number, //mã lỗi
"name": string, //tên lỗi
"message": string //thông tin lỗi cụ thể
}
}

Thời gian

Hệ thống Shippo sử dụng giờ GMT và sẽ trả về các thông tin thời gian với múi giờ này. Developer chú ý đổi sang múi giờ trên hệ thống của Shop.

Ví dụ: Đơn hàng được tạo lúc 8:01 ngày 19/09 theo giờ VN sẽ được lưu trên Shippo với thời gian tạo lúc 01:01 ngày 19/09 theo giờ GMT.

Các logic cơ bản

Các logic cho phép Shop thay đổi thông tin Vận đơn: Vận đơn có trạng thái tương ứng với cột "Mã trạng thái" => Thì chỉ cho phép Shop thay đổi những thông tin Vận đơn tương ứng với cột "Các trường có thể thay đổi"

Ví dụ: Đơn hàng đang ở trạng thái Đang lấy (PICKING_UP) thì Shop có thể thay đổi những thông tin của đơn sau: merchantPrivateNote (lưu ý riêng của Shop), weight (cân nặng), insurance (giá trị bảo hiểm), cod (giá trị thu hộ COD).

Mã trạng thái

Các trường có thể thay đổi

WAITING_FOR_PICKUP (Chờ lấy)

pickupNote, receiverName, receiverPhone, deliverLocationId, deliverDetailAddress, deliveryNote, goods, shift, merchantPrivateNote, weight, insurance, cod, chargeType, state, pickupLocationId, pickupPhone, pickupContact, pickupDetailAddress

PICKING_UP (Đang lấy)

merchantPrivateNote, weight, insurance, cod.

PICKED_UP (Đã lấy)

merchantPrivateNote, cod.

WAITING_FOR_DELIVER (Chờ giao)

merchantPrivateNote

IN_TRANSFER (Trung chuyển)

merchantPrivateNote

DELIVERING (Đang giao)

merchantPrivateNote

DELIVERED (Đã giao)

merchantPrivateNote

COMPLETED (Thành công)

merchantPrivateNote

CANCELLED (Hủy)

merchantPrivateNote

REJECT (Từ chối)

merchantPrivateNote

LOST (Thất lạc)

Không cho phép thay đổi thông tin vận đơn

COD_PAID (Đã chuyển COD)

Không cho phép thay đổi thông tin vận đơn

Logic sử dụng Yêu cầu lấy (YCL)

Khi Shop tạo đơn: Nếu địa chỉ lấy của đơn chưa có trong YCL: cùng Shop, cùng địa chỉ lấy hàng, cùng ngày và nếu có YCL nào cùng địa chỉ thì trạng thái của YCL là khác NEW => Sẽ tạo ra 1 YCL mới .

Nếu Shop có YCL đang ở trạng thái NEW:

  • Shop tạo đơn có cùng địa chỉ lấy hàng, cùng ngày với YCL => Đơn mới tạo sẽ được bổ sung vào YCL đó.

  • Nếu YCL của Shop đang có nhiệm vụ đi lấy, và nhiệm vụ đó đang ở trạng thái "Nhiệm vụ mới": Shop tạo 1 đơn có cùng địa chỉ lấy hàng, cùng ngày sẽ được bổ sung vào YCL và đồng bộ đơn vừa tạo lên nhiệm vụ của Shipper trên App Shipper, để Shipper nắm được thông tin về YCL của Shop cũng như là thông tin đơn mới tạo và thực hiện lấy đơn hàng mới tạo cùng với YCL đó.

Logic YCL khi thay đổi địa chỉ của đơn hàng: Chỉ những đơn ở trạng thái Chờ lấy

  • Với YCL có 1 đơn:

    • Khi sửa địa chỉ lấy hàng của đơn thì đồng thời địa chỉ của YCL cũng được sửa tương ứng.

    • Với YCL 1 đơn đã có nhiệm vụ cho Shipper đi lấy, và nhiệm vụ đó đang ở trạng thái "Nhiệm vụ mới": Khi thay đổi địa chỉ lấy hàng của đơn sẽ có task update lên Nhiệm vụ tương ứng cho Shipper trên App Shipper để Shipper nắm thông tin địa chỉ mới thay đổi.

  • Với YCL nhiều đơn:

    • Khi sửa địa chỉ của đơn: Nếu địa chỉ mới đã thuộc 1 YCL (YCL thoã mãn điều kiện: YCL cùng địa chỉ với địa chỉ vừa được thay đổi, cùng ngày và trạng thái của YCL là New). Thì đơn mới sửa sẽ đc thêm vào YCL đó.

    • Khi thay đổi địa chỉ lấy hàng của 1 đơn (hoặc nhiều đơn), thì đơn đó sẽ được loại bỏ khỏi YCL hiện tại và tạo ra 1 YCL mới cho đơn vừa thay đổi có địa chỉ là địa chỉ vừa thay đổi (đơn cuối cùng của YCL sẽ không được chuyển sang YCL khác).

    • Với YCL nhiều đơn: Khi thay đổi địa chỉ lấy hàng của 2 (hoặc nhiều đơn) sang cùng 1 địa chỉ lấy hàng khác, thì những đơn này sẽ được loại bỏ khỏi YCL hiện tại và tạo ra 1 YCL mới chứa những đơn có cùng địa chỉ lấy hàng.

    • Với YCL nhiều đơn đã có nhiệm vụ cho Shipper đi lấy, và nhiệm vụ đó đang ở trạng thái "Nhiệm vụ mới": Khi thay đổi địa chỉ lấy hàng của 1 đơn (hoặc nhiều đơn), thì sẽ có task update lên Nhiệm vụ tương ứng cho Shipper trên App shipper, đồng thời đơn đó sẽ được loại bỏ khỏi danh sách đơn cần lấy của Shipper.

Nếu YCL đã có nhiệm vụ đi lấy cho Shipper: khi Shipper vuốt chuyển trạng thái trên App thì trạng thái của YCL và Vận đơn cũng được thay đổi tương ứng, để Shop có thể theo dõi trạng thái của Vận đơn.