Data Ingestion Callback

Tài liệu hướng dẫn tích hợp API Callback để nhận kết quả ingest data vào Pango.

Data Ingestion Callback API Spec

API - Pango Data Ingestion Callback được sử dụng để phản hồi kết quả lưu trữ dữ liệu thực tế khi đối tác sử dụng Data Ingestion API để đẩy dữ liệu vào PangoCDP. Ví dụ:

• Đối tác sử dụng Data Ingestion API để gửi dữ liệu khách hàng vào Pango, API phản hồi ngay lập tức xác nhận rằng Pango đã tiếp nhận dữ liệu và sẽ thực hiện ingest thông qua hàng đợi (Queue).

• Để biết chính xác record nào được ghi thành công hoặc thất bại vào Data Model Pango, đối tác cần sử dụng Callback API này.

---

API Endpoint: https://your-domain-api.com

Method: POST

Payload:

{
    "data": {
       "3c439cfc852573428bdb91f5bf96840d10": {
          "status": 200,
          "cdpId": "TAb2P9brterOhKPqOJvs"
       },
       "1c39cc851573728bdb291f5bf96840d10": {
          "status": 101,
          "errorMess":"Missing momCode"
       }
    }
}

Headers:

{
  "Content-Type": "application/json",
  "ApiKey": "Your-Api-Key",
  "CheckSum": "Your-Checksum"
}

---

Headers

Name	Type	Required	Valid Value / Description	Example
Content-type	String	Yes	application/json	application/json
ApiKey	String	No	ApiKey được đối tác gửi trong yêu cầu API ingest và được sử dụng để xác thực thông tin callback từ hệ thống của Pango
Checksum	String	No	Checksum được tạo từ ApiKey do đối tác cung cấp và được sử dụng để xác thực thông tin callback từ hệ thống của Pango. Bắt buộc trong trường hợp có ApiKey.

Payload Parameters

Name	Type	Required	Valid Value / Description	Example
data	String	Yes	Đây là một trường cố định chứa danh sách các đối tượng, trong đó mỗi Key là một refId do đối tác cung cấp thông qua API Ingestion
data.refId	String	Yes	Key định danh cho mỗi object do đối tác truyền ở Api Ingestion Data
data.refId.status	int	Yes	Trường xác định trạng thái xử lý lưu trữ đối với mỗi refId
data.refId.cdpId	String	No	Key định danh do Pango tạo ra khi dữ liệu được lưu thành công. Chỉ xuất hiện khi thao tác lưu thành công (status=200)
data.refId.errorMessage	String	No	Tin nhắn lỗi khi quá trình lưu dữ liệu thất bại. Chỉ xuất hiện khi thao tác lưu không thành công (status != 200)

Response

Status	Code	Sample
Failed	400	{ "success":false, "errorCode":"MISSING_INFO", "message":"Field data is required" }
Failed	401	{ "success":false, "errorCode":"MISSING_INFO", "message":"Field data is required" }
Success	200	{ "success": true, "message": "Your request received successfully" }

Persistence Status

Status	Description	Example
200	Lưu thành công
101	Lỗi xác thực dữ liệu đầu vào: - Thiếu các các trường bắt buộc - Trường dữ liệu không đúng định dạng
102	Lưu thất bại

Hướng dẫn tạo Checksum để xác thực

Lưu ý khi tạo Checksum

• RefIds: Danh sách các giá trị RefId được trích xuất từ object data trong API callback.

• ApiKey: Giá trị ApiKey được lấy từ Header của API callback.

Trước bắt đầu tạo Checksum, danh sách RefId cần được sắp xếp theo thứ tự bảng chữ cái để đảm bảo tính nhất quán trong quá trình mã hóa.

Các bước tạo Checksum

(1) Lấy danh sách RefId từ Object data

Tham khảo ví dụ Request Body:

{
  "data": {
    "3c439cfc852573428bdb91f5bf96840d10":  {
      "status": 200,
      "cdpId": "TAb2P9brterOhKPqOJvs"
    },
    "1c39cc851573728bdb291f5bf96840d10":  {
      "status": 101,
      "errorMess": "Missing momCode"
    }
  }
}

Result:RefIds=["3c439cfc852573428bdb91f5bf96840d10", "1c39cc851573728bdb291f5bf96840d10"]

(2) Sắp xếp danh danh sách RefId

Sắp xếp theo thứ tự bảng chữ cái. Tham khảo ví dụ bên dưới:

RefIds: ["3c439cfc852573428bdb91f5bf96840d10", "1c39cc851573728bdb291f5bf96840d10"]

Result: RefIds=["1c39cc851573728bdb291f5bf96840d10", "3c439cfc852573428bdb91f5bf96840d10"]

(3) Tạo Group Key L1

• Cấu trúc: Value1:Value2:ApiKey

• Kết hợp tất cả các phần tử dữ liệu từ danh sách, ngăn cách bằng dấu hai chấm (:), sau đó nối thêm ApiKey.

• Tham khảo ví dụ:

  • Value1: 1c39cc851573728bdb291f5bf96840d10

  • Value2: 3c439cfc852573428bdb91fbf96840d1

  • ApiKey: Pango

  • Result:"1c39cc851573728bdb291f5bf96840d10:3c439cfc852573428bdb91fbf96840d1:Pango"

(4) Tạo Group Key L2

• Cấu trúc: ApiKey-Value1-Value2

• Bắt đầu với ApiKey, sau đó lần lượt nối từng phần tử dữ liệu, ngăn cách bằng dấu gạch ngang (-)

• Tham khảo ví dụ:

  • Value1: 1c39cc851573728bdb291f5bf96840d10

  • Value2: 3c439cfc852573428bdb91f5bf96840d10

  • ApiKey: Pango

  • Result: "Pango-1c39cc851573728bdb291f5bf96840d10-3c439cfc852573428bdb91f5bf96840d10”

(5) Tạo Checksum cuối cùng:

• Cấu trúc: GroupKeyL1GroupKeyL2

• Kết hợp Group Key L1 và Group Key L2, sau đó băm toàn bộ chuỗi bằng thuật toán MD5 để tạo ra nội dung Checksum cuối cùng.

• Tham khảo ví dụ: MD5.hex("1c39cc851573728bdb291f5bf96840d10:3c439cfc852573428bdb91bf96840d10:PangoPango-1c39cc851573728bdb291f5bf96840d10-3c439cfc852573428bdb91f5bf96840d10") =b1dd22c41d452a312ea095b96ac46bec

---

Xem trên Google Doc

https://docs.google.com/document/d/1V2Hn09sVWBKj4RXzG1wuMTleU7BRMOa4ZAYIrL4-WE4docs.google.com