Thông Tin Môi Trường & Headers Chung

Hệ thống Pango Chatbot Service sử dụng chuẩn giao thức GraphQL over HTTP (POST). Mọi thao tác truy vấn (Queries) và cập nhật dữ liệu (Mutations) đều gửi đến một endpoint duy nhất.

1. Endpoint Môi Trường

Môi Trường	Endpoint URL	Phương Thức	Ghi Chú
Staging / Sandbox	`https://staging-cps-ai-svc-v2.mydatalakes.com/graphql`	POST	Môi trường thử nghiệm & tích hợp dành cho đối tác
Production	(Cung cấp riêng cho từng đối tác khi Go-Live)	POST	Hệ thống chịu tải cao, có WAF và Cloudflare bảo vệ

Lưu Ý Về Giao Thức

Endpoint chỉ chấp nhận phương thức POST. Các request gửi bằng GET, PUT, DELETE sẽ bị từ chối với mã lỗi 405 Method Not Allowed.

2. HTTP Headers Bắt Buộc

Mọi request từ Client gửi lên Gateway phải chứa các HTTP Headers sau đây:

Header Name	Kiểu Dữ Liệu	Ví Dụ	Phạm Vi Yêu Cầu	Ý Nghĩa / Mô Tả
`Content-Type`	`string`	`application/json`	Bắt buộc cho mọi request	Khai báo định dạng payload gửi lên
`orgId`	`string`	`your_org_id_123`	Bắt buộc cho mọi request	Mã định danh Organization của đối tác
`x-org-id`	`string`	`your_org_id_123`	Bắt buộc cho mọi request	Bản sao của mã Organization (để tương thích Gateway)
`x-client-type`	`string`	`app` hoặc `widget`	Bắt buộc cho mọi request	Định danh loại ứng dụng gọi API (`app` cho Mobile, `widget` cho Web)
`x-external-private-key`	`string`	`your_private_key_***`	Bắt buộc cho mọi request	Khóa bí mật của đối tác được cấp riêng
`Checksum`	`string`	`38b4c27f91a0...`	Bắt buộc khi gọi ExternalLogin	Chuỗi mã hóa MD5 bảo mật (Xem Cơ chế Checksum)
`Authorization`	`string`	`Bearer eyJhbGci...`	Bắt buộc sau khi đăng nhập	Token JWT phiên đăng nhập của người dùng

Thứ Tự Gửi Headers

Với các request công khai/tiền đăng nhập như AgentConfigDetail hoặc ExternalLogin, bạn không cần gửi Authorization.

Ngay sau khi ExternalLogin thành công, lưu accessToken vào Secure Storage và luôn đính kèm header Authorization: Bearer <accessToken> trong toàn bộ các request sau đó.

3. Cấu Hình Biến Môi Trường (.env Setup)

Dưới đây là mẫu file .env.example chuẩn cấu hình cho dự án Mobile App (React Native/Flutter) hoặc Web App:

.env.example

# ==========================================
# GRAPHQL API CONFIGURATION (STAGING)
# ==========================================
VITE_API_URL="https://staging-cps-ai-svc-v2.mydatalakes.com/graphql"
VITE_ORG_ID="your_org_id_****************"
VITE_EXTERNAL_PRIVATE_KEY="your_external_private_key_****************"
VITE_ENABLED=true

# ==========================================
# FIREBASE REALTIME FIRESTORE CONFIG
# ==========================================
VITE_FIREBASE_API_KEY="AIzaSy*********************************"
VITE_FIREBASE_AUTH_DOMAIN="your-project-id.firebaseapp.com"
VITE_FIREBASE_PROJECT_ID="your-project-id"
VITE_FIREBASE_STORAGE_BUCKET="your-project-id.firebasestorage.app"
VITE_FIREBASE_MESSAGING_SENDER_ID="481027******"
VITE_FIREBASE_APP_ID="1:481027******:web:********************"
VITE_FIREBASE_DATABASE_ID="your-database-id"
VITE_FIREBASE_CONVERSATION="caresoft"

# ==========================================
# DEBUG / LOGGING
# ==========================================
VITE_DEBUG=true

Chi Tiết Ý Nghĩa Các Biến Môi Trường

Biến Môi Trường	Giá Trị Mẫu	Mô Tả Kỹ Thuật
`VITE_API_URL`	`https://staging-cps-ai-svc-v2.mydatalakes.com/graphql`	Endpoint GraphQL Gateway duy nhất dùng cho toàn bộ Queries & Mutations.
`VITE_ORG_ID`	`your_org_id_****`	Organization ID định danh doanh nghiệp, gửi qua header `orgId` và `x-org-id`.
`VITE_EXTERNAL_PRIVATE_KEY`	`your_private_key_****`	Khóa bảo mật đối tác, gửi qua header `x-external-private-key`.
`VITE_FIREBASE_*`	(Xem trong .env.example)	Bộ config kết nối Firebase SDK để lắng nghe Stream câu trả lời của AI từ Cloud Firestore.
`VITE_FIREBASE_DATABASE_ID`	`your-database-id`	Database ID của Firestore instance (nếu dùng named database thay vì default).
`VITE_FIREBASE_CONVERSATION`	`caresoft`	Mã định danh kênh / platform đàm thoại mặc định.
`VITE_ENABLED`	`true`	Feature flag cho phép bật/tắt widget hoặc màn hình chat nhanh phía client.

Thông Tin Môi Trường & Headers Chung

1. Endpoint Môi Trường

2. HTTP Headers Bắt Buộc

3. Cấu Hình Biến Môi Trường (.env Setup)

Chi Tiết Ý Nghĩa Các Biến Môi Trường

On this page