Tích hợp eNotary vào hệ thống của bạn

Tạo bộ mới. File gửi ngay trong JSON, dưới dạng base64 hoặc url. Bộ vừa tạo ở trạng thái READY và hiện ngay cho Phòng công chứng.

Body

Mỗi phần tử trong files

Ví dụ yêu cầu

curl -X POST "https://api-dev.enotaryid.com/api/integration/documents" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "HD-2026-001",
  "ecmClassCode": "shared-notary-set",
  "customerName": "Nguyễn Văn A",
  "customerIdCode": "079123456789",
  "contractType": "Công chứng mua bán nhà đất",
  "notaryRequestAt": "2026-10-15T08:00:00.000Z",
  "files": [
    {
      "type": "base64",
      "base64Data": "JVBERi0xLjQK...",
      "fileName": "cccd.pdf",
      "code": "FILE-A",
      "title": "CCCD bản sao"
    },
    {
      "type": "url",
      "url": "https://files.example.vn/hop-dong.pdf",
      "fileName": "hop-dong.pdf",
      "code": "FILE-B",
      "title": "Hợp đồng"
    }
  ]
}'

{
  "statusCode": 200,
  "data": {
    "id": 1001,
    "code": "NS-26-000042",
    "externalCode": "HD-2026-001",
    "uuid": "3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34",
    "ecmClassId": 21,
    "ecmClassName": "Bộ tài liệu công chứng chia sẻ",
    "documentType": 17,
    "partnerStatus": "READY",
    "signStatus": "NOT_SIGNED",
    "status": 1,
    "files": [
      {
        "id": 2001,
        "uuid": "9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12",
        "code": "NS-26-000042.1",
        "externalCode": "FILE-A",
        "fileName": "cccd.pdf",
        "title": "CCCD bản sao",
        "documentType": 13,
        "section": "ORIGINAL",
        "status": 1,
        "size": 12345,
        "mimeType": "application/pdf"
      },
      {
        "id": 2002,
        "uuid": "b47a0e63-8c15-4f2d-93be-1d6a7c2e5f08",
        "code": "NS-26-000042.2",
        "externalCode": "FILE-B",
        "fileName": "hop-dong.pdf",
        "title": "Hợp đồng",
        "documentType": 13,
        "section": "ORIGINAL",
        "status": 1,
        "size": 54321,
        "mimeType": "application/pdf"
      }
    ],
    "createdAt": "2026-10-12T08:00:00.000Z",
    "metadata": { "tenantCode": "ORG-DEMO" }
  },
  "timestamp": "2026-10-12T08:00:00.000Z"
}

Các trường trong phản hồi

Lỗi thường gặp

{
  "message": "A shared set with code \"HD-2026-001\" already exists for this organization",
  "existingId": 1001
}

Muốn gửi lại an toàn khi bị mất kết nối: gọi chi tiết bộ theo ?code= trước. Nếu đã có bộ thì dùng luôn, không tạo lại.

Giống 4.1 nhưng gửi file trực tiếp bằng multipart/form-data. Phù hợp khi file lớn hoặc bạn không muốn mã hóa base64. Cần tài khoản đối tác như 4.1.

Các trường form

Ví dụ yêu cầu

curl -X POST "https://api-dev.enotaryid.com/api/integration/documents/upload" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -F "code=HD-2026-002" \
  -F "customerName=Trần Thị B" \
  -F "files=@cccd.pdf" \
  -F "files=@hop-dong.pdf" \
  -F 'titles=["CCCD bản sao", "Hợp đồng"]' \
  -F 'codes=["FILE-A", "FILE-B"]'

Giống hệt 4.1. Lỗi cũng giống, thêm hai lỗi riêng của upload: 413 khi một file quá 150 MB, và 400 khi file không phải PDF (ví dụ Route này chỉ nhận: pdf).

Liệt kê các bộ của Phòng công chứng bạn, mới nhất trước. Có phân trang và bộ lọc. Tất cả tham số đều không bắt buộc.

Tham số query

Tham số signStatus được nhận nhưng hiện chưa có tác dụng lọc.

Ví dụ yêu cầu

curl -G "https://api-dev.enotaryid.com/api/integration/documents" \
  -H "X-API-Key: enk_xxxxxxxx" \
  --data-urlencode "codeLike=HD-2026" \
  --data-urlencode "partnerStatus=READY" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20"

{
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": 1001,
        "code": "NS-26-000042",
        "externalCode": "HD-2026-001",
        "uuid": "3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34",
        "ecmClassId": 21,
        "ecmClassName": "Bộ tài liệu công chứng chia sẻ",
        "customerName": "Nguyễn Văn A",
        "customerIdCode": "079123456789",
        "partnerStatus": "READY",
        "signStatus": "NOT_SIGNED",
        "fileCount": 2,
        "createdAt": "2026-10-12T08:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "metadata": { "tenantCode": "ORG-DEMO" }
  },
  "timestamp": "2026-10-12T08:05:00.000Z"
}

