Tích hợp API giao hàng website: code mẫu Node.js & Python

Tích hợp API giao hàng website: code mẫu Node.js & Python

· 24 phút đọc

Tích hợp API giao hàng vào website bán hàng là quá trình kết nối website thương mại điện tử của bạn với các đơn vị vận chuyển thông qua giao diện lập trình ứng dụng (API), cho phép tự động hóa toàn bộ các tác vụ như tính cước phí, tạo vận đơn, in nhãn, và theo dõi trạng thái đơn hàng. Với Goship API – một cổng vận chuyển đa hãng duy nhất – bạn chỉ cần một lần tích hợp là có thể chọn gửi hàng qua hơn mười hãng vận chuyển hàng đầu tại Việt Nam: GHN, GHTK, Viettel Post, VNPost, J&T Express, Ninja Van và nhiều hãng khác. Bài hướng dẫn này cung cấp code mẫu cụ thể bằng Node.js và Python cho từng endpoint quan trọng, giúp lập trình viên nhanh chóng đưa tính năng vận chuyển vào website mà không cần viết từng tích hợp riêng lẻ.

API giao hàng là gì và tại sao cần tích hợp?

API giao hàng là một tập hợp các endpoint RESTful, tuân theo giao thức HTTP, cho phép hệ thống website của bạn giao tiếp trực tiếp với hệ thống của hãng vận chuyển. Thay vì thao tác thủ công – sao chép địa chỉ người nhận, cân nặng, chọn dịch vụ trên từng app vận chuyển – bạn gửi một yêu cầu HTTP chứa dữ liệu đơn hàng và nhận về ngay một vận đơn hợp lệ, mã tracking, cùng đường dẫn in nhãn.

Sự khác biệt rất rõ giữa hai cách làm:

  • Thủ công: nhân viên phải mở nhiều phần mềm, nhập liệu lặp lại, dễ sai sót tên, số điện thoại, địa chỉ, dẫn đến hoàn hàng và chi phí phát sinh.
  • Qua API: mọi thông tin được đồng bộ từ website hoặc hệ thống quản lý đơn hàng, giảm sai sót gần như tuyệt đối, tăng tốc xử lý gấp nhiều lần.

Goship API nâng tầm trải nghiệm tích hợp bằng mô hình API đa hãng. Thay vì phải đọc tài liệu, xin key, và viết riêng một module cho từng hãng (GHN, GHTK, Viettel Post…), bạn chỉ cần khai báo một API Key của Goship và gọi đến các endpoint thống nhất. Hệ thống Goship tự động phân phối đơn đến hãng vận chuyển bạn chọn – hoặc tự động gợi ý hãng tối ưu dựa trên so sánh cước real-time. Quy trình tổng quát mà bạn sẽ thực hiện: đăng ký tài khoản tại Goship, lấy API Key, gọi Rate API để lấy bảng phí và mã rate, sau đó tạo đơn – in nhãn – tracking, và cấu hình webhook để nhận cập nhật trạng thái. Toàn bộ tài liệu và code mẫu được công bố đầy đủ tại doc.goship.io.

Lợi ích của việc tích hợp API giao hàng đa hãng

Sơ đồ trung tâm minh họa lợi ích API đa hãng của Goship: một vòng tròn trung tâm có logo Goship kết nối với các hãng GHN, Một lần tích hợp Goship API — bạn có ngay quyền truy cập vào hơn mười hãng vận chuyển. Sơ đồ hub-and-spoke này giúp lập trình viên hiểu ngay kiến trúc mà không cần đọc dòng tài liệu nào.

Sử dụng API của từng hãng riêng lẻ buộc đội ngũ phát triển phải đối mặt với nhiều vấn đề: mỗi hãng có cách xác thực khác nhau, cấu trúc request/response không đồng nhất, tài liệu thường không đầy đủ, và việc nâng cấp version tốn rất nhiều công sức. API đa hãng của Goship giải quyết triệt để những hạn chế này.

Một lần tích hợp – dùng tất cả hãng
Chỉ với một API Key, bạn có thể gửi đơn đến bất kỳ hãng nào trong mạng lưới đối tác của Goship. Khi có thêm hãng mới, bạn không cần chỉnh sửa code – Goship sẽ tự động cập nhật ở phía backend. Điều này tiết kiệm hàng chục giờ lập trình so với cách truyền thống, đồng thời giảm đáng kể chi phí bảo trì dài hạn.

