Thực hiện lệnh gọi API đầu tiên

Hướng dẫn từng bước

Dành cho:: Nhà phát triển
Cần quyền:: apikeys:managenhạy cảm, campaigns:view
Trong ứng dụng:: Cài đặt, rồi Khóa và MCP

Bài hướng dẫn API email marketing này mất khoảng năm phút: bạn tạo một khóa API có thể đọc chiến dịch, kiểm tra xem khóa hoạt động chưa, rồi liệt kê các chiến dịch của một không gian làm việc bằng curl.

Trước khi bắt đầu

Một hệ thống ReputeCast truy cập được qua URL công khai của nó. Các ví dụ dùng https://reputecast.example.com; khi dùng thử trên máy, http://localhost:8080 cũng được.
Một tài khoản thành viên có quyền apikeys:manage trong không gian làm việc. Vai trò Chủ sở hữu và Quản trị viên có quyền này. Khóa do một người đã đăng nhập tạo ra; một khóa không thể tạo khóa khác.
Slug của không gian làm việc: phần đứng sau /w/ trong địa chỉ của ứng dụng, ví dụ acme-newsletter trong /w/acme-newsletter/campaigns.
curl trong một cửa sổ terminal.

Các bước

Mở Cài đặt, rồi Khóa và MCP và chọn Tạo khóa API.
Đặt cho khóa một cái tên cho biết nơi nó chạy, chẳng hạn Campaign reader. Ở mục Bắt đầu từ, giữ Tùy chỉnh. Ở mục Quyền, đánh dấu dòng campaigns:view trong nhóm Chiến dịch. Ở mục Hết hạn, chọn Sau 30 ngày cho một khóa dùng thử. Chọn Tạo khóa.

Danh sách chỉ đưa ra những quyền chính bạn đang có. Các quyền còn lại bị khóa, kèm lý do bên cạnh.
Trong Hãy sao chép khóa mới của bạn ngay, chọn Sao chép, đánh dấu ô xác nhận bạn đã sao chép khóa, rồi chọn Xong.

Khóa có dạng rc_live_ theo sau là 64 ký tự thập lục phân. Đây là lần duy nhất ReputeCast hiển thị khóa: máy chủ chỉ giữ giá trị băm SHA-256 của nó. Nếu làm mất khóa, hãy xoay vòng khóa để nhận khóa mới.
Đặt địa chỉ hệ thống của bạn và khóa vào biến môi trường cho các lệnh tiếp theo:
Terminal
```
export RC_URL=https://reputecast.example.com
export RC_KEY=rc_live_…
```
Kiểm tra khóa bằng lệnh gọi thử GET /api/v1/integration. Lệnh này chỉ cần khóa và trả về không gian làm việc cùng các quyền của khóa:
Terminal
```
curl -s -H "Authorization: Bearer $RC_KEY" "$RC_URL/api/v1/integration"
```
Phản hồi
```
{
  "workspace": "acme-newsletter",
  "workspaceName": "Acme Newsletter",
  "integration": "",
  "key": "Campaign reader",
  "triggers": [],
  "actions": [],
  "permissions": ["campaigns:view"]
}
```
workspace là slug mà các đường dẫn khác dùng. integration, triggers và actions để trống với khóa do bạn tự tạo; chúng mô tả khóa của các tích hợp.

Liệt kê chiến dịch đã gửi gần nhất bằng list-campaigns:

curl -s -H "Authorization: Bearer $RC_KEY" \
  "$RC_URL/api/v1/workspaces/acme-newsletter/campaigns?status=sent&channel=email&pageSize=1"

{
  "items": [
    {
      "id": "01a1637b-7ca8-78aa-80be-d3afe3429ffd",
      "name": "October Product Update",
      "channel": "email",
      "status": "sent",
      "blocked": false,
      "audience": "All subscribers",
      "recipients": 47980,
      "createdAt": "2026-10-15T21:00:00+07:00",
      "updatedAt": "2026-10-18T23:41:00+07:00",
      "updatedBy": "Linh Nguyen",
      "scheduledAt": "2026-10-18T21:00:00+07:00",
      "startedAt": "2026-10-18T21:00:00+07:00",
      "delivered": 99.1,
      "humanOpens": 41.2,
      "clicks": 6.3,
      "routes": [
        {
          "providerId": "01a1637b-7a69-7226-a5b2-3326a2d0d468",
          "provider": "Amazon SES",
          "short": "SES",
          "adapter": "ses",
          "percent": 90,
          "planned": 43182,
          "sent": 43182
        },
        {
          "providerId": "01a1637b-7a6d-7a25-9a11-1297d012f10d",
          "provider": "Postal",
          "short": "Postal",
          "adapter": "postal",
          "percent": 10,
          "planned": 4798,
          "sent": 4798
        }
      ],
      "notes": ["A/B subject, winner B"],
      "paidOnly": false
    }
  ],
  "total": 49,
  "page": 1,
  "pageSize": 1,
  "counts": { "all": 61, "drafts": 9, "scheduled": 1, "sending": 0, "sent": 51, "paidOnly": 0 }
}

Phản hồi này lấy từ dữ liệu demo; phản hồi của bạn sẽ liệt kê chiến dịch của chính bạn.

Đọc phản hồi:
- items chứa một trang chiến dịch. total là số chiến dịch khớp với bộ lọc của bạn, còn page và pageSize cho biết bạn nhận được phần nào. Phân trang giải thích cách lấy phần còn lại.
- counts cho biết số chiến dịch ở từng trạng thái, dùng cho các tab và huy hiệu.
- delivered, humanOpens và clicks là tỷ lệ phần trăm. Chúng bị bỏ khỏi chiến dịch chưa gửi gì, vì vậy hãy kiểm tra trường bị thiếu thay vì kiểm tra null.
- routes liệt kê các nhà cung cấp gửi thư mà chiến dịch đã đi qua và phần mỗi nhà cung cấp đảm nhận.

Xem một lỗi trông như thế nào: gửi một khóa không tồn tại.

curl -i -H "Authorization: Bearer rc_live_0000000000000000000000000000000000000000000000000000000000000000" \
  "$RC_URL/api/v1/workspaces/acme-newsletter/campaigns"

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
Www-Authenticate: Bearer realm="reputecast"

{"title":"Unauthorized","status":401,"detail":"This API key is revoked or unknown.","code":"unauthenticated"}

Mọi lệnh gọi thất bại đều trả về một problem document như thế này. Hãy rẽ nhánh theo status và code; detail được viết cho người đọc. Lỗi API liệt kê mọi mã lỗi.

Bạn đã làm được gì

Bạn có một khóa chỉ đọc được chiến dịch và không làm được gì khác, cùng hai lệnh gọi hoạt động: một lệnh gọi thử cho biết không gian làm việc và các quyền của khóa, và một lệnh gọi danh sách có phân trang. Dòng của khóa trong Cài đặt, rồi Khóa và MCP giờ hiển thị lần cuối khóa được dùng và từ địa chỉ IP nào. Khi thử nghiệm xong, hãy chọn Thu hồi trên dòng đó: khóa ngừng hoạt động ngay lập tức.

Bước tiếp theo

Xác thực và khóa APICác loại khóa, phạm vi, hạn dùng, xoay vòng và những phản hồi bạn nhận được khi khóa bị từ chối.

Gửi email giao dịch bằng APIGửi thư đặt lại mật khẩu và biên lai từ sản phẩm của bạn bằng một khóa chỉ gửi.

Nhận webhookNhận sự kiện có chữ ký thay vì hỏi API định kỳ để biết thay đổi.