API nhà phát triển

Tổng quan

API nhà phát triển Nudgen cung cấp cho các tập lệnh, công cụ nội bộ và tác nhân AI một khả năng có thể dự đoán được Giao diện REST cho không gian làm việc của bạn. Sử dụng Mã thông báo truy cập cá nhân (PAT) để quản lý tài nguyên không gian làm việc. Chỉ sử dụng khóa API kích hoạt nhóm để kích hoạt chiến dịch Trọn đời từ chương trình phụ trợ của bạn.

Tại sao điều này lại quan trọng

Bạn có thể tự động hóa quy trình tiếp thị và quy trình lưu giữ theo sự kiện mà không cần chia sẻ phiên trang tổng quan. PAT giữ cho việc quản lý không gian làm việc có thể thu hồi được, trong khi khóa kích hoạt Nhóm hẹp cho phép dịch vụ sản xuất gửi một cú huých do sự kiện kích hoạt mà không có quyền truy cập không gian làm việc rộng.

URL cơ sở

Đặt URL ứng dụng cho môi trường của bạn một lần và sử dụng URL đó trong mọi ví dụ. Sản xuất thường sử dụng https://app.nudgen.net; phát triển cục bộ thường sử dụng http://localhost:3000.

export NUDGEN_APP_URL="https://app.nudgen.net"

Authentication

Mã thông báo truy cập cá nhân

Tạo PAT trong Cài đặt → Khóa API. Sử dụng nó để liên hệ, quản lý chiến dịch, cài đặt thương hiệu và tạo AI.

Authorization: Bearer $NUDGEN_PAT

PAT chỉ được hiển thị một lần. Lưu trữ chúng một cách an toàn và thu hồi mọi mã thông báo cũ hoặc bị lộ khỏi Cài đặt → Khóa API.

Khóa API kích hoạt nhóm

A Khóa API kích hoạt nhóm bắt đầu bằng ndg_team_ và có phạm vi campaigns:trigger hẹp. Nó chỉ có thể kích hoạt các chiến dịch Trọn đời; PAT không thể kích hoạt chúng. Chỉ chủ sở hữu và quản trị viên không gian làm việc mới có thể tạo, xoay hoặc thu hồi các khóa này. Theo mặc định, khóa sẽ hết hạn sau 90 ngày. Đặt expiresInDays thành null để tạo khóa không hết hạn.

curl -X POST "$NUDGEN_APP_URL/api/v1/settings/team-api-keys" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"name":"Order service production","expiresInDays":90}'

Phản hồi 201 chứa chính xác văn bản gốc key một lần. Lưu nó trong trình quản lý bí mật phía máy chủ. Các phản hồi sau chỉ hiển thị keyPrefix.

Phương pháp	Điểm cuối	Mô tả
`POST`	`/api/v1/settings/team-api-keys`	Tạo khóa API kích hoạt nhóm.
`GET`	`/api/v1/settings/team-api-keys`	Liệt kê các khóa API kích hoạt nhóm.
`POST`	`/api/v1/settings/team-api-keys/:id`	Xoay một phím đang hoạt động, chưa hết hạn.
`DELETE`	`/api/v1/settings/team-api-keys/:id`	Thu hồi một chìa khóa.

Điểm cuối REST

Danh tính và không gian làm việc

Phương pháp	Điểm cuối	Mô tả
`GET`	`/api/v1/user/me`	Nhận người dùng được xác thực.
`GET`	`/api/v1/teams`	Liệt kê các không gian làm việc có sẵn cho chủ sở hữu mã thông báo.

Liên hệ

Phương pháp	Điểm cuối	Mô tả
`GET`	`/api/v1/contacts`	Liệt kê các liên hệ với các bộ lọc `page`, `limit`, `search`, `tags` và `status`.
`POST`	`/api/v1/contacts/add`	Tạo một liên hệ.
`GET`	`/api/v1/contacts/:id`	Nhận một liên lạc.
`PATCH`	`/api/v1/contacts/:id`	Cập nhật một liên hệ.
`DELETE`	`/api/v1/contacts/:id`	Xóa một liên hệ.

curl -X POST "$NUDGEN_APP_URL/api/v1/contacts/add" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"email":"nathan@example.com","name":"Nathan Nguyen","tags":["api-test"]}'

Chiến dịch một lần và nhỏ giọt

