Xây dựng tích hợp

Hướng dẫn thao tác

Dành cho:: Nhà phát triển
Cần quyền:: webhooks:manage, subscribers:create, subscribers:edit
Trong ứng dụng:: Cài đặt, rồi Khóa và MCP

Các ứng dụng Zapier, Make, n8n và plugin WordPress do ReputeCast phát hành chỉ dùng REST API công khai. Trang này hướng dẫn xây dựng tích hợp email marketing theo đúng cách đó: xác thực, xác định không gian làm việc, đăng ký nhận sự kiện và gọi năm hành động mà các ứng dụng chính thức cung cấp, mà không bao giờ làm mất sự đồng ý của một liên hệ.

Trước khi bắt đầu

Một hệ thống ReputeCast truy cập được qua HTTPS từ nơi tích hợp của bạn chạy, cùng URL công khai của nó (“URL hệ thống”). Mọi đường dẫn bên dưới đều bắt đầu bằng /api/v1.
Một khóa API. Với ứng dụng hoặc dịch vụ của riêng bạn, hãy tạo khóa trong Cài đặt, rồi Khóa và MCP bằng Tạo khóa API và chỉ cấp những gì tích hợp cần: webhooks:manage cho trình kích hoạt, subscribers:create và subscribers:edit cho các hành động với liên hệ, transactional:send để gửi email giao dịch. Xem Xác thực và khóa API.
Các ứng dụng chính thức nhận một loại khóa khác, khóa tích hợp, từ Cài đặt, rồi Tích hợp › Kết nối. ReputeCast chỉ tạo khóa tích hợp cho Zapier, Make, n8n và WordPress (Kết nối công cụ khác).

Kết nối và kiểm tra

Hỏi người dùng URL hệ thống và khóa. Lưu khóa ở dạng mã hóa; gửi nó dưới dạng Authorization: Bearer rc_live_… trong mọi lệnh gọi.

Gọi GET /api/v1/integration. Mọi khóa API đều gọi được thao tác này mà không cần quyền nào, và phản hồi cho biết khóa thuộc không gian làm việc nào:

curl https://reputecast.example.com/api/v1/integration \
  --header "Authorization: Bearer $REPUTECAST_API_KEY"

{
  "workspace": "acme-newsletter",
  "workspaceName": "Acme Newsletter",
  "integration": "",
  "key": "CRM sync",
  "triggers": [],
  "actions": [],
  "permissions": ["subscribers:create", "subscribers:edit", "webhooks:manage"]
}

Dùng workspace trong mọi đường dẫn khác (/api/v1/workspaces/acme-newsletter/…) và kiểm tra permissions trước khi cung cấp một tính năng. integration, triggers và actions chỉ có giá trị với khóa tích hợp.

Trình kích hoạt: đăng ký nhận sự kiện

Tích hợp của bạn biết về các thay đổi qua webhook gửi đi. Khi người dùng bật một trình kích hoạt, hãy tạo endpoint cho nó; khi họ tắt, hãy xóa endpoint đó.

curl --request POST \
  --url https://reputecast.example.com/api/v1/workspaces/acme-newsletter/webhooks \
  --header "Authorization: Bearer $REPUTECAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "name": "CRM sync · unsubscribes", "url": "https://crm.example.com/hooks/reputecast", "events": ["contact.unsubscribed"] }'

Phản hồi 201 chứa endpoint trong webhook và khóa bí mật ký của nó trong secret, chỉ xuất hiện trong phản hồi này. Hãy lưu khóa bí mật cùng lượt đăng ký và dùng nó để xác minh mọi lần gửi (xác minh chữ ký). DELETE …/webhooks/<webhookId> hủy đăng ký. Các sự kiện mà hầu hết tích hợp dùng làm trình kích hoạt:

Trình kích hoạt	Sự kiện	Khóa cần có
Liên hệ đăng ký	`contact.subscribed`	`subscribers:view`
Liên hệ hủy đăng ký	`contact.unsubscribed`	`subscribers:view`
Liên hệ được cập nhật	`contact.updated`	`subscribers:view`
Biểu mẫu được gửi	`form.submitted`	`subscribers:view`
Chiến dịch đã gửi xong	`campaign.completed`	`campaigns:view`
Thư giao dịch bị trả lại	`message.bounced`	`transactional:view`

Mọi sự kiện khác trong Sự kiện webhook đều hoạt động theo cách tương tự. form.submitted phát ra khi một lượt đăng ký được xác nhận (ngay lập tức với xác nhận một bước) và mang ID của biểu mẫu, để ứng dụng của bạn lọc theo biểu mẫu.