Tự động so sánh cước real-time
Endpoint tính phí của Goship nhận thông tin đơn hàng (địa chỉ, khối lượng, kích thước) và trả về một bảng so sánh cước của tất cả hãng hỗ trợ, giúp bạn chọn lựa chọn rẻ nhất hoặc nhanh nhất ngay tại bước thanh toán. Nhờ đó, shop có thể tối ưu chi phí vận chuyển mà không cần tra cứu thủ công.

Quản lý tập trung
Mọi đơn hàng – dù gửi qua GHN hay Viettel Post – đều được quản lý qua một dashboard duy nhất trên Goship, hoặc bạn có thể đồng bộ trạng thái về hệ thống của mình thông qua polling hoặc webhook. Việc đối soát COD, xem tỷ lệ hoàn hàng, phân tích hiệu suất từng hãng trở nên minh bạch và thuận tiện.

Cập nhật trạng thái real-time qua webhook
Thay vì gửi request định kỳ hỏi thăm trạng thái (polling), Goship chủ động gửi cập nhật về URL mà bạn đăng ký. Khi đơn hàng chuyển từ "đang lấy hàng" sang "đang giao" hay "giao thành công", hệ thống của bạn nhận được một POST request chứa dữ liệu chi tiết, phản ứng ngay lập tức để thông báo cho khách hàng hoặc ghi nhận doanh thu.

Chuẩn bị: Đăng ký tài khoản Goship và lấy API Key

Sơ đồ quy trình 4 bước chuẩn bị tích hợp API Goship: (1) Đăng ký tài khoản tại goship.io, (2) Lấy API Key trong mục Cài đặt, Bốn bước chuẩn bị chỉ mất 5 phút — đây là phần dễ bị bỏ qua nhưng quyết định sự thành công của cả quá trình tích hợp. Infographic này giúp developer không sót bước nào trước khi bắt đầu code.

Trước khi bắt tay vào code, bạn cần hoàn tất vài bước đơn giản.

  1. Đăng ký tài khoản Goship: Truy cập goship.io, điền đầy đủ thông tin, xác thực email, số điện thoại và địa chỉ. Quá trình này giúp Goship định danh người gửi, đảm bảo đơn hàng gửi qua API hợp lệ.

  2. Lấy API Key: Sau khi đăng nhập, vào mục Tài khoản → Developer, nhấn "Xem token". Hệ thống sẽ sinh ra một chuỗi token dạng mã hoá. Hãy copy ngay và lưu trữ an toàn.

  3. Cấu hình IP whitelist (tuỳ chọn): Để tăng bảo mật, bạn có thể khai báo địa chỉ IP máy chủ của mình. Những request từ IP khác ngoài danh sách sẽ bị chặn, kể cả khi có API Key hợp lệ.

  4. Đăng ký webhook URL: Cũng trong giao diện API, bạn điền URL mà Goship sẽ gọi đến mỗi khi có cập nhật trạng thái. Đây là cách nhận tracking real‑time được khuyến nghị. Nhớ verify webhook secret trên header để xác thực callback.

Lưu ý bảo mật quan trọng: không được nhúng API Key trực tiếp vào mã nguồn, đặc biệt nếu bạn sử dụng hệ thống quản lý phiên bản như Git. Hãy dùng biến môi trường (.env) hoặc dịch vụ vault. Việc lộ key có thể dẫn đến đơn hàng giả mạo gây tổn thất nghiêm trọng.

Các endpoint API chính của Goship

Goship cung cấp các endpoint RESTful với xác thực dạng Bearer token. Danh sách endpoint cốt lõi mà bạn sẽ làm việc:

  • POST /api/v2/rates – tính cước phí vận chuyển và lấy mã rate để tạo đơn.
  • POST /api/v2/shipments – tạo vận đơn mới.
  • GET /api/v2/shipments – lấy danh sách vận đơn.
  • GET /api/v2/shipments/search?code=:id – tìm kiếm vận đơn theo mã.
  • DELETE /api/v2/shipments/:id – hủy vận đơn.
  • GET /api/v2/shipments/print/:id – In tem vận chuyển.

Mọi request đều cần gửi header Authorization: Bearer {api_key}. Base URL production là https://api.goship.io, môi trường sandbox là https://sandbox.goship.io. Bạn có thể tham khảo đầy đủ các trường tham số và ví dụ tại doc.goship.io.

