BelumindScience
envi

Hướng dẫn cho lập trình viên

Virgo

Một sản phẩm của Belumind · Rà soát hợp đồng tiếng Việt

Trang sản phẩm

Gửi hợp đồng tiếng Việt — PDF có chữ chọn được, tệp Word, tệp văn bản, hoặc dán thẳng nội dung — và nhận lại những điều khoản nên đọc kỹ, vị trí của chúng trên trang, và những gì nên hỏi lại bên kia. Mỗi điều khoản được kiểm tra theo chín nhóm rủi ro thường gặp, mức phạt và lãi suất được đối chiếu với giới hạn luật định, và chỗ chưa điền được đánh dấu. Kết quả chỉ là gợi ý — không thay thế luật sư và không quyết định thay bạn.

Địa chỉ cho phần mềm của bạn (API)

https://api.belumind.com/virgo

Địa chỉ cho trợ lý AI (MCP)

https://mcp.belumind.com/virgo
Đầu vào
PDF, Word, tệp văn bản hoặc nội dung dán vào
Tốc độ
~300 ms / trang

Key truy cập

Mọi yêu cầu đều gửi kèm hai thứ: API key cho sản phẩm này, tạo trong trang quản lý ở mục API key, và access token của người dùng đang đăng nhập sở hữu key đó. Token có hạn 15 phút, nên hãy làm mới và gửi token mới. Key tạo cho sản phẩm khác sẽ nhận lỗi 403 — nhờ vậy, bạn có thể giao cho trợ lý AI một key chỉ dùng được đúng một công cụ và không gì khác.

Trợ lý AI gửi cùng hai header đó khi kết nối tới địa chỉ ở trên.

contracts:analyze
Cách gửi key
X-API-Key: bm_live_7f3c…
Authorization: Bearer eyJhbGciOi…
Content-Type: application/json
POST/v1/analyzecontracts:analyze

Xem xét một tệp hợp đồng

Tách hợp đồng thành các điều khoản và trả về những điều đáng chú ý. Mỗi điều kèm nhóm rủi ro (`code`), mức độ — `doc_ky` (nên đọc kỹ) hoặc `xem_xet` (nên xem xét) — đúng câu dẫn đến gợi ý, vị trí trên trang để tô sáng, và gợi ý: nên hỏi lại gì, cần lưu ý gì, câu điều khoản có thể bổ sung. Tệp Word và tệp văn bản không có trang nên không có vị trí; PDF scan không chọn được chữ sẽ trả về rỗng, kèm ghi chú trong `document.warnings`. Gửi lại đúng tệp vừa xem sẽ có câu trả lời ngay (`cached: true`). `POST /v1/analyze/stream` nhận cùng tệp và gửi dần kết quả theo từng trang khi có, kết thúc bằng đúng kết quả này. Qua MCP, `analyze_contract` gán cho mỗi điều khoản một mã như `c3`; `get_clause` trả về toàn văn, giải thích, căn cứ pháp lý và gợi ý của điều khoản đó, dùng `analysis_id` in ở cuối kết quả phân tích.

Công cụ cho trợ lý AIanalyze_contract

Nội dung cần gửi

filefilebắt buộc
Tệp hợp đồng: PDF có chữ chọn được, Word .docx, hoặc tệp văn bản .txt / .md. Tệp .doc cũ không được nhận (lỗi 415).
include_allboolean · querytuỳ chọn
Liệt kê cả các điều khoản không có gợi ý. Mặc định tắt.
compactboolean · querytuỳ chọn
Trả câu trả lời ngắn hơn, bỏ phần giải thích dài và căn cứ pháp lý — có thể tra lại theo `code` bằng `GET /v1/risk-types`. Nhỏ hơn từ 20% đến 65%: hợp đồng càng ngắn thì càng gọn hơn. Mặc định tắt.

Kết quả nhận về

  • 200 OKThành công. Bạn nhận về đúng như ví dụ.
  • 400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
  • 401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
  • 403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
  • 402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
  • 429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
  • 500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
  • 503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api.belumind.com/virgo/v1/analyze \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -F "file=@hop_dong_lao_dong.pdf"

Bạn nhận về

