Nhúng eContract vào Website (Iframe)

Tổng quan

econtractid hỗ trợ nhúng giao diện trực tiếp vào website của bên thứ ba thông qua <iframe>. Người dùng không cần rời khỏi hệ thống hiện tại mà vẫn có thể:

Xem danh sách hồ sơ / hợp đồng
Xem chi tiết và xem PDF hợp đồng
Thực hiện ký số (ký đơn giản, ký ảnh, ký Cloud HSM)
Xác thực eKYC (chụp giấy tờ, xác thực khuôn mặt)
Xử lý công việc liên quan đến hợp đồng

Ký bằng USB Token không dùng được trong iframe — xem mục Quyền cần cấp cho iframe bên dưới.

Phương thức này phù hợp cho các hệ thống muốn tích hợp nhanh giao diện econtractid mà không cần phát triển lại UI.

Luồng hoạt động

Bước 1: Lấy Access Token

Partner Login (khuyến nghị)
Login bằng Username/Password

Backend của bạn dùng API Key để lấy token cho một người dùng cụ thể — không cần mật khẩu người dùng.

POST https://api.econtractid.com/api/auth/partner-login
x-api-key: econtract_a1b2c3d4...
Content-Type: application/json

{
  "username": "john.doe",
  "tenantCode": "ACME"
}

Response trả về accessToken cùng userInfo và permission.

API Key chỉ được gọi từ backend. Không để lộ xuống trình duyệt.

Chi tiết đầy đủ: Xác thực API.

Dùng khi người dùng tự nhập tài khoản econtractid của họ.

POST https://api.econtractid.com/api/auth/login
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "your_password"
}

Phù hợp khi hệ thống bên thứ ba muốn người dùng đăng nhập bằng chính tài khoản econtractid của họ.

Trên môi trường production, Access Token có hiệu lực 15 ngày (môi trường development cấu hình dài hơn nhiều — đừng dựa vào số liệu đo trên dev). Hệ thống không có endpoint refresh token — khi token hết hạn, backend của bạn gọi lại partner-login để lấy token mới rồi cập nhật iframe.Vì thời hạn dài, hãy đối xử với token như một thông tin xác thực: không ghi log, không lưu lâu dài ở client, không để token nằm trong URL bị chia sẻ hoặc bookmark.

Xem chi tiết về xác thực và vòng đời token tại Xác thực API.

Bước 2: Tạo URL nhúng

Tạo URL truy cập econtractid kèm accessToken dưới dạng query parameter at:

https://app.econtractid.com/{đường-dẫn}?at={accessToken}

Các đường dẫn phổ biến

Đường dẫn	Mô tả
`/tasks`	Danh sách công việc cần xử lý
`/tasks?id={taskId}`	Mở thẳng một công việc để ký
`/folders`	Danh sách hồ sơ hợp đồng
`/folders?id={documentId}`	Mở thẳng một hồ sơ cụ thể
`/dashboard`	Trang tổng quan
`/document-signing`	Trang ký số

Đường dẫn không hợp lệ sẽ được tự chuyển hướng về /tasks. Khi nhúng, nên trỏ thẳng vào /tasks hoặc /folders thay vì /dashboard — người dùng cuối thường chỉ cần ký và xử lý công việc.

Với event webhook notification.*, trường signUrl đã chứa sẵn URL chi tiết theo đúng định dạng trên — dùng lại trực tiếp thay vì tự ghép chuỗi.

Ví dụ URL đầy đủ:

https://app.econtractid.com/tasks?at=eyJhbGciOiJIUzI1NiIs...
https://app.econtractid.com/folders?id=12345&at=eyJhbGciOiJIUzI1NiIs...

Để kiểm tra nhanh, bạn có thể đăng nhập hệ thống econtractid, lấy accessToken từ DevTools (Application → localStorage), sau đó mở trình duyệt mới (hoặc cửa sổ ẩn danh) và paste URL kèm accessToken để xác nhận hoạt động đúng.

Bước 3: Nhúng iframe vào website

Quyền cần cấp cho iframe

econtractid có các tính năng cần quyền thiết bị: eKYC (chụp ảnh giấy tờ, xác thực khuôn mặt) dùng camera, ký ảnh dùng chuột/cảm ứng, xem PDF toàn màn hình. Trình duyệt chặn mặc định mọi quyền thiết bị với iframe khác domain. Website nhúng phải uỷ quyền tường minh qua thuộc tính allow:

allow="camera; fullscreen; clipboard-read; clipboard-write"

Quyền	Dùng cho
`camera`	Chụp ảnh giấy tờ và xác thực khuôn mặt (eKYC)
`fullscreen`	Xem PDF hợp đồng toàn màn hình
`clipboard-read` / `clipboard-write`	Sao chép mã OTP, mã hồ sơ

Thiếu allow="camera", luồng eKYC sẽ thất bại im lặng hoặc báo lỗi không truy cập được camera — trình duyệt không hiện hộp thoại xin quyền nào cả.

Trang cha bắt buộc chạy trên HTTPS. Trình duyệt chỉ cấp quyền camera cho ngữ cảnh bảo mật. Trang cha dùng http:// (trừ localhost) sẽ không dùng được eKYC dù đã khai allow.

Nếu website của bạn có Permissions-Policy header ở tầng server, phải cho phép cả ở đó, ví dụ:

Permissions-Policy: camera=(self "https://app.econtractid.com")

Header cấp server có mức ưu tiên cao hơn — nếu nó chặn thì thuộc tính allow trên iframe không có tác dụng.

Ký bằng USB Token không hoạt động trong iframe — trình duyệt không cho plugin/extension truy cập từ iframe khác domain. Người dùng cần ký USB Token phải mở econtractid ở tab riêng, hoặc chuyển sang ký Cloud HSM / ký ảnh.

