Các biểu mẫu trực tuyến không chỉ để thu thập dữ liệu — khi được tích hợp bằng API, chúng trở thành “động cơ” giúp dữ liệu di chuyển thông suốt giữa CRM, ERP, ứng dụng nội bộ và bảng điều khiển phân tích. Bài viết này hướng dẫn bạn bắt đầu với Walla API, các điểm cuối (endpoints) quan trọng, và tình huống sử dụng điển hình.

1) Bắt đầu: Xác thực API

Để dùng Walla API, trước tiên bạn cần phát hành API key và cấu hình xác thực.

1.1 Phát hành API key

1. Đăng nhập Walla Dashboard (app.walla.my).

2. Vào Cài đặt của team mà bạn muốn phát hành API key.

3. Tại Team Settings > API, tạo và lưu clientId và apiKey vào nơi an toàn.

1.2 Gửi yêu cầu xác thực

Walla API sử dụng Basic Authentication.

• Tạo chuỗi ở dạng {clientId}:{apiKey} (ví dụ: myClientId:myApiKey).

• Mã hóa chuỗi trên bằng Base64.

• Khi gọi API, thêm header:

cURL (Bash) ví dụ:

# 1. Tạo token (macOS / Linux)
TOKEN=$(echo -n "YOUR_CLIENT_ID:YOUR_API_KEY" | base64)

# 2. Gọi API
curl -X GET "<https://walla-api.datalab.workers.dev/workspace/list>" \\
     -H "Authorization: Basic $TOKEN"

2) Chi tiết endpoints

Base URL: https://walla-api.data-lab.workers.dev

2.1 Workspaces – Thông tin không gian làm việc

• GET /workspace/list

  Lấy danh sách tất cả workspace trong team.

Phản hồi mẫu (JSON):

[
  {
    "workspaceName": "Hanni's workspace",
    "workspaceKey": "ws-key-12345",
    "createdAt": "2025-07-03T10:00:00Z",
    "creator": "user-uid-abcde",
    "storage": { "used": 102400 }
  }
]

• GET /workspace/{workspaceKey}

  Lấy chi tiết một workspace cụ thể.

• GET /workspace/query/projectKey?projectKey={projectKey}

  Tìm workspaceKey từ projectKey.

Phản hồi mẫu (JSON):

{
  "workspaceKey": "ws-key-12345"
}

2.2 Projects – Thông tin dự án trong workspace

• GET /workspace/{workspaceKey}/project/list

  Liệt kê tất cả dự án trong một workspace.

• GET /workspace/{workspaceKey}/project/{projectKey}

  Xem chi tiết một dự án cụ thể.

2.3 Responses – Dữ liệu phản hồi khảo sát

• GET /workspace/{workspaceKey}/project/{projectKey}/response/list

  Tải toàn bộ phản hồi dưới dạng Parquet (thuận tiện cho phân tích dữ liệu lớn).

  Content-Type: application/octet-stream

• GET /workspace/{workspaceKey}/project/{projectKey}/response/get/responseKey/{responseKey}

  Lấy một phản hồi đơn bằng responseKey.

• GET /workspace/{workspaceKey}/project/{projectKey}/response/get/customerKey/{customerKey}

  Lấy một phản hồi đơn bằng customerKey (khóa bạn gán khi nộp form).

• GET /workspace/{workspaceKey}/project/{projectKey}/response/check/customerKey/{customerKey}

  Kiểm tra xem có phản hồi nào với customerKey đó hay không.

Phản hồi mẫu (JSON):

{
  "exists": true
}

• GET /workspace/{workspaceKey}/project/{projectKey}/response/query/dateRange?startDate=...&endDate=...

  Lọc các phản hồi theo khoảng ngày (ISO).

• GET /workspace/{workspaceKey}/project/{projectKey}/response/listCustomerKeys

  Lấy toàn bộ danh sách customerKey (khác null) trong dự án.

Phản hồi mẫu (JSON):

{
  "customerKeys": ["customer-001", "customer-002", "customer-003"]
}

2.4 Columns – Cấu trúc dữ liệu (schema)

• GET /workspace/{workspaceKey}/project/{projectKey}/columns

  Lấy cấu trúc các field và hidden field của dự án.

Phản hồi mẫu (JSON):

{
  "field_columns": [
    { "column_name": "field_abcd", "label": "이름", "type": "TEXT" }
  ],
  "hidden_field_columns": [
    { "column_name": "hf_1234", "label": "유입경로", "type": "TEXT" }
  ]
}

3) Tình huống sử dụng tiêu biểu

Ví dụ 1: Tải toàn bộ phản hồi để phân tích

1. Gọi GET /workspace/list hoặc GET /workspace/query/projectKey để tìm workspaceKey.

2. Gọi GET /workspace/{workspaceKey}/project/{projectKey}/response/list để tải file Parquet.

3. Đưa file vào Pandas (Python) hoặc R để phân tích.

Ví dụ 2: Kết nối CRM để xem lịch sử phản hồi theo khách hàng

1. Đồng bộ customer ID của CRM với customerKey trong Walla.

2. Khi mở hồ sơ khách hàng, gọi

   GET .../response/check/customerKey/{customerKey} để kiểm tra có phản hồi hay không.

3. Nếu exists: true, gọi

   GET .../response/get/customerKey/{customerKey} để hiển thị chi tiết ngay trong CRM.

4) Lưu ý & FAQ

• Phiên bản API: v1.0. Các thay đổi trong tương lai có thể phát hành theo phiên bản mới.

• Xử lý lỗi: Trả về HTTP status tiêu chuẩn (400/401/404...). Phần thân phản hồi có thể kèm chi tiết lỗi.

• Rate Limiting: Áp dụng giới hạn tần suất gọi để đảm bảo hiệu năng — kiểm tra response headers để biết trạng thái hiện tại.

• Cần hỗ trợ? Hãy liên hệ Trung tâm hỗ trợ Walla.

Kết luận

Với Walla API, biểu mẫu của bạn không còn tách rời mà kết nối liền mạch với hệ sinh thái dữ liệu doanh nghiệp: từ thu thập → xác thực → phân tích → kích hoạt quy trình. Một công cụ – vô hạn workflow.