application/json200 OK
{
  "version": "1.11.0",
  "model_version": "v1.11",
  "document": {
    "file_name": "hop_dong_lao_dong.pdf",
    "pages": [
      {
        "index": 0,
        "width": 595.3,
        "height": 841.9,
        "rotation": 0
      }
    ],
    "n_clauses": 2,
    "n_chars": 132,
    "is_credit_institution": false,
    "is_labour_contract": false,
    "warnings": [],
    "domain": "dieu_kien_giao_dich"
  },
  "summary": {
    "n_flagged_clauses": 1,
    "n_blank_fields": 1,
    "n_capped": 0,
    "by_risk": {
      "DON_PHUONG_CHAM_DUT": {
        "doc_ky": 1,
        "xem_xet": 0
      },
      "CHUA_DIEN": {
        "doc_ky": 0,
        "xem_xet": 1
      }
    },
    "levels": {
      "doc_ky": "Nên đọc kỹ",
      "xem_xet": "Nên xem xét"
    }
  },
  "clauses": [
    {
      "id": "c0",
      "index": 0,
      "heading": "Điều 3. Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
      "text": "Điều 3. Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
      "page_start": 0,
      "page_end": 0,
      "max_level": "doc_ky",
      "risks": [
        {
          "code": "DON_PHUONG_CHAM_DUT",
          "label": "Một bên được đơn phương chấm dứt",
          "level": "doc_ky",
          "score": 0.9035,
          "source": "model",
          "evidence": {
            "text": "Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
            "boxes": [
              {
                "page": 0,
                "x0": 72,
                "y0": 96.4,
                "x1": 523.3,
                "y1": 110.2
              }
            ]
          }
        }
      ],
      "advice": {
        "code": "DON_PHUONG_CHAM_DUT",
        "label": "Một bên được đơn phương chấm dứt",
        "level": "doc_ky",
        "card_id": "dpcd_tuy_y",
        "title": "Chấm dứt tuỳ ý, không cần lý do",
        "ask": [
          "Bên kia được chấm dứt trong những trường hợp cụ thể nào? \"Khi có nhu cầu / khi xét thấy cần thiết\" nghĩa là gì?",
          "Phải báo trước bao nhiêu ngày, bằng văn bản hay chỉ thông báo?",
          "Khi bị chấm dứt sớm, bạn được hoàn lại / bồi thường những khoản nào?"
        ],
        "notes": [
          "Quyền chấm dứt không cần căn cứ khiến thời hạn hợp đồng gần như không có giá trị bảo đảm cho bạn.",
          "Kiểm tra bạn có quyền chấm dứt tương đương không; nếu chỉ một bên có quyền thì hợp đồng đang lệch."
        ],
        "add_clause": "\"Mỗi bên chỉ được đơn phương chấm dứt Hợp đồng khi bên kia vi phạm nghĩa vụ [liệt kê] và không khắc phục trong [15] ngày kể từ ngày nhận thông báo; trường hợp chấm dứt không do lỗi của bên kia, bên chấm dứt phải báo trước [30] ngày và bồi thường thiệt hại thực tế phát sinh.\"",
        "legal_basis": "Điều 428 Bộ luật Dân sự 2015 (đơn phương chấm dứt thực hiện hợp đồng); Điều 25 Luật Bảo vệ quyền lợi người tiêu dùng 2023 (hợp đồng theo mẫu)",
        "similarity": 0.9103,
        "safe_margin": -0.0315
      }
    }
  ],
  "disclaimer": "Đây là GỢI Ý các điều khoản nên đọc kỹ, do mô hình máy học tự động đề xuất; không phải tư vấn pháp lý…"
}

Thử ngay

Thử ngay

Chế độ ví dụ
POST https://api.belumind.com/virgo/v1/analyze

Nền tảng đang trong giai đoạn truy cập sớm, nên ô này hiển thị câu trả lời mẫu thay vì liên hệ dịch vụ thật. Hãy xin chúng tôi một key và chính ô này sẽ gửi yêu cầu thật.

POST/v1/analyze/textcontracts:analyze

Xem xét nội dung hợp đồng

Cùng cách xem xét cho văn bản bạn đã có — ví dụ chép từ Word hay email, hoặc chữ đọc từ bản scan. Câu trả lời giống `/v1/analyze`, chỉ khác là không có trang: thay vào đó `char_start` / `char_end` cho biết vị trí từng phần trong văn bản của bạn. Nhận cùng tuỳ chọn `include_all` và `compact`; ví dụ dưới đây dùng `compact=true`.

Công cụ cho trợ lý AIanalyze_contract

Nội dung cần gửi

textstringbắt buộc
Toàn văn hợp đồng. Văn bản quá dài trả lỗi 413 (`text_too_large`); văn bản rỗng trả lỗi 422 (`empty_text`).
file_namestringtuỳ chọn
Tên hiển thị lại trong kết quả (`document.file_name`). Mặc định là `contract.txt`.
include_allboolean · querytuỳ chọn
Liệt kê cả các điều khoản không có gợi ý. Mặc định tắt.
compactboolean · querytuỳ chọn
Trả câu trả lời ngắn hơn, bỏ phần giải thích dài và căn cứ pháp lý — có thể tra lại theo `code` bằng `GET /v1/risk-types`. Mặc định tắt.

