Lấy danh sách phường / xã hệ mới theo tỉnh

v3.master-data.ward.all-by-province-id

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

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 phường / xã của một tỉnh theo địa giới MỚI 2 cấp (không còn quận / huyện). name gửi nguyên văn vào to_ward_name khi tạo / xem trước đơn với is_new_to_address = true.

province_id sai hoặc thiếu vẫn trả HTTP 200 / code 200 nhưng data = null — coi data rỗng là sai mã tỉnh.
Khớp tên địa chỉ khách nhập: so với name trước, không trùng thì so với extension_names (bỏ tiền tố Phường / Xã / Thị trấn); chỉ nhận khi khớp DUY NHẤT một mục.

Request

Địa chỉ

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

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ả
province_id	query	int	Có	1000001	Mã tỉnh hệ 2 cấp (`_id` của API tỉnh / thành mới).
offset	query	int	Không	0
limit	query	int	Không	200	Tối đa 200 — tỉnh nhiều phường / xã nhất (TP. Hồ Chí Minh, 168) vẫn đủ trong một lần.

Ví dụ request

curl -s "https://partner.quantri360.com/v1/ghn/shiip/public-api/v3/master-data/ward/all-by-province-id?province_id=1000001&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/ward/all-by-province-id",
    params={
        "province_id": 1000001,
        "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/ward/all-by-province-id');
for (const [k, v] of Object.entries({"province_id":1000001,"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/ward/all-by-province-id' . '?' . http_build_query(['province_id' => 1000001, '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[]		Phường / xã; `null` khi province_id sai hoặc thiếu.
_id	int	1003646	Mã phường / xã hệ 2 cấp.
name	string	Phường Vũng Tàu	Tên chuẩn — dùng nguyên văn cho `to_ward_name`.
extension_names	string[]	["vung tau","p.vũng tàu"]	Các cách viết khác để khớp địa chỉ.
type	string	ward
parent_id	int	1000001	Mã tỉnh chứa phường / xã.
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": 1003646,
      "name": "Phường Vũng Tàu",
      "extension_names": [
        "phường vũng tàu",
        "p.vũng tàu",
        "vũng tàu",
        "vung tau",
        "phuong vung tau"
      ],
      "type": "ward",
      "parent_id": 1000001,
      "status": 1
    }
  ]
}

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

Bấm để xem

Mã	Ý nghĩa
Authorization header is required!	401 — Thiếu Token
data là null	200 — province_id thiếu hoặc không tồn tại (API không trả lỗi riêng)
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

Lấy danh sách phường / xã hệ mới theo tỉnh — API GHN