Phương pháp	Điểm cuối	Mô tả
`GET`	`/api/v1/campaigns`	Liệt kê các chiến dịch trong không gian làm việc đang hoạt động.
`POST`	`/api/v1/campaigns`	Tạo bản dự thảo chiến dịch hoặc chiến dịch đã lên lịch.
`GET`	`/api/v1/campaigns/:id`	Nhận chi tiết chiến dịch.
`PUT`	`/api/v1/campaigns/:id`	Cập nhật chiến dịch hiện có.
`POST`	`/api/v1/campaigns/:id/launch`	Khởi động ngay bây giờ hoặc lên lịch chiến dịch một lần hoặc nhỏ giọt.
`GET`	`/api/v1/campaigns/:id/stats`	Nhận số liệu thống kê về giao hàng, mở, nhấp chuột, trả lại và khiếu nại.
`GET`	`/api/v1/campaigns/:id/progress`	Nhận tiến trình gửi chiến dịch.
`GET`	`/api/v1/campaigns/:id/recipients`	Liệt kê người nhận chiến dịch.
`POST`	`/api/v1/campaigns/test-send`	Gửi email kiểm tra mà không có số liệu thống kê gửi bảng điều khiển.

Khởi động chiến dịch lên lịch gửi email thực. Sử dụng /api/v1/campaigns/test-send để xem trước hộp thư đến.

Chiến dịch trọn đời

Chiến dịch trọn đời được kích hoạt theo sự kiện: mỗi trình kích hoạt được chấp nhận tạo ra tối đa một lần thực thi và gửi một lần thúc đẩy đến người liên hệ được cung cấp. Xem Sử dụng chiến dịch trọn đời để biết quy trình làm việc trên trang tổng quan và hướng dẫn về hợp đồng thay đổi.

Tạo chiến dịch trọn đời

Tạo chiến dịch trọn đời dưới dạng draft. Không gửi sendNow: true, status: "active" hoặc status: "scheduled"; thay vào đó hãy kích hoạt chiến dịch với điểm cuối vòng đời của nó.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Order confirmation",
  "type": "lifetime",
  "status": "draft",
  "goal": "Confirm an order and direct the customer to its details.",
  "subject": "Your order {{data.order_id}} was received",
  "html": "<p>Hello {{contact.firstName}},</p><p>Order {{data.order_id}} totals {{data.total}} VND.</p><p><a href=\"{{data.order_url}}\">View your order</a></p>",
  "link": "https://example.com/orders",
  "variableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ],
  "generatedVariableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ]
}
JSON

variableManifest xác định tối đa 100 biến data.*. Nó phải bao gồm mọi mã thông báo data.* được sử dụng trong chủ đề hoặc HTML. Giá trị mặc định phải khớp với loại đã khai báo và biến được sử dụng trong HTML href phải có loại url. Khi bạn tạo nội dung email, hãy lưu generatedVariableManifest phù hợp. Nudgen chặn kích hoạt nếu nó khác với tệp kê khai hiện tại hoặc nếu các tham số được khai báo bắt buộc không có trong email.

Thay đổi vòng đời

Phương pháp	Điểm cuối	Xác thực	Mô tả
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	PAT	Thay đổi chiến dịch Trọn đời thành `active`, `paused` hoặc `archived`.

curl -X PATCH "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/lifecycle" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"status":"active"}'

Các chuyển tiếp hợp lệ là draft → active → paused → active và active|paused → archived. Việc tạm dừng hoặc lưu trữ sẽ hủy các lệnh thực thi vẫn là pending hoặc queued và giải phóng hạn ngạch đặt trước của chúng. Một quá trình thực thi đang được xử lý vẫn có thể gửi.

Kích hoạt một cú huých

Phương pháp	Điểm cuối	Xác thực	Mô tả
`POST`	`/api/v1/campaigns/:campaignId/triggers`	Khóa API kích hoạt nhóm	Tạo một lần thực hiện sự kiện và xếp hàng một cú huých.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "phone": "+84901234567",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON

Lĩnh vực	Loại	Bắt buộc	Giới hạn và hành vi
`eventId`	chuỗi	Có	1–128 ký tự. Khóa bình thường duy nhất trong chiến dịch; tái sử dụng nó để thử lại.
`eventName`	chuỗi	Không	1–100 ký tự, ví dụ `order.created`.
`occurredAt`	Ngày giờ ISO 8601	Không	Thời gian xảy ra sự kiện nguồn.
`contact.email`	email	Có	Viết thường. Nudgen tạo hoặc cập nhật liên hệ qua email.
`contact.externalId`	chuỗi	Không	1–200 ký tự và không được thuộc về một email liên hệ khác trong không gian làm việc.
`contact.name`	chuỗi	Không	Lên đến 200 ký tự.
`contact.phone`	chuỗi	Không	Tối đa 50 ký tự.
`contact.metadata`	đối tượng	Không	Dữ liệu hồ sơ liên hệ bổ sung.
`data`	đối tượng	Có	Phải khớp với `variableManifest`; tối đa 32 KiB.

