Dorabot – Vietnam address after 2025 merger

@dorabot-io/dia-chi

适用于 JavaScript / TypeScript 的2025 年合并后越南行政区划：34 个省、3,321 个新社/坊/特区、根据国会常务委员会决议（附条款编号）将 11,559 个旧社映射到新社的对照表，以及适用于 React 的二级地址选择表单。

自 2025 年 7 月 1 日起，越南地址仅有2 级：社/坊/特区 → 省/直辖市。**不再有郡/县。**三级表单（省 → 县 → 社）已过时。

npm i @dorabot-io/dia-chi

离线运行，无需密钥，不调用网络（doiDiaChi 除外）。支持 Node ≥ 18、浏览器、Vite、Next.js、Bun、Deno、Cloudflare Workers。

快速使用

import { tinh, xa, timXaCu, kiemDiaChi, doiDiaChi } from '@dorabot-io/dia-chi';

tinh();                 // 34 tỉnh/thành: { slug, tenDayDu, gomTinhCu, nghiQuyet, soXa }
xa('ha-noi');           // xã/phường mới của Hà Nội (nhận cả "Hà Nội", "Thái Bình" → Hưng Yên)

await timXaCu('Bách Khoa', { huyen: 'Hai Bà Trưng', tinh: 'Hà Nội' });
// [{ xaCu: 'Phường Bách Khoa', huyenCu: 'Quận Hai Bà Trưng', den: [{ tenDayDu: 'Phường Bạch Mai', phan: 'toan_bo', khoan: 8 }],
//    nghiQuyet: { so: '1656/NQ-UBTVQH15', hieu_luc: '2025-07-01', url: '…' } }]

await kiemDiaChi('12 Tạ Quang Bửu, phường Bách Khoa, quận Hai Bà Trưng, Hà Nội');
// { trangThai: 'dia_chi_cu', lyDo: 'Còn cấp quận/huyện …' }   ← dùng ở bước kiểm form / nhập dữ liệu
await kiemDiaChi('12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội');
// { trangThai: 'hop_le', diaChiChuan: '12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội' }

// Đổi địa chỉ đầy đủ, chuỗi lộn xộn/viết tắt (gọi API dorabot.io):
await doiDiaChi('12 Tạ Quang Bửu, P. Bách Khoa, Q. Hai Bà Trưng, HN');
// { thanh_cong: true, dia_chi_moi: '12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội', tin_cay: { muc: 'cao' } }
await doiDiaChi([...5000DiaChiKhachHang], { apiKey: process.env.DORABOT_API_KEY }); // tối đa 200/lần

doiDiaChi 无需密钥：每天每个 IP 可调用 20 次。免费密钥 dk_…（每天 100 次，使用 Google 登录）：https://dorabot.io/dia-chi/nha-phat-trien/ — 企业批量转换套餐：https://dorabot.io/dia-chi/doanh-nghiep/

二级地址选择表单（React）

import { ChonDiaChi } from '@dorabot-io/dia-chi/react';

<ChonDiaChi
  choDoiDiaChiCu            // thêm ô "dán địa chỉ cũ để đổi"
  onChange={(v) => setForm({ ...form, tinh: v.tinh, xa: v.xa, diaChi: v.diaChi })}
  selectClassName="border rounded px-2 py-1"
/>

不依赖 UI 库（使用 2 个 <select> 标签）。在数据库中保存省份 slug 和社 slug，显示 tenDayDu。

在数据库中保存

-- địa chỉ mới: 2 cấp
dia_chi_chi_tiet text,      -- số nhà, đường, thôn/xóm
xa_slug   text,             -- 'phuong-bach-mai'
tinh_slug text              -- 'ha-noi'
-- giữ cột địa chỉ cũ (nếu có) để đối chiếu, đừng xoá ngay

其他功能

• MCP，适用于 Claude / ChatGPT / Cursor：https://dorabot.io/dia-chi/mcp（工具 tra_cuu_xa_cu、doi_dia_chi、kiem_dia_chi、danh_sach_xa_moi、danh_sach_tinh）。
• REST：POST https://dorabot.io/dia-chi/api/v1/doi.php {"addresses": [...]} — OpenAPI 文档见开发者页面。
• Python：pip install dorabot-dia-chi。
• 开放数据 CSV/JSON：https://github.com/Dorabot-io/sap-nhap-2025
• 手动查询、转换 Excel 文件：https://dorabot.io/dia-chi/

许可证

代码采用 MIT 许可证。数据采用 CC BY 4.0 许可证 — 请在应用或文档中的某处注明来源“Dorabot (dorabot.io)”（React 组件已附带小字来源说明；如果你在其他地方注明来源，可通过 ghiNguon={false} 关闭）。

数据摘录自 2025 年各省关于调整社级行政单位的国会常务委员会决议，以及第 202/2025/QH15 号决议。如发现错误，请联系 [email protected] 或提交 issue。

Dorabot (dorabot.io) 是越南的一款工具，与深圳的机器人公司 Dorabot (dorabot.com) 无关。

---

English. 越南 2025 年 7 月 1 日合并后的行政区划（34 个省，2 级：社/坊 → 省，无县）。提供离线省份列表和 3,321 个新社、将 11,559 个旧社映射到新社并附官方决议条款的对照表、新格式地址验证器、React 二级地址选择器，以及调用 dorabot.io API 将完整的旧格式自由文本地址转换为新地址的 doiDiaChi()。代码采用 MIT 许可证，数据采用 CC BY 4.0 许可证。

本仓库内容

• js/ — npm 包 @dorabot-io/dia-chi（以及 /react）
• python/ — PyPI 包 dorabot-dia-chi
• vi-du/ — React/Vite 示例、Node CSV 文件转换、Python Excel、PHP/Laravel、Flutter
• 完整 CSV/JSON 数据：https://github.com/Dorabot-io/sap-nhap-2025