Lưu ý quan trọng về luồng tạo đơn: Goship yêu cầu bạn luôn gọi Rate API trước để lấy mã rate (chuỗi Base64, ví dụ MTRfMTFfMTAwMg==). Mã này đại diện cho hãng vận chuyển + bảng giá cụ thể và là tham số bắt buộc khi tạo vận đơn. Không có cơ chế carrier: "auto" — bạn phải chọn rate từ danh sách trả về.

Tính phí vận chuyển (Rates)

Rate API là bước bắt buộc trước khi tạo đơn. Bạn gửi thông tin địa chỉ và kiện hàng, nhận về danh sách các hãng kèm cước phí, thời gian giao dự kiến và hiệu suất giao hàng. Quan trọng: địa chỉ phải dùng mã số (district_code, city_code) lấy từ API District/City, không phải chuỗi tự do.

POST https://api.goship.io/api/v2/rates

Request body:

{
  "shipment": {
    "address_from": {
      "district": "100100",
      "city": "100000"
    },
    "address_to": {
      "district": "100300",
      "city": "100000"
    },
    "parcel": {
      "cod": 350000,
      "amount": 350000,
      "width": 15,
      "height": 15,
      "length": 15,
      "weight": 250
    }
  }
}

Node.js:

const axios = require('axios');

async function getRates(rateParams) {
  const { data } = await axios.post(
    'https://api.goship.io/api/v2/rates',
    rateParams,
    { headers: { Authorization: `Bearer ${process.env.GOSHIP_API_KEY}` } }
  );
  // data.data là mảng các rate, mỗi rate có trường `rate` (Base64 ID) dùng để tạo đơn
  const rates = data.data;
  const cheapest = rates.sort((a, b) => a.total_fee - b.total_fee)[0];
  console.log(`Hãng rẻ nhất: ${cheapest.carrier_name}, phí: ${cheapest.total_fee} VND`);
  console.log(`Rate ID để tạo đơn: ${cheapest.rate}`);
  return rates;
}

// Ví dụ sử dụng
getRates({
  shipment: {
    address_from: { district: '100100', city: '100000' },
    address_to: { district: '100300', city: '100000' },
    parcel: { cod: 350000, amount: 350000, width: 15, height: 15, length: 15, weight: 250 }
  }
});

Python:

import requests
import os

api_key = os.environ['GOSHIP_API_KEY']

def get_rates(params):
    resp = requests.post(
        'https://api.goship.io/api/v2/rates',
        json=params,
        headers={'Authorization': f'Bearer {api_key}'}
    )
    if resp.ok:
        rates = resp.json()['data']
        cheapest = min(rates, key=lambda r: r['total_fee'])
        print(f"Hãng rẻ nhất: {cheapest['carrier_name']}, phí: {cheapest['total_fee']} VND")
        print(f"Rate ID để tạo đơn: {cheapest['rate']}")
        return rates
    else:
        raise Exception(resp.json().get('data', {}).get('errors'))

# Ví dụ sử dụng
get_rates({
    "shipment": {
        "address_from": {"district": "100100", "city": "100000"},
        "address_to": {"district": "100300", "city": "100000"},
        "parcel": {"cod": 350000, "amount": 350000, "width": 15, "height": 15, "length": 15, "weight": 250}
    }
})

Response mẫu mỗi rate trong mảng data:

{
  "id": "MTFfMjJfNjgzOQ==",
  "rate": "MTFfMjJfNjgzOQ==",
  "carrier_name": "Best Express",
  "carrier_short_name": "best",
  "service": "Nhanh",
  "total_fee": 19540,
  "expected": "Dự kiến giao 2 ngày",
  "cod_fee": 0,
  "return_fee": 9000,
  "report": {
    "success_percent": 88.6,
    "return_percent": 11.4,
    "avg_time_delivery": 51,
    "avg_time_delivery_format": "51H"
  }
}

Tích hợp tính phí vào website giúp khách hàng thấy chính xác chi phí giao hàng và hiệu suất từng hãng ngay tại bước thanh toán. Trường report đặc biệt hữu ích để hiển thị tỷ lệ giao thành công cho người mua tham khảo.

Tạo vận đơn mới (Create Shipment)

Sau khi có mã rate từ bước trên, bạn tạo vận đơn bằng cách gửi POST request tới /api/v2/shipments. Toàn bộ payload được wrap trong object shipment. Địa chỉ dùng mã số ward, district, city — không phải chuỗi tự do.