Toàn bộ nội dung yêu cầu được giới hạn ở 64 KiB, JSON lồng nhau ở tám cấp và các khóa không an toàn như __proto__, constructor và prototype bị từ chối. A trình kích hoạt mới sẽ trả về 201 với { "execution": { "id": "...", "status": "queued" }, "duplicate": false }. Việc sử dụng lại eventId sẽ trả về kết quả thực thi hiện có với 200 và duplicate: true.

Thực thi danh sách

Phương pháp	Điểm cuối	Xác thực	Mô tả
`GET`	`/api/v1/campaigns/:campaignId/executions`	PAT	Liệt kê các lần thực thi chiến dịch trọn đời.

curl "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/executions?limit=25&status=sent&search=an@example.com" \
  -H "Authorization: Bearer $NUDGEN_PAT"

Sử dụng limit từ 1–100 (25 mặc định), cursor cho trang tiếp theo, status để lọc theo trạng thái thực thi và search để khớp với email hoặc ID bên ngoài. Phản hồi bao gồm executions và nextCursor.

Lỗi, số lần thử lại và giới hạn tốc độ

Trình kích hoạt trọn đời cho phép 600 yêu cầu mỗi phút đối với mỗi khóa API kích hoạt Nhóm. Các phản hồi bao gồm x-ratelimit-limit, x-ratelimit-remaining và x-ratelimit-reset. Phản hồi 429 cũng bao gồm Retry-After.

Trạng thái	Ý nghĩa	Phải làm gì
`200`	Bản sao `eventId`	Sử dụng việc thực thi được trả về; đừng gửi nữa.
`201`	Đã xếp hàng thực thi mới	Chờ nhân viên xử lý.
`400`	JSON, nội dung hoặc trường cơ bản không hợp lệ	Sửa tải trọng; không thử lại không thay đổi.
`401`	Khóa bị thiếu, không hợp lệ, bị thu hồi, hết hạn hoặc sai phạm vi	Xoay hoặc sửa cấu hình phím.
`402` / `403`	Hạn ngạch hoặc đăng ký ngăn cản việc ghi	Giải quyết vấn đề hạn ngạch hoặc đăng ký. Lỗi hạn ngạch bao gồm `code`, `required`, `available` và `checkoutUrl`.
`404`	Chiến dịch bị thiếu hoặc nằm ngoài không gian làm việc của khóa	Kiểm tra ID chiến dịch và khóa.
`409`	Chiến dịch không hoạt động/không trọn đời hoặc xung đột danh tính liên hệ	Kích hoạt chiến dịch hoặc sửa danh tính liên hệ.
`413`	Yêu cầu vượt quá 64 KiB	Giảm kích thước tải trọng.
`415`	Thiếu `Content-Type: application/json`	Thêm tiêu đề cần thiết.
`422`	`data` không khớp với bảng kê khai biến	Sửa dữ liệu; kiểm tra `details` để tìm đường dẫn và mã lỗi.
`429`	Đã vượt quá giới hạn tỷ lệ	Đợi `Retry-After`, sau đó thử lại với `eventId` tương tự.
`503`	Việc thực thi không thể được xếp hàng đợi	Thử lại với thời gian chờ và `eventId` tương tự.

Đối với 429, 503 và các lỗi mạng, hãy thử lại với thời gian chờ lũy thừa và eventId tương tự. Công việc xếp hàng mang tính quyết định cho việc thực thi, do đó, việc thử lại sẽ không tạo ra email trùng lặp.

Brand settings

Phương pháp	Điểm cuối	Mô tả
`GET`	`/api/v1/settings/brand`	Đọc tên thương hiệu, trang web, email người gửi, logo và cài đặt thiết kế.
`PATCH`	`/api/v1/settings/brand`	Cập nhật cài đặt thương hiệu.

Thế hệ dự thảo AI

Phương pháp	Điểm cuối	Mô tả
`POST`	`/api/v1/ai/generate`	Tạo chủ đề email và bản nháp HTML từ ngữ cảnh chiến dịch.

