{
 "openapi": "3.0.3",
 "info": {
  "title": "Dorabot – đổi địa chỉ và tra xã, phường cũ sau sáp nhập 2025",
  "version": "2026-11-08",
  "description": "Tra xã/phường/thị trấn cũ nay thuộc xã/phường mới nào (chép từ nghị quyết UBTVQH, miễn phí, không khoá) và đổi hàng loạt địa chỉ cũ đầy đủ sang địa chỉ mới (POST /api/v1/doi.php; không khoá 20 địa chỉ/ngày, khoá API miễn phí 100/ngày ở https://dorabot.io/dia-chi/nha-phat-trien/). Có cả máy chủ MCP: https://dorabot.io/dia-chi/mcp. Giấy phép dữ liệu CC BY 4.0, ghi nguồn: Dorabot (dorabot.io/dia-chi/sap-nhap), chép từ nghị quyết của Ủy ban Thường vụ Quốc hội.",
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/deed.vi"
  }
 },
 "servers": [
  {
   "url": "https://dorabot.io/dia-chi"
  }
 ],
 "components": {
  "securitySchemes": {
   "khoaApi": {
    "type": "http",
    "scheme": "bearer",
    "description": "Khoá dạng dk_..., tạo ở https://dorabot.io/dia-chi/nha-phat-trien/"
   }
  }
 },
 "paths": {
  "/api/v1/doi.php": {
   "post": {
    "summary": "Đổi hàng loạt địa chỉ cũ sang địa chỉ mới",
    "operationId": "doiDiaChi",
    "security": [
     {},
     {
      "khoaApi": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "addresses"
        ],
        "properties": {
         "addresses": {
          "type": "array",
          "minItems": 1,
          "maxItems": 200,
          "items": {
           "type": "string"
          },
          "description": "Địa chỉ cũ đủ phường/xã, quận/huyện, tỉnh, vd \"Số 12 ngõ 5, phường Khâm Thiên, quận Đống Đa, Hà Nội\""
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "ket_qua[] {dia_chi_cu, thanh_cong, dia_chi_moi, tin_cay {muc: cao|kiem_tra, ly_do, lua_chon}, loi}; thong_ke; han_muc",
      "content": {
       "application/json": {}
      }
     },
     "401": {
      "description": "Khoá sai hoặc đã thu hồi"
     },
     "413": {
      "description": "Quá số dòng mỗi lần"
     },
     "429": {
      "description": "Hết hạn mức ngày"
     }
    }
   }
  },
  "/sap-nhap/api/v1/tra-cuu": {
   "get": {
    "summary": "Tra một xã cũ",
    "operationId": "traCuuXaCu",
    "parameters": [
     {
      "name": "xa",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Tên xã/phường/thị trấn cũ, có hoặc không có dấu, có thể kèm loại (vd \"Phường Khâm Thiên\")"
     },
     {
      "name": "huyen",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Quận/huyện cũ (nên có vì nhiều xã trùng tên)"
     },
     {
      "name": "tinh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Tỉnh mới hoặc cũ, hoặc slug: ha-noi, ho-chi-minh, hai-phong, da-nang, hung-yen, bac-ninh, ninh-binh, thanh-hoa, an-giang, ca-mau, cao-bang, lai-chau, lang-son, hue, quang-tri, quang-ngai, khanh-hoa, gia-lai, lam-dong, dak-lak, dong-nai, tay-ninh, dong-thap, dien-bien, son-la, quang-ninh, nghe-an, ha-tinh, tuyen-quang, lao-cai, thai-nguyen, phu-tho, can-tho, vinh-long"
     }
    ],
    "responses": {
     "200": {
      "description": "Danh sách khớp (tối đa 20). ket_qua[].den = các xã mới; phan = toan_bo | mot_phan | phan_con_lai",
      "content": {
       "application/json": {}
      }
     },
     "400": {
      "description": "Thiếu tham số xa"
     }
    }
   }
  }
 }
}