POST https://api.goship.io/api/v2/shipments

Request body:

{
  "shipment": {
    "rate": "MTRfMTFfMTAwMg==",
    "payer": 1,
    "order_id": "don-hang-cua-ban-001",
    "address_from": {
      "name": "Shop ABC",
      "phone": "0912345678",
      "street": "123 Nguyễn Huệ",
      "ward": "26734",
      "district": "100100",
      "city": "100000"
    },
    "address_to": {
      "name": "Nguyễn Văn B",
      "phone": "0987654321",
      "street": "51 Lê Đại Hành",
      "ward": "37",
      "district": "100300",
      "city": "100000"
    },
    "parcel": {
      "cod": 350000,
      "amount": 350000,
      "weight": "250",
      "width": "15",
      "height": "15",
      "length": "15",
      "metadata": "Áo thun, hàng dễ vỡ vui lòng nhẹ tay."
    }
  }
}

Trong đó:

  • rate: Mã rate Base64 lấy từ Rate API ở bước trên — bắt buộc
  • payer: 0 = khách trả phí ship, 1 = shop trả phí ship
  • order_id: Mã đơn hàng nội bộ của bạn (tuỳ chọn, dùng để tra cứu sau)
  • parcel.cod: Số tiền cần thu hộ (COD)
  • parcel.amount: Giá trị thực của hàng hóa (dùng để tính phí khai giá nếu > 1.000.000đ)
  • parcel.metadata: Ghi chú cho shipper

Code mẫu Node.js:

const axios = require('axios');