Các trường của mỗi phần tử

Xem một bộ kèm toàn bộ file và liên kết tải. Gửi một trong ba tham số. Nếu gửi nhiều, thứ tự ưu tiên là id, rồi uuid, rồi code. Không gửi cái nào thì 400. Bộ không tồn tại hoặc thuộc đơn vị khác thì 404.

Tham số query

Ví dụ yêu cầu

curl -G "https://api-dev.enotaryid.com/api/integration/documents/detail" \
  -H "X-API-Key: enk_xxxxxxxx" \
  --data-urlencode "code=HD-2026-001"

{
  "statusCode": 200,
  "data": {
    "id": 1001,
    "code": "NS-26-000042",
    "externalCode": "HD-2026-001",
    "uuid": "3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34",
    "ecmClassId": 21,
    "ecmClassName": "Bộ tài liệu công chứng chia sẻ",
    "documentType": 17,
    "partnerStatus": "READY",
    "signStatus": "NOT_SIGNED",
    "customerName": "Nguyễn Văn A",
    "customerIdCode": "079123456789",
    "contractType": "Công chứng mua bán nhà đất",
    "assetInfo": null,
    "notaryRequestAt": "2026-10-15T08:00:00.000Z",
    "files": [
      {
        "id": 2001,
        "uuid": "9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12",
        "code": "NS-26-000042.1",
        "externalCode": "FILE-A",
        "fileName": "cccd.pdf",
        "title": "CCCD bản sao",
        "documentType": 13,
        "section": "ORIGINAL",
        "status": 1,
        "size": 12345,
        "downloadUrl": "https://storage.example/presigned-link?X-Amz-Signature=...",
        "signUrl": "https://storage.example/presigned-link?X-Amz-Signature=..."
      }
    ],
    "createdAt": "2026-10-12T08:00:00.000Z",
    "completedAt": null,
    "metadata": { "tenantCode": "ORG-DEMO" }
  },
  "timestamp": "2026-10-12T08:10:00.000Z"
}

Các trường trong phản hồi

Đẩy thêm file vào một bộ đã tạo. Hay dùng để gửi bản đã ghép và đã ký của bạn (xem luồng tự ghép lời chứng), hoặc bổ sung văn bản gốc cho bộ rỗng. Cần tài khoản đối tác.

Tham số đường dẫn

Body

Bạn không thể tự gửi vào khối "Lời chứng" hay "Đã ký (kết quả)". API cũng không nhận documentType dạng số.

Ví dụ yêu cầu

curl -X POST "https://api-dev.enotaryid.com/api/integration/documents/3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34/files" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "fileType": "SIGNED",
  "files": [
    {
      "type": "url",
      "url": "https://files.example.vn/hop-dong-da-ky.pdf",
      "fileName": "hop-dong-da-ky.pdf",
      "code": "HD-2026-001-SIGNED"
    }
  ]
}'

data là một mảng các file vừa thêm.

{
  "statusCode": 200,
  "data": [
    {
      "id": 2003,
      "uuid": "c58d2f91-4e07-4a6b-8d13-7f0e9b3a6c45",
      "code": null,
      "externalCode": "HD-2026-001-SIGNED",
      "fileName": "hop-dong-da-ky.pdf",
      "title": "hop-dong-da-ky.pdf",
      "documentType": 16,
      "section": "SIGNED",
      "status": 1,
      "size": 204800,
      "downloadUrl": "https://storage.example/presigned-link?X-Amz-Signature=...",
      "signUrl": "https://storage.example/presigned-link?X-Amz-Signature=..."
    }
  ],
  "timestamp": "2026-10-12T09:00:00.000Z"
}

Lỗi thường gặp

Bản multipart/form-data của 5.1. Cùng quy tắc, giới hạn và mã lỗi. uuid trong đường dẫn vẫn là uuid của bộ.

Các trường form

Ví dụ yêu cầu

curl -X POST "https://api-dev.enotaryid.com/api/integration/documents/3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34/files/upload" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -F "fileType=SIGNED" \
  -F "files=@hop-dong-da-ky.pdf" \
  -F 'codes=["HD-2026-001-SIGNED"]'

Giống 5.1: data là mảng file vừa thêm. Thiếu file thì 400 At least one file is required. fileType sai thì 400 fileType must be one of: ORIGINAL, SIGNED, MERGED.

Xem thông tin một file (không tải nội dung), kèm tóm tắt bộ chứa nó. Gửi một trong ba tham số. Thứ tự ưu tiên: uuid, rồi code, rồi externalCode.

Tham số query

Ví dụ yêu cầu

curl -G "https://api-dev.enotaryid.com/api/integration/files/detail" \
  -H "X-API-Key: enk_xxxxxxxx" \
  --data-urlencode "externalCode=FILE-A"