Các ứng dụng chính thức dùng REST hook thay thế: POST …/integration/hooks với { "event", "url" } tạo một endpoint được quản lý, và endpoint nào trả lời 410 Gone sẽ bị xóa. Các thao tác này, cùng các thao tác tra cứu dữ liệu mẫu, danh sách, trường và mẫu trong …/integration/, chỉ chấp nhận khóa tích hợp (tài liệu Integration API).

Hành động

Hành động	Lệnh gọi	Khóa cần có
Tạo hoặc cập nhật liên hệ	`POST …/contacts/upsert`	`subscribers:create`; `subscribers:edit` để cập nhật liên hệ
Thêm liên hệ vào danh sách	`POST …/lists/<listId>/contacts`	`subscribers:edit`
Thêm thẻ cho liên hệ	`POST …/contacts/tags`	`subscribers:edit`
Ghi nhận sự kiện	`POST …/automations/events`	`subscribers:edit`
Gửi email giao dịch	`POST …/transactional/messages`	`transactional:send` (nhạy cảm)

Tạo hoặc cập nhật liên hệ khớp theo email, nên gọi lại sẽ cập nhật đúng liên hệ đó thay vì tạo thêm một liên hệ thứ hai:

# REPUTECAST_API_KEY: an API key (rc_live_…) with subscribers:create (and subscribers:edit to update contacts).
# Replace reputecast.example.com with your public URL and your-workspace with your workspace slug.
# List IDs come from GET /api/v1/workspaces/your-workspace/lists.
curl --request POST \
  --url https://reputecast.example.com/api/v1/workspaces/your-workspace/contacts/upsert \
  --header "Authorization: Bearer $REPUTECAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "firstName": "Sam",
    "lastName": "Rivera",
    "language": "en-US",
    "tags": ["trial"],
    "lists": ["0192f1c4-3a5b-7c2d-8e9f-1a2b3c4d5e6f"],
    "consent": "double"
  }'

consent: "single" thêm liên hệ vào danh sách ngay; "double" gửi email xác nhận trước, và danh sách hiển thị pending cho đến khi người đó nhấp vào liên kết. Nếu không có consent, cài đặt riêng của từng danh sách được áp dụng.
language nhận mã BCP 47. Các giá trị như Spanish hoặc es_MX được chuẩn hóa (es, es-MX); giá trị không nhận diện được sẽ trả về 422, kèm tên giá trị gần nhất nếu có.
Mỗi lệnh gọi nhận tối đa 20 ID danh sách và 50 thẻ. Lấy ID danh sách từ GET …/lists và khóa của trường tùy chỉnh cho fields từ GET …/fields (cả hai đều cần subscribers:view).
Phản hồi cho biết liên hệ có được tạo mới không (created), đã tham gia những danh sách nào với trạng thái nào, và email xác nhận có được gửi đi không (confirmationSent).

Thêm liên hệ vào danh sách cần một liên hệ đã tồn tại; địa chỉ mới sẽ trả về 404, nên hãy gọi upsert trước. Ghi nhận sự kiện được trình bày trong Ghi nhận sự kiện và chuyển đổi, còn Gửi email giao dịch trong Gửi email giao dịch bằng API.

Sự đồng ý luôn được giữ

Một hành động không bao giờ thêm lại ai đó vào danh sách họ đã rời và không bao giờ thêm một địa chỉ bị chặn gửi. Thay vào đó, nó trả lời 409:

{
  "status": 409,
  "title": "Conflict",
  "code": "unsubscribed",
  "detail": "[email protected] left Beta Program on 2 Oct. ReputeCast doesn't add people back to a list they left.",
  "meta": { "list": "Beta Program", "listId": "0192…", "leftAt": "2026-10-02T13:41:00Z" }
}

409 suppressed mang meta.reason và meta.since. Hãy coi cả hai trường hợp là “bỏ qua” cho bản ghi đó, không phải một quy trình thất bại: báo cho người dùng và tiếp tục với các bản ghi còn lại.

Thử lại và idempotency

Lệnh gửi giao dịch và API chuyển đổi nhận header Idempotency-Key: lần thử lại với cùng khóa nhận lại phản hồi đầu tiên và không gửi hay ghi nhận hai lần. Hãy đưa ID lần chạy hoặc ID bản ghi của nền tảng vào khóa, như các ứng dụng chính thức làm (make-<scenario ID>-<value>, n8n-<workflow ID>-<value>).
Các hành động khác không nhận khóa này. Chỉ thử lại chúng sau lỗi mạng hoặc phản hồi 429/5xx, và không bao giờ sau phản hồi 2xx.
Khi nhận 429, hãy chờ theo Retry-After. Giới hạn chung là 600 yêu cầu mỗi phút cho mỗi khóa (Giới hạn tốc độ).