async function createShipment(shipmentData) {
  const response = await axios.post(
    'https://api.goship.io/api/v2/shipments',
    { shipment: shipmentData },
    {
      headers: {
        Authorization: `Bearer ${process.env.GOSHIP_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );
  return response.data;
}

const newShipment = {
  rate: 'MTRfMTFfMTAwMg==', // lấy từ Rate API
  payer: 1,
  order_id: 'don-hang-001',
  address_from: {
    name: 'Shop ABC',
    phone: '0912345678',
    street: '123 Nguyễn Huệ',
    ward: '26734',
    district: '100100',
    city: '100000',
  },
  address_to: {
    name: 'Nguyễn Văn B',
    phone: '0987654321',
    street: '51 Lê Đại Hành',
    ward: '37',
    district: '100300',
    city: '100000',
  },
  parcel: {
    cod: 350000,
    amount: 350000,
    weight: '250',
    width: '15',
    height: '15',
    length: '15',
    metadata: 'Áo thun x2',
  },
};

createShipment(newShipment)
  .then(data => console.log('Vận đơn tạo thành công:', data.id, '|', data.tracking_number))
  .catch(err => console.error(err.response?.data || err.message));

Code mẫu Python:

import requests
import os

api_key = os.environ['GOSHIP_API_KEY']
url = 'https://api.goship.io/api/v2/shipments'

shipment_data = {
    "shipment": {
        "rate": "MTRfMTFfMTAwMg==",  # lấy từ Rate API
        "payer": 1,
        "order_id": "don-hang-001",
        "address_from": {
            "name": "Shop ABC",
            "phone": "0912345678",
            "street": "123 Nguyễn Huệ",
            "ward": "26734",
            "district": "100100",
            "city": "100000"
        },
        "address_to": {
            "name": "Nguyễn Văn B",
            "phone": "0987654321",
            "street": "51 Lê Đại Hành",
            "ward": "37",
            "district": "100300",
            "city": "100000"
        },
        "parcel": {
            "cod": 350000,
            "amount": 350000,
            "weight": "250",
            "width": "15",
            "height": "15",
            "length": "15",
            "metadata": "Áo thun x2"
        }
    }
}

headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
resp = requests.post(url, json=shipment_data, headers=headers)
if resp.ok:
    result = resp.json()
    print(f"Vận đơn Goship: {result['id']}")
    print(f"Mã vận đơn hãng: {result['tracking_number']}")
    print(f"Hãng vận chuyển: {result['carrier']}")
else:
    print(resp.json())

Khi tạo đơn thành công, response trả về:

{
  "id": "GSL9VBJ2Y6",
  "shipment_status": 901,
  "shipment_status_txt": "Chờ lấy hàng",
  "cod": 350000,
  "fee": 25000,
  "tracking_number": "GA6NWFXL",
  "carrier": "Giao Hàng Nhanh (v3)",
  "carrier_short_name": "ghnv3",
  "sorting_code": "HN01-01-02",
  "amount_return_shop": 325000,
  "created_at": "13/12/2021 14:59:56"
}

Dùng id (dạng GSL9VBJ2Y6) làm định danh vận đơn Goship cho các thao tác tiếp theo. tracking_number là mã vận đơn của hãng vận chuyển để tra cứu phía khách hàng.

Một số lỗi thường gặp:

  • 422: thiếu trường bắt buộc hoặc trọng lượng/kích thước không hợp lệ — đọc trường data.errors để biết chính xác trường nào sai.
  • 401: API Key không đúng hoặc hết hạn.
  • 404: mã rate không hợp lệ hoặc đã hết hạn (rate chỉ có hiệu lực trong thời gian ngắn, cần lấy lại).

Lưu ý bất đồng bộ: Tạo vận đơn là thao tác asynchronous. Response HTTP 200 chỉ xác nhận Goship đã tiếp nhận yêu cầu. Kết quả thực tế (thành công hay lỗi từ hãng vận chuyển) sẽ được gửi qua webhook. Nếu shipment_status = 900 trong response, kiểm tra trường carrier_error để biết lý do lỗi.

In nhãn vận đơn (Print Label)

Sau khi có id vận đơn, bạn có thể lấy nhãn in. Tham khảo tài liệu tại doc.goship.io để biết endpoint in nhãn chính xác, vì có thể thay đổi theo version. Nhãn thường có thể xuất theo định dạng A4, A6, hoặc ZPL cho máy in chuyên dụng.

Node.js (ví dụ tham khảo):

const labelRes = await axios.get(
  `https://api.goship.io/api/v2/shipments/print/${shipmentId}`,
  { headers: { Authorization: `Bearer ${process.env.GOSHIP_API_KEY}` } }
);
console.log('Link in nhãn:', labelRes.data.data?.url);

Python (ví dụ tham khảo):

label_resp = requests.get(
    f'https://api.goship.io/api/v2/shipments/print/{shipment_id}',
    headers={'Authorization': f'Bearer {api_key}'}
)
if label_resp.ok:
    print(label_resp.json()['data']['url'])

Bạn có thể trả URL này cho người dùng tải về, hoặc tích hợp vào màn hình quản lý để nhân viên kho trực tiếp bấm in. Với số lượng đơn lớn, hãy cân nhắc gọi endpoint này theo batch hoặc lên lịch in tự động sau khi tạo đơn hàng loạt.

Tracking đơn hàng

So sánh hai phương pháp theo dõi đơn hàng qua API Goship: bên trái là polling với các mũi tên request liên tục gây tải cao Bạn có thể chọn polling hoặc webhook để cập nhật trạng thái đơn hàng. Sơ đồ so sánh này cho thấy webhook giúp hệ thống phản ứng tức thời khi đơn giao thành công hoặc bị hoàn, thay vì phải gửi request kiểm tra liên tục.

Có hai cách để cập nhật trạng thái:

  1. Polling: gửi GET /api/v2/shipments/search?code={id} theo chu kỳ (ví dụ mỗi 30 phút) để lấy trạng thái mới nhất. Tham số code chấp nhận id Goship, order_id của bạn, hoặc carrier_code (mã vận đơn hãng). Cách này đơn giản nhưng tạo tải liên tục lên server và chậm phản hồi.

  2. Webhook (khuyến nghị): Bạn đăng ký một URL nhận callback trong phần Cài đặt API của Goship. Mỗi khi có thay đổi trạng thái, Goship gửi POST request đến URL đó kèm theo payload: order_code, status, timestamp, reason (nếu hoàn). Để bảo mật, bạn nên kiểm tra chữ ký HMAC trong header X-Goship-Signature dựa trên webhook secret.

Ví dụ Node.js xử lý webhook (sử dụng Express):

const crypto = require('crypto');
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-goship-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  if (signature !== expected) return res.status(403).end();
  console.log(`Đơn ${req.body.order_code} chuyển sang: ${req.body.status}`);
  // cập nhật cơ sở dữ liệu
  res.status(200).end();
});

Python (Flask):

import hmac, hashlib
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Goship-Signature')
    payload = request.data
    secret = os.environ['WEBHOOK_SECRET'].encode()
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        return '', 403
    order_code = request.json['order_code']
    status = request.json['status']
    ## xử lý cập nhật
    return '', 200

Webhook giúp hệ thống của bạn luôn phản ứng tức thời khi đơn hoàn để kịp thời xử lý, hoặc khi giao thành công để tự động kích hoạt đánh giá, tính doanh thu.

Code mẫu tích hợp API với Node.js

Dưới đây là một module JavaScript mẫu gói gọn các chức năng chính, có thể sử dụng ngay trong dự án Express hoặc Next.js. Nhớ tạo file .env chứa:

GOSHIP_API_KEY=your_api_key
GOSHIP_BASE_URL=https://api.goship.io/api/v2
WEBHOOK_SECRET=your_webhook_secret

goship.js:

const axios = require('axios');

const API = axios.create({
  baseURL: process.env.GOSHIP_BASE_URL,
  headers: { Authorization: `Bearer ${process.env.GOSHIP_API_KEY}` }
});

// Lấy bảng phí và mã rate để tạo đơn
exports.getRates = async (params) => {
  const { data } = await API.post('/rates', { shipment: params });
  return data.data;
};

// Tạo vận đơn — phải truyền rate ID lấy từ getRates()
exports.createShipment = async (shipment) => {
  const { data } = await API.post('/shipments', { shipment });
  return data;
};

// In nhãn vận đơn
exports.printLabel = async (shipmentId) => {
  const { data } = await API.get(`/shipments/print/${shipmentId}`);
  return data.data?.url;
};

// Tìm kiếm / tra cứu vận đơn
exports.searchShipment = async (code) => {
  const { data } = await API.get(`/shipments/search?code=${code}`);
  return data.data;
};

Sử dụng (luồng đầy đủ):

const goship = require('./goship');

// Bước 1: Tính phí và lấy rate ID
const rates = await goship.getRates({
  address_from: { district: '100100', city: '100000' },
  address_to: { district: '100300', city: '100000' },
  parcel: { cod: 150000, amount: 150000, weight: 500, width: 15, height: 15, length: 15 }
});

// Chọn hãng rẻ nhất
const cheapest = rates.reduce((prev, curr) =>
  prev.total_fee < curr.total_fee ? prev : curr
);

// Bước 2: Tạo đơn với rate ID vừa chọn
const shipment = await goship.createShipment({
  rate: cheapest.rate,            // Base64 ID từ Rate API
  payer: 1,
  order_id: 'don-hang-001',
  address_from: {
    name: 'Shop', phone: '0912345678', street: '123 Nguyễn Huệ',
    ward: '26734', district: '100100', city: '100000'
  },
  address_to: {
    name: 'Khách', phone: '0987654321', street: '51 Lê Đại Hành',
    ward: '37', district: '100300', city: '100000'
  },
  parcel: { cod: 150000, amount: 150000, weight: '500', width: '15', height: '15', length: '15', metadata: 'Sách' }
});

// Bước 3: In nhãn
const labelUrl = await goship.printLabel(shipment.id);
console.log('Link in nhãn:', labelUrl);

Code mẫu tích hợp API với Python

Tương tự, bạn có thể tổ chức mã Python thành class để dễ quản lý. Sử dụng requests.Session để giảm overhead kết nối.

import os, requests

class GoshipClient:
    def __init__(self):
        self.base = 'https://api.goship.io/api/v2'
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {os.environ["GOSHIP_API_KEY"]}',
            'Content-Type': 'application/json'
        })

    def get_rates(self, params):
        """Lấy bảng phí. params là dict chứa address_from, address_to, parcel."""
        return self._post('/rates', {'shipment': params})

    def create_shipment(self, shipment):
        """Tạo vận đơn. shipment phải có trường rate (Base64 ID từ get_rates)."""
        return self._post('/shipments', {'shipment': shipment})

    def print_label(self, shipment_id):
        resp = self.session.get(f'{self.base}/shipments/print/{shipment_id}')
        return self._handle(resp).get('url')

    def search(self, code):
        """Tìm kiếm theo id Goship, order_id của bạn, hoặc mã vận đơn hãng."""
        resp = self.session.get(f'{self.base}/shipments/search?code={code}')
        return self._handle(resp)

    def _post(self, path, data):
        resp = self.session.post(f'{self.base}{path}', json=data)
        return self._handle(resp)

    def _handle(self, resp):
        if resp.ok:
            return resp.json().get('data')
        raise Exception(resp.json())