{
  "statusCode": 200,
  "data": {
    "id": 2001,
    "uuid": "9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12",
    "code": "NS-26-000042.1",
    "externalCode": "FILE-A",
    "fileName": "cccd.pdf",
    "title": "CCCD bản sao",
    "documentType": 13,
    "section": "ORIGINAL",
    "status": 1,
    "size": 12345,
    "mimeType": "application/pdf",
    "downloadUrl": "https://storage.example/presigned-link?X-Amz-Signature=...",
    "signUrl": "https://storage.example/presigned-link?X-Amz-Signature=...",
    "sharedSet": {
      "id": 1001,
      "uuid": "3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34",
      "code": "NS-26-000042",
      "externalCode": "HD-2026-001",
      "customerName": "Nguyễn Văn A"
    },
    "metadata": { "tenantCode": "ORG-DEMO" }
  },
  "timestamp": "2026-10-12T09:10:00.000Z"
}

Các trường của file giống mục 4.1, thêm downloadUrl và signUrl (liên kết tải có thời hạn, mặc định 7 ngày). sharedSet là tóm tắt bộ chứa file. 400 khi không gửi tham số nào, 404 File not found khi không thấy hoặc thuộc đơn vị khác.

Tải nội dung file. Phản hồi là dữ liệu file thô (không có phong bì JSON). Luôn là phiên bản mới nhất: nếu file đã ký xong, bạn nhận bản đã ký.

Tham số đường dẫn

Ví dụ yêu cầu

curl -L "https://api-dev.enotaryid.com/api/integration/files/9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12/download" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -o ket-qua.pdf

Header Content-Type theo loại file, Content-Disposition: attachment; filename="…" (tên file được mã hóa URL). Thân phản hồi là các byte của file.

Lỗi thường gặp

Lấy luồng trao đổi của một bộ, cũ nhất trước.

curl "https://api-dev.enotaryid.com/api/integration/documents/3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34/comments?page=1&pageSize=50" \
  -H "X-API-Key: enk_xxxxxxxx"

{
  "statusCode": 200,
  "data": {
    "rows": [
      {
        "id": 8890,
        "content": "<p>Nhờ bổ sung CCCD mặt sau.</p>",
        "contentHtml": "<p>Nhờ bổ sung CCCD mặt sau.</p>",
        "createdAt": "2026-09-30T07:30:00.000Z",
        "author": { "type": "ORG", "name": "Nguyễn Văn A" }
      },
      {
        "id": 8892,
        "content": "Đã bổ sung **CCCD mặt sau**.\n\n- Nhờ phòng kiểm tra giúp\n- Cảm ơn",
        "contentHtml": "<p>Đã bổ sung <strong>CCCD mặt sau</strong>.</p>\n<ul>\n<li>Nhờ phòng kiểm tra giúp</li>\n<li>Cảm ơn</li>\n</ul>",
        "createdAt": "2026-10-12T08:00:00.000Z",
        "author": { "type": "API", "name": "Đối tác A" }
      }
    ],
    "count": 2
  },
  "timestamp": "2026-10-12T08:01:00.000Z"
}

Phần tử đầu là một trao đổi cũ (viết trước 12/10/2026): content là HTML đã lưu từ trước. Hiển thị thì luôn dùng contentHtml. Xem đối tượng comment.

Gửi một trao đổi mới lên bộ.

Body

curl -X POST "https://api-dev.enotaryid.com/api/integration/documents/3f2b8c1e-7a4d-4e5f-9b21-0c6d8e1a2f34/comments" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Đã bổ sung **CCCD mặt sau**.\n\n- Nhờ phòng kiểm tra giúp\n- Cảm ơn"}'

{
  "statusCode": 200,
  "data": {
    "id": 8892,
    "content": "Đã bổ sung **CCCD mặt sau**.\n\n- Nhờ phòng kiểm tra giúp\n- Cảm ơn",
    "contentHtml": "<p>Đã bổ sung <strong>CCCD mặt sau</strong>.</p>\n<ul>\n<li>Nhờ phòng kiểm tra giúp</li>\n<li>Cảm ơn</li>\n</ul>",
    "createdAt": "2026-10-12T08:00:00.000Z",
    "author": { "type": "API", "name": "Đối tác A" }
  },
  "timestamp": "2026-10-12T08:00:00.000Z"
}

Lấy luồng trao đổi riêng của một file. Hỗ trợ page và pageSize như 6.1.

curl "https://api-dev.enotaryid.com/api/integration/files/9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12/comments" \
  -H "X-API-Key: enk_xxxxxxxx"

Gửi trao đổi về đúng một file. Body: { "content": "…" } như 6.1.

curl -X POST "https://api-dev.enotaryid.com/api/integration/files/9d1e5c70-2b3a-4c88-a6f1-5e7b0d4c9a12/comments" \
  -H "X-API-Key: enk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "File này em gửi nhầm bản cũ, nhờ phòng **bỏ qua** giúp."}'