Máy chủ MCP

Sử dụng Nudgen MCP khi tác nhân của bạn hỗ trợ công cụ Model Context Protocol. MCP dùng OAuth gắn với không gian làm việc bạn chọn; mỗi lần khởi chạy chiến dịch đều cần phê duyệt trong trình duyệt. REST API dùng mã truy cập cá nhân (PAT).

MCP server setup

Cài đặt Nudgen MCP trong Claude Code, Cursor, Windsurf, Codex CLI hoặc MCP chung client.

API Map Leads

Dùng PAT của không gian làm việc đang hoạt động. Tìm kiếm mới dùng hạn mức hằng ngày; phân trang và thử bổ sung thông tin không dùng hạn mức. Hạn mức đặt lại lúc nửa đêm UTC. Bán kính lớn hơn bắt đầu tìm kiếm mới. Lỗi nhà cung cấp hoàn lại lượt đã giữ; hủy tìm kiếm đã chấp nhận không hoàn lại. Tìm kiếm API và MCP mặc định 5 km, chấp nhận số nguyên radiusKm từ 1 đến 100 và không hiển thị hộp thoại xác nhận của bảng điều khiển. Giữ nguyên tham số khi truyền nextPageToken thành pageToken; một trang không có kết quả phù hợp vẫn có thể có trang tiếp theo. Thông tin liên hệ có thể được bổ sung sau khi doanh nghiệp xuất hiện. enrichmentPending đánh dấu việc nghiên cứu website chưa hoàn tất. Xem businessSummary và businessSources khi có; ngữ cảnh doanh nghiệp được nhập có thể hỗ trợ lời mở đầu cá nhân hóa. Chưa có email có thể do nghiên cứu còn đang chờ.

Method	Endpoint
`POST`	`/api/v1/map-leads/suggest`
`POST`	`/api/v1/map-leads/place`
`POST`	`/api/v1/map-leads/search`
`POST`	`/api/v1/map-leads/enrichment-retry`
`POST`	`/api/v1/map-leads/import`
`GET`	`/api/v1/map-leads/quota`
`GET`	`/api/v1/map-leads/geolocate`

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

Nếu có enrichmentRetryToken, gọi POST /api/v1/map-leads/enrichment-retry với token. Công cụ cần PAT, gắn với không gian làm việc đã kết nối, hết hạn sau 15 phút và chỉ dùng một lần. Hợp nhất kết quả theo placeId trước khi nhập. Đặt Accept: application/x-ndjson khi tìm kiếm hoặc thử bổ sung thông tin để nhận kết quả dần. Mỗi dòng JSON có type là progress, complete hoặc error. Hợp nhất data.leads theo placeId; dùng complete.data cuối cùng làm kết quả chính thức. Lỗi nằm trong error. Không có header này, phản hồi là JSON thông thường. POST /place phân giải gợi ý vị trí, không lấy liên hệ doanh nghiệp. GET /geolocate trả vị trí mặc định cố định tại Thành phố Hồ Chí Minh, không xác định vị trí của bạn.

curl -N -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/enrichment-retry" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data "{\"token\":\"$ENRICHMENT_RETRY_TOKEN\"}"

​Tổng quan

​Tại sao điều này lại quan trọng

​URL cơ sở

​Authentication

​Mã thông báo truy cập cá nhân

​Khóa API kích hoạt nhóm

​Điểm cuối REST

​Danh tính và không gian làm việc

​Liên hệ

​Chiến dịch một lần và nhỏ giọt

​Chiến dịch trọn đời

​Tạo chiến dịch trọn đời

​Thay đổi vòng đời

​Kích hoạt một cú huých

​Thực thi danh sách

​Lỗi, số lần thử lại và giới hạn tốc độ

​Brand settings

​Thế hệ dự thảo AI

​Máy chủ MCP

MCP server setup

​API Map Leads

Tổng quan

Tại sao điều này lại quan trọng

URL cơ sở

Authentication

Mã thông báo truy cập cá nhân

Khóa API kích hoạt nhóm

Điểm cuối REST

Danh tính và không gian làm việc

Liên hệ

Chiến dịch một lần và nhỏ giọt

Chiến dịch trọn đời

Tạo chiến dịch trọn đời

Thay đổi vòng đời

Kích hoạt một cú huých

Thực thi danh sách

Lỗi, số lần thử lại và giới hạn tốc độ

Brand settings

Thế hệ dự thảo AI

Máy chủ MCP

API Map Leads