Kết quả nhận về

  • 200 OKThành công. Bạn nhận về đúng như ví dụ.
  • 400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
  • 401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
  • 403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
  • 402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
  • 429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
  • 500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
  • 503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api.belumind.com/virgo/v1/analyze/text \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Điều 3. Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.\nĐiều 4. Mức lương: ........ đồng/tháng.",
  "file_name": "hop_dong_lao_dong.txt"
}'

Bạn nhận về

application/json200 OK
{
  "version": "1.11.0",
  "model_version": "v1.11",
  "compact": true,
  "document": {
    "format": "text",
    "file_name": "hop_dong_lao_dong.txt",
    "pages": [],
    "n_clauses": 2,
    "n_chars": 132,
    "is_credit_institution": false,
    "is_labour_contract": false,
    "warnings": [],
    "domain": "dieu_kien_giao_dich"
  },
  "summary": {
    "n_flagged_clauses": 1,
    "n_blank_fields": 1,
    "n_capped": 0,
    "by_risk": {
      "DON_PHUONG_CHAM_DUT": {
        "doc_ky": 1,
        "xem_xet": 0
      },
      "CHUA_DIEN": {
        "doc_ky": 0,
        "xem_xet": 1
      }
    },
    "levels": {
      "doc_ky": "Nên đọc kỹ",
      "xem_xet": "Nên xem xét"
    }
  },
  "clauses": [
    {
      "id": "c0",
      "index": 0,
      "heading": "Điều 3. Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
      "text": "Điều 3. Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
      "char_start": 0,
      "char_end": 93,
      "boxes": [],
      "max_level": "doc_ky",
      "risks": [
        {
          "code": "DON_PHUONG_CHAM_DUT",
          "level": "doc_ky",
          "score": 0.9035,
          "source": "model",
          "evidence": {
            "text": "Công ty có quyền đơn phương chấm dứt hợp đồng bất cứ lúc nào mà không cần báo trước.",
            "char_start": 8,
            "char_end": 92,
            "boxes": []
          }
        }
      ]
    },
    {
      "id": "c1",
      "index": 1,
      "heading": "Điều 4. Mức lương: ........ đồng/tháng.",
      "text": "Điều 4. Mức lương: ........ đồng/tháng.",
      "char_start": 93,
      "char_end": 132,
      "boxes": [],
      "max_level": "xem_xet",
      "risks": [
        {
          "code": "CHUA_DIEN",
          "level": "xem_xet",
          "score": 1,
          "source": "rule",
          "evidence": {
            "text": "1 chỗ chưa điền: Điều 4. Mức lương: đồng/tháng.",
            "char_start": 112,
            "char_end": 120,
            "boxes": []
          }
        }
      ]
    }
  ],
  "timing_ms": 82
}

Thử ngay

Thử ngay

Chế độ ví dụ
POST https://api.belumind.com/virgo/v1/analyze/text

Nền tảng đang trong giai đoạn truy cập sớm, nên ô này hiển thị câu trả lời mẫu thay vì liên hệ dịch vụ thật. Hãy xin chúng tôi một key và chính ô này sẽ gửi yêu cầu thật.

GET/v1/risk-typescontracts:analyze

Xem tất cả nhóm rủi ro

Mọi rủi ro Virgo kiểm tra, theo `code`: tên, ý nghĩa, nên kiểm tra gì, căn cứ pháp lý để tham khảo, và hiện có đang được kiểm tra không. Dùng để bổ sung chi tiết cho câu trả lời rút gọn (`compact`). Cần cả hai thông tin xác thực nhưng không trừ credit. Ví dụ hiển thị ba trong mười ba nhóm.

Công cụ cho trợ lý AIlist_risk_types

Kết quả nhận về

  • 200 OKThành công. Bạn nhận về đúng như ví dụ.
  • 400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
  • 401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
  • 403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
  • 402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
  • 429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
  • 500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
  • 503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X GET https://api.belumind.com/virgo/v1/risk-types \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

Bạn nhận về