# Luồng đầy đủ
client = GoshipClient()

# Bước 1: Lấy bảng phí
rates = client.get_rates({
    "address_from": {"district": "100100", "city": "100000"},
    "address_to": {"district": "100300", "city": "100000"},
    "parcel": {"cod": 150000, "amount": 150000, "weight": 500, "width": 15, "height": 15, "length": 15}
})

# Chọn hãng rẻ nhất
cheapest = min(rates, key=lambda r: r['total_fee'])

# Bước 2: Tạo đơn
shipment = client.create_shipment({
    "rate": cheapest["rate"],       # Base64 ID từ Rate API
    "payer": 1,
    "order_id": "don-hang-001",
    "address_from": {
        "name": "Shop ABC", "phone": "0912345678", "street": "123 Nguyễn Huệ",
        "ward": "26734", "district": "100100", "city": "100000"
    },
    "address_to": {
        "name": "Nguyễn Văn B", "phone": "0987654321", "street": "51 Lê Đại Hành",
        "ward": "37", "district": "100300", "city": "100000"
    },
    "parcel": {"cod": 150000, "amount": 150000, "weight": "500",
               "width": "15", "height": "15", "length": "15", "metadata": "Sách"}
})

print(f"Vận đơn: {shipment['id']} | Hãng: {shipment['carrier']} | Tracking: {shipment['tracking_number']}")

