Tỉnh / thành hệ mới (34) — API GHN

v3.master-data.province.all

GET/shiip/public-api/v3/master-data/province/allGọi qua 360: GET https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all

Sắp mở. API này đã chạy thật qua 360 và đang được chốt giá — bạn có thể đọc tài liệu và chuẩn bị tích hợp trước.

Mô tả API

Danh sách tỉnh / thành theo địa giới MỚI 2 cấp (34 tỉnh, sau sắp xếp hành chính 01/07/2025). name là giá trị gửi nguyên văn vào to_province_name khi tạo / xem trước đơn với is_new_to_address = true; _id dùng để lấy phường / xã.

Danh mục ít đổi — lấy một lần rồi lưu (khoảng 24 giờ).
Đơn còn dùng địa chỉ cũ 3 cấp (có quận / huyện) thì gửi tên theo danh mục cũ với is_new_to_address = false, không dùng danh mục này.

Request

Địa chỉ

GET https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all

Xác thực & gian hàng

Tên	Vị trí	Kiểu	Mẫu	Mô tả
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	196560	ShopId GHN đã nối (GET /v1/platforms). Mỗi brand một cửa hàng — có thể bỏ. `shop_id` trong body (vd available-services) phải trùng.

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mẫu	Mô tả
offset	query	int	Không	0	Vị trí bắt đầu. Mặc định 0.
limit	query	int	Không	200	Tối đa 200; bỏ trống hoặc 0 = lấy tất cả (34 tỉnh — một lần là đủ).

Ví dụ request

curl -s "https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all?offset=0&limit=200" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all",
    params={
        "offset": 0,
        "limit": 200
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all');
for (const [k, v] of Object.entries({"offset":0,"limit":200})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/province/all' . '?' . http_build_query(['offset' => 0, 'limit' => 200]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Tham số phản hồi (nguyên của GHN)

Tên	Kiểu	Mẫu	Mô tả
code	int	200	200 = thành công.
message	string	Success
data	object[]		Tỉnh / thành.
_id	int	1000001	Mã tỉnh hệ 2 cấp — gửi vào `province_id` của API phường / xã mới.
name	string	Hồ Chí Minh	Tên chuẩn — dùng nguyên văn cho `to_province_name`.
extension_names	string[]	["hcm","ho chi minh"]	Các cách viết khác (không dấu, viết tắt, có tiền tố) — dùng để khớp địa chỉ khách gõ tự do.
type	string	province
parent_id	int	1	Quốc gia (Việt Nam = 1).
status	int	1	1 hoạt động · 2 ngừng · 10 đã xóa.

Mẫu phản hồi

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "_id": 1000001,
      "name": "Hồ Chí Minh",
      "extension_names": [
        "hồ chí minh",
        "tp.hồ chí minh",
        "thành phố hồ chí minh",
        "hcm",
        "ho chi minh"
      ],
      "type": "province",
      "parent_id": 1,
      "status": 1
    }
  ]
}

Mã lỗi của GHN (4)

Bấm để xem

Mã	Ý nghĩa
Authorization header is required!	401 — Thiếu Token
limit tối đa chỉ được 200	400 — limit vượt quá 200
IP không được phép	401 — Tài khoản của bạn có whitelist IP và request đến từ IP khác
SERVER_ERROR_COMMON	500 — Lỗi hệ thống

Bắt đầu dùng

Đăng ký tài khoản Partner
Mở loại dữ liệu thuộc nhóm Danh mục & cửa hàng ở trang nền tảng
Tạo API key (tick kênh GHN)
Gọi theo ví dụ ở trên