application/json200 OK
{
  "PHAT_VUOT_TRAN_8": {
    "label": "Mức phạt vi phạm có thể vượt 8%",
    "explanation": "Mức phạt vi phạm được nêu cao hơn 8% giá trị phần nghĩa vụ bị vi phạm. Trần 8% chỉ áp dụng cho hợp đồng thương mại; hợp đồng dân sự do các bên tự thoả thuận.",
    "suggestion": "Kiểm tra hợp đồng là thương mại hay dân sự, mức phạt tính trên giá trị nào, và bên kia có chịu mức phạt tương tự không.",
    "legal_basis": "Điều 301 Luật Thương mại 2005; Điều 418 Bộ luật Dân sự 2015",
    "enabled": true
  },
  "DON_PHUONG_CHAM_DUT": {
    "label": "Một bên được đơn phương chấm dứt",
    "explanation": "Một bên được chấm dứt/huỷ hợp đồng, khoá tài khoản hoặc ngừng dịch vụ TUỲ Ý: không cần căn cứ, căn cứ do chính bên đó tự quyết định, hoặc không báo trước/không bồi thường dù bên kia không có lỗi.",
    "suggestion": "Hỏi rõ bên kia được chấm dứt trong trường hợp nào, có báo trước bao lâu, và bạn được hoàn tiền / bồi thường gì nếu bị chấm dứt.",
    "legal_basis": "Điều 428 Bộ luật Dân sự 2015; Điều 25 Luật Bảo vệ quyền lợi người tiêu dùng 2023",
    "enabled": true
  },
  "CHUA_DIEN": {
    "label": "Chưa điền",
    "explanation": "Chỗ trống (dòng chấm, \"…\", \"____\") chưa điền thông tin — thường gặp ở mẫu hợp đồng. Đây là nhắc điền thông tin, không phải đánh giá rủi ro của điều khoản.",
    "suggestion": "Điền đầy đủ và kiểm tra lại các chỗ trống trước khi ký; không để trống để bên kia tự điền sau.",
    "legal_basis": "Điều 398 Bộ luật Dân sự 2015 (nội dung của hợp đồng)",
    "enabled": true
  }
}

Thử ngay

Thử ngay

Chế độ ví dụ
GET https://api.belumind.com/virgo/v1/risk-types

Nền tảng đang trong giai đoạn truy cập sớm, nên ô này hiển thị câu trả lời mẫu thay vì liên hệ dịch vụ thật. Hãy xin chúng tôi một key và chính ô này sẽ gửi yêu cầu thật.

Dùng với trợ lý AI

Khi kết nối với trợ lý AI, Virgo trở thành bước kiểm tra đầu tiên cho mọi hợp đồng người dùng gửi vào khung chat: trợ lý giải thích các điều khoản được đánh dấu bằng lời dễ hiểu và soạn sẵn câu hỏi cần gửi. Virgo không bao giờ kết luận một điều khoản là trái luật — chỉ ra chỗ đáng xem kỹ hơn. Virgo không mở được tệp trên máy người dùng, nên trợ lý gửi chính tệp đó hoặc đoạn văn bản được dán vào.

Bạn hỏi

“Xem giúp hợp đồng lao động này trước khi tôi ký — tôi nên hỏi lại phòng nhân sự những gì?”

Trợ lý sẽ

  1. 01Gửi tệp PDF cho Virgo xem xét
  2. 02Nhóm các điều khoản được đánh dấu theo mức: nên đọc kỹ trước, rồi nên xem xét
  3. 03Hỏi Virgo gợi ý cho từng điều khoản, rồi soạn câu hỏi tiếp theo kèm số trang
Cài đặt để dán vào trợ lý AI
{
  "mcpServers": {
    "virgo": {
      "url": "https://mcp.belumind.com/virgo",
      "headers": {
        "X-API-Key": "bm_live_7f3c…",
        "Authorization": "Bearer eyJhbGciOi…"
      }
    }
  }
}

Khi có sự cố

Khi một yêu cầu thất bại, bạn nhận được một số lỗi tiêu chuẩn và một code ngắn để phần mềm của bạn xử lý, kèm một thông báo dễ hiểu cho người đọc. Mỗi yêu cầu có thể kèm Idempotency-Key, nên gửi lại sau sự cố phía chúng tôi là an toàn — việc sẽ không bị làm hai lần.

Lỗi trông như thế nào4xx / 5xx
{
  "error": {
    "code": "invalid_parameter",
    "message": "`url` must be a reachable http(s) URL.",
    "param": "url",
    "request_id": "req_4d91c0b7"
  }
}

Sẵn sàng dùng thật?

Trong giai đoạn truy cập sớm, ô "Thử ngay" hiển thị câu trả lời mẫu. Hãy cho chúng tôi biết bạn đang xây gì, chúng tôi sẽ cấp key cho bạn.