Khóa tích hợp và tên quy trình

Nếu bạn duy trì một trong các ứng dụng chính thức, khóa của ứng dụng đó đến từ Cài đặt, rồi Tích hợp và tuân theo thêm các quy tắc sau:

Khóa chỉ dùng được cho các thao tác của những trình kích hoạt và hành động mà người dùng đã bật, ngay cả khi quyền của khóa cho phép nhiều hơn. Mọi lệnh gọi khác trả về 403 integration_operation_denied.
Xoay vòng khóa giữ khóa cũ hoạt động thêm 24 giờ, để ứng dụng được cập nhật mà không có lần chạy nào bị lỗi; Dừng khóa cũ ngay kết thúc khoảng chồng lấn đó.
Khi người sở hữu khóa bị vô hiệu hóa hoặc bị xóa, lệnh gọi trả về 403 owner_deactivated cho đến khi một thành viên có integrations:manage chọn Tiếp quản. Khóa bị thu hồi hoặc hết hạn trả về 401 key_revoked hoặc 401 key_expired.
Mọi lệnh gọi được lưu 7 ngày trong nhật ký lệnh gọi của tích hợp. Hãy gửi tên và ID của quy trình kèm mỗi lệnh gọi để nhật ký hiển thị được chúng:
Header của yêu cầu
```
X-ReputeCast-Workflow: Beta application (Typeform) → ReputeCast contact; id=284113907
```
Hãy mã hóa phần trăm (UTF-8) các ký tự nằm ngoài bảng ASCII in được, cùng %, ;, = và "; ReputeCast sẽ giải mã chúng. Dạng name="…" và dạng RFC 8187 name*=UTF-8''… cũng được chấp nhận.

Thiết lập	Mặc định	Cách thay đổi
Khóa cũ vẫn hoạt động sau Xoay vòng khóa	24 hours	Chọn Dừng khóa cũ ngay để kết thúc sớm
Thời gian giữ nhật ký lệnh gọi	7 days	Cố định
Cần chú ý khi khóa hết hạn trong vòng	7 days	Cố định
Cần chú ý khi một webhook được quản lý liên tục lỗi trong	30 minutes	Cố định
Cần chú ý khi lệnh gọi bị lỗi	More than 50% of calls in the last hour (at least 4 calls)	Cố định
Cần chú ý khi một trang WordPress ngừng báo cáo trong	24 hours	Cố định
Plugin WordPress báo cáo về ReputeCast	On connect, every 12 hours and with every post	Cố định
Thời gian chờ của Kiểm tra ngay với một trang WordPress	10 s	Cố định

Kiểm tra kết quả

GET /api/v1/integration trả lời 200 với không gian làm việc và các quyền đúng như bạn mong đợi.
Sau khi tạo endpoint, Cài đặt, rồi Webhook liệt kê endpoint đó, và Gửi sự kiện thử của nó tới được bộ nhận của bạn.
Sau một lệnh upsert, liên hệ xuất hiện trong Người đăng ký với danh sách, thẻ và sự đồng ý mà bạn đã gửi.

Khắc phục sự cố

403 permission_denied: khóa thiếu quyền được nêu trong permission; trường helpers nêu tên các thành viên có thể cấp quyền đó.
422 private_address khi tạo endpoint: URL trỏ tới mạng riêng. Hãy dùng địa chỉ công khai, hoặc nhờ quản trị viên hệ thống đặt webhooks.allow_private_networks.
404 khi thêm vào danh sách: liên hệ chưa tồn tại; hãy upsert trước.
409 unsubscribed hoặc 409 suppressed: đây là hành vi dự kiến; hãy bỏ qua bản ghi đó.
403 integration_operation_denied: khóa tích hợp không được phép thực hiện lệnh gọi này. Hãy thay đổi những gì tích hợp được làm trong Cài đặt, rồi Tích hợp.

Liên quan

Nhận webhookEnvelope, header, chữ ký và cơ chế thử lại.

Kết nối công cụ khácDanh mục tích hợp trong ứng dụng.

LỗiTài liệu lỗi dạng problem và mọi mã lỗi.

Tài liệu APIMọi thao tác mà khóa API có thể gọi.