# API v1 của Số Định Danh

URL chuẩn: https://sodinhdanh.com/api

OpenAPI: https://sodinhdanh.com/api/v1/openapi.json

- GET /api/v1/entries: Nội dung đã xuất bản, kèm nguồn
- GET /api/v1/entries/{kind}/{slug}: Chi tiết nội dung công khai
- GET /api/v1/administrative-units: Tra cứu bộ mẫu mã hành chính
- POST /api/v1/validate: Kiểm tra định dạng, không xác thực danh tính
- GET /api/v1/mapsviet/businesses/{taxCode}: Doanh nghiệp công khai từ MapsViet
- GET /api/health: Kiểm tra DB và schema

## Phạm vi và giới hạn

Nội dung chỉ là các mục đã xuất bản. Mã hành chính là bộ mẫu không đầy đủ. Kiểm tra định dạng không xác thực danh tính hay trạng thái cấp mã. MapsViet trả 503 nếu chưa cấu hình; không giả lập dữ liệu.

60 yêu cầu/phút cho nội dung và mã hành chính; 30 cho kiểm tra; 15 cho MapsViet. Lỗi 429 có Retry-After. Không bật CORS mặc định.

Mã đầu vào của API được xử lý tạm thời qua POST, không lưu hoặc phản chiếu. Giao diện công cụ xử lý ngay trên thiết bị. Không đưa số định danh vào URL.

## Ví dụ với mã hành chính công khai

GET /api/v1/administrative-units?code=01

POST /api/v1/validate với Content-Type: application/json và nội dung:

```json
{
  "kind": "province",
  "value": "01"
}
```