# Bước 3: In nhãn
label_url = client.print_label(shipment['id'])
print(f"Link in nhãn: {label_url}")

Chú ý handling Unicode: địa chỉ tiếng Việt có dấu nên gửi dưới dạng UTF-8, thư viện requests mặc định mã hóa đúng. Nếu gặp lỗi mã hóa, đảm bảo rằng bạn đọc/ghi dữ liệu với encoding utf-8.

Xử lý lỗi và best practices

Bất kỳ tích hợp API nào cũng cần phải xử lý lỗi một cách thông minh. Dưới đây là các mã trạng thái HTTP thường gặp và cách ứng phó:

  • 400/422 Bad Request: Request thiếu hoặc sai tham số. Hãy đọc trường data.errors trong response để biết chính xác trường nào sai (ví dụ: thiếu mã quận/huyện, kích thước ngoài khoảng cho phép). Bạn nên validate dữ liệu phía client trước khi gửi.
  • 401 Unauthorized: API Key không hợp lệ hoặc đã bị thu hồi. Kiểm tra lại key và đảm bảo IP của máy chủ nằm trong whitelist (nếu bật).
  • 404 Not Found: Mã vận đơn không tồn tại, hoặc mã rate đã hết hạn — cần gọi lại Rate API để lấy rate mới.
  • 429 Too Many Requests: Vượt quá giới hạn rate limit. Hãy đọc header Retry-After (nếu có) và áp dụng exponential backoff để thử lại sau vài giây. Không nên gọi liên tục gây quá tải.
  • 5xx Server Error: Lỗi phía Goship, thường là tạm thời. Retry tối đa 3 lần với thời gian chờ tăng dần.

Best practices bảo mật:

  • Sử dụng biến môi trường hoặc secret manager, tuyệt đối không commit API Key lên git.
  • Giới hạn IP whitelist cho request tới API Goship.
  • Xác thực webhook bằng chữ ký HMAC để tránh giả mạo.

Về logging: ghi lại request/response nhưng phải che dấu API Key và dữ liệu nhạy cảm của khách hàng. Thiết lập cảnh báo qua Slack/Email khi tỉ lệ lỗi tăng cao hoặc có lỗi 5xx liên tiếp để kịp thời phản ứng.

Câu hỏi thường gặp (FAQ)

Tích hợp API giao hàng vào website bán hàng là gì?
Đó là việc sử dụng giao thức API để kết nối website TMĐT của bạn với các đơn vị vận chuyển, cho phép tự động tính phí, tạo vận đơn, in nhãn và cập nhật trạng thái đơn hàng mà không cần thao tác thủ công.

Làm thế nào để bắt đầu với Goship Shipping API?
Đăng ký tài khoản tại goship.io, lấy API Key trong mục Cài đặt → API, sau đó tham khảo tài liệu tại doc.goship.io. Với code mẫu Node.js và Python, bạn có thể gọi endpoint đầu tiên chỉ trong vài phút.

