←Home/Docs
⌕

Hiệu lực theo ngày (Effectivity-at-date)

Văn bản pháp luật Việt Nam thay đổi theo thời gian theo hai trục độc lập: thời điểm CrawlPipe ghi nhận thay đổi (revision, thời gian hệ thống) và thời điểm một quy định có hiệu lực pháp lý thực sự (legal_effectivity, thời gian hiệu lực). Tham số at= cho phép bạn truy vấn "luật quy định gì vào ngày cụ thể đó" — bao gồm các ngày trong quá khứ hoặc tương lai, độc lập với thời điểm CrawlPipe thu thập thay đổi. Đây là tính năng của gói Pro.

Xem văn bản tại một mốc ngày

GET /v1/legal/documents/{id}?include=units&at=2026-08-01 chú thích văn bản và từng đơn vị với trạng thái của nó vào ngày đó:

curl "https://api.crawlpipe.com/v1/legal/documents/vn:tt:2026:18:btc?include=units&at=2026-08-01" \
-H "Authorization: Bearer cp_live_a1b2c3d4e5f6…"

Phản hồi thêm trường status_at ở cấp cao nhất và status_at cho mỗi đơn vị:

{
  "document": {
    "units": [
      {
        "path": "c1.d1",
        "content": "Thông tư này quy định…",
        "status_at": "effective"
      }
    ],
    "status_at": { "date": "2026-08-01", "status": "effective" }
  }
}

natural_key (ví dụ vn:tt:2026:18:btc), UUID của bản ghi, hoặc doc_number đã chuẩn hóa đều dùng được cho {id}.

Toàn bộ mốc thời gian (Timeline)

GET /v1/legal/documents/{id}/effectivity (1 đơn vị; tham số at trên endpoint này cũng yêu cầu gói Pro) trả về toàn bộ lịch sử dưới dạng chuỗi các khoảng hiệu lực, bao gồm cả các sửa đổi trong tương lai chưa có hiệu lực:

{
  "effectivity": [
    { "unit_path": null, "status": "not_yet_effective", "valid_from": "2026-05-12", "valid_to": "2026-06-30", "caused_by": null },
    { "unit_path": null, "status": "effective", "valid_from": "2026-07-01", "valid_to": null, "caused_by": null },
    {
      "unit_path": "d3.k2",
      "status": "amended",
      "valid_from": "2026-09-01",
      "valid_to": null,
      "caused_by": { "record_id": "…", "doc_number": "45/2026/TT-BTC", "relation_type": "sua_doi_bo_sung" }
    }
  ]
}

unit_path mang giá trị null mô tả toàn bộ văn bản; các đường dẫn cụ thể mô tả sửa đổi áp dụng cho một khoản/điều. caused_by trỏ tới văn bản sửa đổi để bạn có thể theo dõi chuỗi thay đổi.

Tại sao điều này quan trọng

Tích hợp thông thường luôn đọc văn bản "hiện tại" sẽ vô tình cung cấp nội dung đã hết hạn hoặc chưa có hiệu lực xung quanh ngày có hiệu lực của một sửa đổi. Hãy dùng at= để cố định ngày chính xác liên quan đến trường hợp của bạn — ví dụ: ngày trên hóa đơn trong đồng bộ kế toán, hoặc "ngày hôm nay" theo giờ Việt Nam — thay vì bất kỳ văn bản nào đang là hiện tại khi gọi API.

Giới hạn theo gói

Tham số at= trên cả hai endpoint sẽ trả về lỗi 403 feature_not_in_plan (details.required_plan: "pro") ở gói Miễn phí và Builder. Khi không truyền at=, cả hai endpoint hoạt động trên mọi gói và trả về dữ liệu trạng thái hiện tại.

Hiệu lực theo ngày (Effectivity-at-date) — CrawlPipe Docs