HTML thuần

<iframe
  id="econtract-frame"
  src="https://app.econtractid.com/tasks?at=YOUR_ACCESS_TOKEN"
  width="100%"
  height="800px"
  frameborder="0"
  style="border: 1px solid #ddd; border-radius: 8px; background: #fff;"
  allow="camera; fullscreen; clipboard-read; clipboard-write"
>
</iframe>

Angular

// component.ts
import { Component, OnInit } from "@angular/core";
import { DomSanitizer, SafeResourceUrl } from "@angular/platform-browser";

@Component({
  selector: "app-econtract-embed",
  template: `
    <iframe
      id="econtract-frame"
      [src]="econtractIframeSrc"
      width="100%"
      height="800px"
      frameborder="0"
      style="border: 1px solid #ddd; border-radius: 8px; background: #fff;"
      allow="camera; fullscreen; clipboard-read; clipboard-write"
    >
    </iframe>
  `,
})
export class EcontractEmbedComponent implements OnInit {
  econtractIframeSrc: SafeResourceUrl = "";

  constructor(private sanitizer: DomSanitizer) {}

  ngOnInit(): void {
    const accessToken = "eyJhbGciOiJIUzI1NiIs..."; // Lấy từ API login
    const baseUrl = "https://app.econtractid.com/tasks";
    const url = `${baseUrl}?at=${accessToken}`;
    this.econtractIframeSrc =
      this.sanitizer.bypassSecurityTrustResourceUrl(url);
  }
}

React

import React, { useState, useEffect } from "react";

function EcontractEmbed() {
  const [iframeSrc, setIframeSrc] = useState("");

  useEffect(() => {
    // Lấy token từ BACKEND của bạn — backend gọi partner-login với API Key.
    // Không bao giờ gọi trực tiếp econtractid từ trình duyệt.
    async function getToken() {
      const response = await fetch("/api/econtract-token");
      const { accessToken } = await response.json();
      setIframeSrc(`https://app.econtractid.com/tasks?at=${accessToken}`);
    }
    getToken();
  }, []);

  if (!iframeSrc) return <div>Đang tải...</div>;

  return (
    <iframe
      id="econtract-frame"
      src={iframeSrc}
      width="100%"
      height="800px"
      frameBorder="0"
      style={{
        border: "1px solid #ddd",
        borderRadius: "8px",
        background: "#fff",
      }}
      allow="camera; fullscreen; clipboard-read; clipboard-write"
    />
  );
}

export default EcontractEmbed;

Vue.js

<template>
  <iframe
    v-if="iframeSrc"
    id="econtract-frame"
    :src="iframeSrc"
    width="100%"
    height="800px"
    frameborder="0"
    style="border: 1px solid #ddd; border-radius: 8px; background: #fff;"
    allow="camera; fullscreen; clipboard-read; clipboard-write"
  />
  <div v-else>Đang tải...</div>
</template>

<script setup>
import { ref, onMounted } from "vue";

const iframeSrc = ref("");

onMounted(async () => {
  // Token lấy từ backend của bạn — backend gọi partner-login với API Key
  const response = await fetch("/api/econtract-token");
  const { accessToken } = await response.json();
  iframeSrc.value = `https://app.econtractid.com/tasks?at=${accessToken}`;
});
</script>

Xử lý sự cố

Vấn đề	Nguyên nhân	Giải pháp
Iframe hiển thị trang login	Token hết hạn hoặc không hợp lệ	Backend gọi lại `partner-login` để lấy token mới
Không mở được camera khi eKYC	Iframe thiếu quyền camera	Thêm `camera` vào `allow` của iframe
Đã khai `allow` nhưng camera vẫn lỗi	Trang cha chạy HTTP, hoặc `Permissions-Policy` ở server chặn	Chuyển trang cha sang HTTPS; kiểm tra header `Permissions-Policy`
Lỗi `Refused to display in a frame`	Domain chưa được đăng ký	Liên hệ hỗ trợ để đăng ký domain
Iframe trắng trống	CSP chặn iframe	Thêm `frame-src` vào CSP của website
Không ký được bằng USB Token	Iframe chặn plugin	Sử dụng phương thức ký Cloud HSM hoặc ký ảnh thay thế

Hỗ trợ

Nếu gặp vấn đề khi tích hợp, liên hệ đội ngũ hỗ trợ:

Email: support@econtractid.vn
Điện thoại: Liên hệ qua kênh hỗ trợ kỹ thuật

Bắt đầu

Hướng dẫn người dùng

Kỹ thuật & Tích hợp

Nhúng eContract vào Website (Iframe)

Tổng quan

Luồng hoạt động

Bước 1: Lấy Access Token

Bước 2: Tạo URL nhúng

Các đường dẫn phổ biến

Bước 3: Nhúng iframe vào website

Quyền cần cấp cho iframe

HTML thuần

Angular

React

Vue.js

Xử lý sự cố

Hỗ trợ

​Tổng quan

​Luồng hoạt động

​Bước 1: Lấy Access Token

​Bước 2: Tạo URL nhúng

​Các đường dẫn phổ biến

​Bước 3: Nhúng iframe vào website

​Quyền cần cấp cho iframe

​HTML thuần

​Angular

​React

​Vue.js

​Xử lý sự cố

​Hỗ trợ

Tổng quan

Luồng hoạt động

Bước 1: Lấy Access Token

Bước 2: Tạo URL nhúng

Các đường dẫn phổ biến

Bước 3: Nhúng iframe vào website

Quyền cần cấp cho iframe

HTML thuần

Angular

React

Vue.js

Xử lý sự cố

Hỗ trợ