Goship API hỗ trợ những đơn vị vận chuyển nào?
Goship kết nối với hơn mười hãng lớn tại Việt Nam: GHN, GHTK, Viettel Post, VNPost, J&T Express, Ninja Van và một số hãng nội địa khác. Danh sách được cập nhật thường xuyên trên tài liệu.

Cần chuẩn bị gì để tích hợp API giao hàng?
Bạn cần một tài khoản Goship đã xác thực, kiến thức cơ bản về HTTP request và lập trình web. Bạn cũng cần lấy sẵn mã district và city từ API District/City của Goship vì địa chỉ phải dùng mã số, không phải chuỗi tự do.

Có thể tự động so sánh cước vận chuyển giữa các hãng không?
Có, endpoint POST /api/v2/rates trả về bảng so sánh cước real-time từ tất cả hãng hỗ trợ, kèm tỷ lệ giao thành công và thời gian giao trung bình. Bạn có thể lập trình để chọn ra hãng rẻ nhất hoặc giao nhanh nhất theo ngữ cảnh.

Tại sao phải gọi Rate API trước khi tạo đơn?
Goship không có cơ chế chọn hãng tự động qua tên (carrier: "auto"). Bạn phải gọi Rate API để nhận mã rate (Base64 ID đại diện cho hãng + bảng giá cụ thể), sau đó truyền mã này vào trường rate khi tạo vận đơn. Đây là bước bắt buộc.

Code mẫu tạo vận đơn bằng Node.js ở đâu?
Bạn có thể xem mã nguồn đầy đủ tại doc.goship.io. Trong bài viết này cũng có ví dụ cụ thể: gọi Rate API lấy rate ID, rồi POST tới /api/v2/shipments với payload wrap trong object shipment.

Tích hợp API giao hàng có khó không cho người mới?
Với tài liệu rõ ràng và code mẫu có sẵn từ Goship, việc tích hợp trở nên đơn giản. Điểm cần chú ý nhất là luồng hai bước: gọi Rate API trước để lấy mã rate, rồi mới tạo đơn.

Webhook tracking hoạt động như thế nào?
Sau khi bạn đăng ký URL, mỗi khi trạng thái đơn hàng thay đổi, Goship gửi một POST request đến URL đó với dữ liệu order_code, status, reason. Bạn chỉ cần xác thực chữ ký HMAC và cập nhật vào cơ sở dữ liệu.

Lợi ích của API đa hãng so với dùng API từng hãng riêng lẻ?
Chỉ cần tích hợp một lần, bạn có ngay khả năng gửi hàng qua nhiều hãng. Điều này giảm đến hàng chục giờ lập trình, hạn chế lỗi do khác biệt tài liệu, và cho phép chọn hãng tối ưu tự động giúp tiết kiệm chi phí vận chuyển.

Goship API có hỗ trợ in nhãn vận đơn không?
Có, sau khi tạo vận đơn thành công và có id Goship, bạn có thể gọi endpoint in nhãn để lấy URL file in (A4, A6, ZPL). Tham khảo doc.goship.io để biết endpoint chính xác theo version hiện tại.

Kết luận và tài liệu tham khảo

Tích hợp API giao hàng vào website bán hàng không còn là bài toán phức tạp khi bạn có một đối tác đa hãng như Goship. Chỉ với một API Key, bạn khai thác được sức mạnh của hơn mười đơn vị vận chuyển lớn, tự động hóa từ tính phí, tạo đơn, in nhãn đến tracking real-time. Điều này không chỉ tiết kiệm công sức phát triển mà còn mở ra cơ hội tối ưu chi phí và nâng cao trải nghiệm khách hàng.

Hãy đăng ký tài khoản tại goship.io ngay hôm nay để nhận API Key và bắt đầu tích hợp. Tham khảo tài liệu chi tiết tại doc.goship.io để xem schema đầy đủ, các endpoint nâng cao và cập nhật mới nhất. Để tìm hiểu thêm về so sánh phí giữa các hãng vận chuyển, bạn có thể ghé thăm công cụ so sánh phí ship của Goship. Đội ngũ hỗ trợ kỹ thuật luôn sẵn sàng đồng hành cùng bạn trong quá trình tích hợp. Bắt đầu ngay – biến website của bạn thành một cỗ máy vận hành giao hàng thông minh.

Chia sẻ bài viết này

Quay lại Blog