Files
pos-system/services/mkt-x-service-net/docs/vi/API.md

24 KiB

Dịch Vụ MKT X/Twitter - Tài Liệu API

Mục Lục

  1. Tổng Quan API
  2. Xác Thực
  3. Quản Lý Tài Khoản
  4. Quản Lý Liên Hệ
  5. Quản Lý Hội Thoại
  6. Quản Lý Template
  7. Quản Lý Chiến Dịch
  8. Quản Lý Segment
  9. Automation Flows
  10. AI Chatbot
  11. Phân Tích
  12. Webhooks
  13. Xử Lý Lỗi

Tổng Quan API

Base URL

Development: http://localhost:5000/api/v1/mkt-x
Production:  https://api.goodgo.com/api/v1/mkt-x

Versioning

API versioning được xử lý thông qua URL path (/api/v1/).

Định Dạng Request

Tất cả requests với body nên sử dụng:

Content-Type: application/json

Định Dạng Response

Tất cả responses tuân theo cấu trúc này:

Success Response

{
  "success": true,
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Error Response

{
  "success": false,
  "error": "Mô tả lỗi"
}

Xác Thực

JWT Bearer Token

Tất cả API endpoints (ngoại trừ webhooks) yêu cầu xác thực qua JWT bearer token.

Request Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Lấy Token

Tokens được lấy từ IAM service:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "refresh...",
    "expiresIn": 3600
  }
}

Quản Lý Tài Khoản

Kết Nối Tài Khoản Twitter

Kết nối tài khoản Twitter sử dụng OAuth 1.0a credentials.

Endpoint

POST /accounts

Request Body

{
  "oauthToken": "oauth_token_từ_twitter",
  "oauthTokenSecret": "oauth_token_secret_từ_twitter"
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "merchantId": "merchant-uuid",
    "twitterUserId": "123456789",
    "username": "goodgo_shop",
    "displayName": "GoodGo Official",
    "status": "active",
    "connectedAt": "2026-01-18T10:00:00Z"
  }
}

Mã Lỗi

  • 400 - OAuth credentials không hợp lệ
  • 401 - Unauthorized
  • 409 - Tài khoản đã được kết nối

Danh Sách Tài Khoản Đã Kết Nối

Lấy tất cả tài khoản Twitter đã kết nối bởi merchant.

Endpoint

GET /accounts

Query Parameters

  • status (tùy chọn) - Lọc theo trạng thái: active, inactive, error

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "merchantId": "uuid",
      "twitterUserId": "123456789",
      "username": "goodgo_shop",
      "displayName": "GoodGo Official",
      "status": "active",
      "connectedAt": "2026-01-18T10:00:00Z"
    }
  ]
}

Lấy Chi Tiết Tài Khoản

Lấy thông tin chi tiết về tài khoản Twitter cụ thể.

Endpoint

GET /accounts/{accountId}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "merchantId": "uuid",
    "twitterUserId": "123456789",
    "username": "goodgo_shop",
    "displayName": "GoodGo Official",
    "profileImageUrl": "https://pbs.twimg.com/profile_images/...",
    "status": "active",
    "webhookId": "webhook-id",
    "connectedAt": "2026-01-18T10:00:00Z",
    "statistics": {
      "totalContacts": 1234,
      "totalConversations": 567,
      "messagesThisMonth": 890
    }
  }
}

Mã Lỗi

  • 404 - Không tìm thấy tài khoản

Ngắt Kết Nối Tài Khoản

Ngắt kết nối tài khoản Twitter và thu hồi OAuth tokens.

Endpoint

DELETE /accounts/{accountId}

Response 200 OK

{
  "success": true,
  "data": null
}

Cập Nhật Cài Đặt Tài Khoản

Cập nhật cài đặt cấu hình tài khoản.

Endpoint

PUT /accounts/{accountId}

Request Body

{
  "autoReplyEnabled": true,
  "businessHours": {
    "enabled": true,
    "timezone": "Asia/Ho_Chi_Minh",
    "schedule": {
      "monday": { "start": "09:00", "end": "18:00" },
      "tuesday": { "start": "09:00", "end": "18:00" }
    }
  }
}

Response 200 OK


Quản Lý Liên Hệ

Danh Sách Liên Hệ

Lấy danh sách liên hệ có phân trang với filtering.

Endpoint

GET /contacts

Query Parameters

  • accountId (tùy chọn) - Lọc theo tài khoản Twitter
  • tags (tùy chọn) - Tags phân cách bằng dấu phẩy: vip,customer
  • search (tùy chọn) - Tìm kiếm trong username/display name
  • skip (tùy chọn, mặc định: 0) - Pagination offset
  • take (tùy chọn, mặc định: 20, tối đa: 100) - Items per page

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "accountId": "uuid",
      "twitterUserId": "987654321",
      "username": "customer_john",
      "displayName": "John Doe",
      "profileImageUrl": "https://...",
      "tags": ["vip", "customer"],
      "attributes": {
        "purchaseCount": 5,
        "totalSpent": 1250000,
        "lastPurchaseDate": "2026-01-15"
      },
      "conversationCount": 3,
      "firstInteractionAt": "2025-12-01T10:00:00Z",
      "lastInteractionAt": "2026-01-18T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1234,
    "totalPages": 62
  }
}

Lấy Chi Tiết Liên Hệ

Lấy thông tin chi tiết về liên hệ cụ thể.

Endpoint

GET /contacts/{contactId}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "twitterUserId": "987654321",
    "username": "customer_john",
    "displayName": "John Doe",
    "profileImageUrl": "https://...",
    "tags": ["vip", "customer"],
    "attributes": {
      "purchaseCount": 5,
      "totalSpent": 1250000,
      "lastPurchaseDate": "2026-01-15",
      "preferredLanguage": "vi"
    },
    "source": "inbound_message",
    "conversationCount": 3,
    "firstInteractionAt": "2025-12-01T10:00:00Z",
    "lastInteractionAt": "2026-01-18T09:30:00Z",
    "engagement": {
      "messagesSent": 15,
      "messagesReceived": 18,
      "averageResponseTime": "5m 30s"
    }
  }
}

Cập Nhật Liên Hệ

Cập nhật thông tin liên hệ.

Endpoint

PUT /contacts/{contactId}

Request Body

{
  "displayName": "John Doe (VIP)",
  "attributes": {
    "preferredLanguage": "vi",
    "notes": "Khách hàng cao cấp"
  }
}

Response 200 OK


Thêm Tags vào Liên Hệ

Thêm một hoặc nhiều tags vào liên hệ.

Endpoint

POST /contacts/{contactId}/tags

Request Body

{
  "tags": ["vip", "premium"]
}

Response 200 OK


Xóa Tag khỏi Liên Hệ

Xóa tag cụ thể khỏi liên hệ.

Endpoint

DELETE /contacts/{contactId}/tags/{tagName}

Response 200 OK


Cập Nhật Thuộc Tính Liên Hệ

Cập nhật hàng loạt thuộc tính tùy chỉnh cho liên hệ.

Endpoint

PUT /contacts/{contactId}/attributes

Request Body

{
  "attributes": {
    "purchaseCount": 6,
    "totalSpent": 1500000,
    "lastPurchaseDate": "2026-01-18",
    "membershipTier": "gold"
  }
}

Response 200 OK


Lấy Hội Thoại của Liên Hệ

Lấy tất cả hội thoại cho liên hệ cụ thể.

Endpoint

GET /contacts/{contactId}/conversations

Query Parameters

  • status (tùy chọn) - Lọc theo trạng thái: open, closed
  • skip (tùy chọn) - Pagination offset
  • take (tùy chọn) - Items per page

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "contactId": "uuid",
      "status": "open",
      "messageCount": 5,
      "startedAt": "2026-01-18T09:00:00Z",
      "lastMessageAt": "2026-01-18T09:30:00Z"
    }
  ]
}

Xóa Liên Hệ

Xóa liên hệ và tất cả dữ liệu liên quan (tuân thủ GDPR).

Endpoint

DELETE /contacts/{contactId}

Response 200 OK


Quản Lý Hội Thoại

Danh Sách Hội Thoại

Lấy danh sách hội thoại có phân trang.

Endpoint

GET /conversations

Query Parameters

  • accountId (tùy chọn) - Lọc theo tài khoản
  • status (tùy chọn) - Lọc theo trạng thái: open, closed
  • assignedTo (tùy chọn) - Lọc theo user ID được gán
  • skip (tùy chọn) - Pagination offset
  • take (tùy chọn) - Items per page

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "contactId": "uuid",
      "accountId": "uuid",
      "status": "open",
      "channel": "direct_message",
      "assignedToUserId": "uuid",
      "messageCount": 12,
      "startedAt": "2026-01-18T09:00:00Z",
      "lastMessageAt": "2026-01-18T10:15:00Z",
      "contact": {
        "username": "customer_john",
        "displayName": "John Doe"
      }
    }
  ],
  "pagination": { ... }
}

Lấy Hội Thoại với Tin Nhắn

Lấy chi tiết hội thoại bao gồm tất cả tin nhắn.

Endpoint

GET /conversations/{conversationId}

Query Parameters

  • includeMessages (tùy chọn, mặc định: true) - Bao gồm lịch sử tin nhắn

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "contactId": "uuid",
    "accountId": "uuid",
    "status": "open",
    "channel": "direct_message",
    "assignedToUserId": "uuid",
    "startedAt": "2026-01-18T09:00:00Z",
    "messages": [
      {
        "id": "uuid",
        "conversationId": "uuid",
        "direction": "inbound",
        "type": "text",
        "content": "Xin chào, tôi có câu hỏi về đơn hàng",
        "attachments": [],
        "isFromBot": false,
        "sentAt": "2026-01-18T09:00:00Z"
      },
      {
        "id": "uuid",
        "conversationId": "uuid",
        "direction": "outbound",
        "type": "text",
        "content": "Chào bạn! Tôi rất vui được hỗ trợ. Mã đơn hàng của bạn là gì?",
        "attachments": [],
        "isFromBot": false,
        "sentAt": "2026-01-18T09:02:00Z"
      }
    ]
  }
}

Gửi Tin Nhắn

Gửi tin nhắn trong hội thoại.

Endpoint

POST /conversations/{conversationId}/messages

Request Body

{
  "content": "Đơn hàng #12345 của bạn đã được gửi đi!",
  "type": "text",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/tracking.png"
    }
  ]
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "conversationId": "uuid",
    "twitterMessageId": "123456789",
    "direction": "outbound",
    "type": "text",
    "content": "Đơn hàng #12345 của bạn đã được gửi đi!",
    "sentAt": "2026-01-18T10:30:00Z"
  }
}

Mã Lỗi

  • 400 - Nội dung tin nhắn vượt quá giới hạn Twitter (10,000 ký tự)
  • 429 - Vượt quá rate limit

Đóng Hội Thoại

Đóng hội thoại đang hoạt động.

Endpoint

PUT /conversations/{conversationId}/close

Request Body (tùy chọn)

{
  "reason": "resolved"
}

Response 200 OK


Gán Hội Thoại

Gán hội thoại cho user/agent cụ thể.

Endpoint

POST /conversations/{conversationId}/assign

Request Body

{
  "userId": "user-uuid"
}

Response 200 OK


Quản Lý Template

Tạo Template

Tạo template tin nhắn mới.

Endpoint

POST /templates

Request Body

{
  "name": "Tin Nhắn Chào Mừng",
  "type": "text",
  "content": "Chào {{name}}, chào mừng đến {{shop_name}}! Sử dụng mã {{discount_code}} để được giảm giá 10% cho đơn hàng đầu tiên.",
  "variables": ["name", "shop_name", "discount_code"]
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "merchantId": "uuid",
    "name": "Tin Nhắn Chào Mừng",
    "type": "text",
    "content": "Chào {{name}}, chào mừng đến...",
    "variables": ["name", "shop_name", "discount_code"],
    "createdAt": "2026-01-18T10:00:00Z"
  }
}

Danh Sách Templates

Lấy tất cả templates của merchant.

Endpoint

GET /templates

Query Parameters

  • type (tùy chọn) - Lọc theo loại: text, quick_reply, card
  • search (tùy chọn) - Tìm kiếm trong tên template

Response 200 OK


Lấy Template

Lấy chi tiết template.

Endpoint

GET /templates/{templateId}

Response 200 OK


Cập Nhật Template

Cập nhật template hiện có.

Endpoint

PUT /templates/{templateId}

Request Body

{
  "name": "Tin Nhắn Chào Mừng Đã Cập Nhật",
  "content": "Xin chào {{name}}!..."
}

Response 200 OK


Xóa Template

Xóa template.

Endpoint

DELETE /templates/{templateId}

Response 200 OK

Mã Lỗi

  • 409 - Template đang được sử dụng bởi chiến dịch đang hoạt động

Xem Trước Template

Xem trước template đã render với dữ liệu mẫu.

Endpoint

POST /templates/{templateId}/preview

Request Body

{
  "variables": {
    "name": "John",
    "shop_name": "GoodGo Shop",
    "discount_code": "WELCOME10"
  }
}

Response 200 OK

{
  "success": true,
  "data": {
    "rendered": "Chào John, chào mừng đến GoodGo Shop! Sử dụng mã WELCOME10 để được giảm giá 10% cho đơn hàng đầu tiên."
  }
}

Quản Lý Chiến Dịch

Tạo Chiến Dịch

Tạo chiến dịch tin nhắn mới.

Endpoint

POST /campaigns

Request Body

{
  "name": "Khuyến Mãi Tết 2026",
  "templateId": "template-uuid",
  "segmentIds": ["segment-uuid-1", "segment-uuid-2"],
  "schedule": {
    "startAt": "2026-01-25T09:00:00Z",
    "endAt": "2026-01-31T23:59:59Z"
  },
  "variables": {
    "discount_code": "TET2026"
  }
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "merchantId": "uuid",
    "name": "Khuyến Mãi Tết 2026",
    "status": "scheduled",
    "targetContactCount": 1500,
    "createdAt": "2026-01-18T10:00:00Z"
  }
}

Danh Sách Chiến Dịch

Lấy tất cả chiến dịch.

Endpoint

GET /campaigns

Query Parameters

  • status (tùy chọn) - Lọc theo trạng thái: draft, scheduled, running, paused, completed
  • skip (tùy chọn) - Pagination offset
  • take (tùy chọn) - Items per page

Response 200 OK


Lấy Chi Tiết Chiến Dịch

Endpoint

GET /campaigns/{campaignId}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Khuyến Mãi Tết 2026",
    "status": "running",
    "templateId": "uuid",
    "segmentIds": ["uuid"],
    "schedule": {
      "startAt": "2026-01-25T09:00:00Z",
      "endAt": "2026-01-31T23:59:59Z"
    },
    "metrics": {
      "totalSent": 1200,
      "delivered": 1180,
      "opened": 850,
      "clicked": 320,
      "replied": 45,
      "failed": 20
    }
  }
}

Bắt Đầu Chiến Dịch

Bắt đầu thực thi chiến dịch.

Endpoint

POST /campaigns/{campaignId}/start

Response 200 OK


Tạm Dừng Chiến Dịch

Tạm dừng chiến dịch đang chạy.

Endpoint

POST /campaigns/{campaignId}/pause

Response 200 OK


Tiếp Tục Chiến Dịch

Tiếp tục chiến dịch đã tạm dừng.

Endpoint

POST /campaigns/{campaignId}/resume

Response 200 OK


Lấy Số Liệu Chiến Dịch

Lấy số liệu chi tiết cho chiến dịch.

Endpoint

GET /campaigns/{campaignId}/metrics

Response 200 OK

{
  "success": true,
  "data": {
    "totalSent": 1200,
    "delivered": 1180,
    "deliveryRate": 98.3,
    "opened": 850,
    "openRate": 72.0,
    "clicked": 320,
    "clickRate": 37.6,
    "replied": 45,
    "replyRate": 5.3,
    "failed": 20,
    "failureRate": 1.7
  }
}

Quản Lý Segment

Tạo Segment

Tạo phân khúc khách hàng mới.

Endpoint

POST /segments

Request Body

{
  "name": "Khách Hàng VIP",
  "conditions": [
    {
      "field": "attributes.purchaseCount",
      "operator": "gte",
      "value": 5
    },
    {
      "field": "tags",
      "operator": "contains",
      "value": "vip"
    }
  ]
}

Response 200 OK


Danh Sách Segments

Endpoint

GET /segments

Response 200 OK


Đánh Giá Segment

Lấy số lượng liên hệ khớp với điều kiện segment.

Endpoint

POST /segments/{segmentId}/evaluate

Response 200 OK

{
  "success": true,
  "data": {
    "segmentId": "uuid",
    "contactCount": 345,
    "sampleContacts": [
      {
        "id": "uuid",
        "username": "customer_1",
        "displayName": "Customer 1"
      }
    ]
  }
}

Automation Flows

Tạo Automation Flow

Tạo workflow tự động hóa.

Endpoint

POST /automation/flows

Request Body

{
  "name": "Chào Mừng Khách Hàng Mới",
  "trigger": {
    "type": "contact_created",
    "config": {}
  },
  "nodes": [
    {
      "type": "send_message",
      "templateId": "welcome-template-uuid",
      "delay": 0
    },
    {
      "type": "wait",
      "duration": 86400
    },
    {
      "type": "send_message",
      "templateId": "followup-template-uuid",
      "delay": 0
    }
  ]
}

Response 200 OK


Kích Hoạt Flow

Kích hoạt automation flow.

Endpoint

POST /automation/flows/{flowId}/activate

Response 200 OK


Hủy Kích Hoạt Flow

Hủy kích hoạt automation flow.

Endpoint

POST /automation/flows/{flowId}/deactivate

Response 200 OK


AI Chatbot

Gửi Tin Nhắn AI

Gửi tin nhắn và nhận phản hồi AI.

Endpoint

POST /ai/conversations/{conversationId}/message

Request Body

{
  "message": "Tôi muốn kiểm tra đơn hàng của tôi"
}

Response 200 OK

{
  "success": true,
  "data": {
    "message": "Dạ, tôi có thể giúp bạn kiểm tra đơn hàng. Vui lòng cho tôi biết mã đơn hàng của bạn.",
    "intent": "check_order",
    "confidence": 0.95,
    "needsHumanEscalation": false
  }
}

Cấu Hình AI Chatbot

Cập nhật cài đặt AI chatbot cho tài khoản.

Endpoint

PUT /ai/accounts/{accountId}/config

Request Body

{
  "enabled": true,
  "model": "gpt-4",
  "systemPrompt": "Bạn là trợ lý ảo của GoodGo Shop...",
  "temperature": 0.7,
  "escalationThreshold": 0.6
}

Response 200 OK


Phân Tích

Tổng Quan Analytics

Lấy số liệu tổng quan cho merchant.

Endpoint

GET /analytics/overview

Query Parameters

  • startDate (bắt buộc) - Ngày bắt đầu (YYYY-MM-DD)
  • endDate (bắt buộc) - Ngày kết thúc (YYYY-MM-DD)
  • accountId (tùy chọn) - Lọc theo tài khoản

Response 200 OK

{
  "success": true,
  "data": {
    "period": {
      "startDate": "2026-01-01",
      "endDate": "2026-01-18"
    },
    "summary": {
      "totalContacts": 1234,
      "newContacts": 145,
      "totalConversations": 567,
      "activeConversations": 89,
      "messagesSent": 2340,
      "messagesReceived": 1890,
      "campaignsCompleted": 12,
      "averageResponseTime": "3m 45s"
    },
    "trends": {
      "contactsGrowth": 12.5,
      "conversationsGrowth": 8.3,
      "messagesGrowth": -2.1
    }
  }
}

Phân Tích Liên Hệ

Lấy thống kê về liên hệ.

Endpoint

GET /analytics/contacts

Response 200 OK


Phân Tích Hội Thoại

Lấy số liệu về hội thoại.

Endpoint

GET /analytics/conversations

Response 200 OK


Phân Tích Chiến Dịch

Lấy hiệu suất chiến dịch.

**Endpoint``` GET /analytics/campaigns


**Response** `200 OK`

---

## Webhooks

### Endpoint Webhook

Twitter sẽ gửi events đến:

POST /webhooks/twitter


### Xác Minh CRC

Twitter gửi challenge để xác minh webhook:

GET /webhooks/verify?crc_token=xxx


**Response** `200 OK`
```json
{
  "response_token": "sha256=..."
}

Sự Kiện Webhook

Direct Message Event

{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "123456789",
      "created_timestamp": "1642000000000",
      "message_create": {
        "sender_id": "987654321",
        "message_data": {
          "text": "Xin chào!"
        }
      }
    }
  ]
}

Xử Lý Lỗi

Mã Lỗi HTTP

Ý Nghĩa Mô Tả
400 Bad Request Request không hợp lệ hoặc thiếu tham số
401 Unauthorized Token xác thực không hợp lệ hoặc thiếu
403 Forbidden Không có quyền truy cập tài nguyên
404 Not Found Không tìm thấy tài nguyên
409 Conflict Xung đột với trạng thái hiện tại
422 Unprocessable Entity Validation failed
429 Too Many Requests Vượt quá rate limit
500 Internal Server Error Lỗi server

Error Response Structure

{
  "success": false,
  "error": "Mô tả lỗi",
  "errorCode": "ERROR_CODE",
  "details": {
    "field": "fieldName",
    "message": "Chi tiết lỗi"
  }
}

Validation Errors

{
  "success": false,
  "error": "Validation failed",
  "errorCode": "VALIDATION_ERROR",
  "details": [
    {
      "field": "templateId",
      "message": "Template ID là bắt buộc"
    },
    {
      "field": "segmentIds",
      "message": "Cần ít nhất một segment"
    }
  ]
}

Rate Limiting

Service thực thi các giới hạn sau:

  • API Calls: 100 requests/phút mỗi merchant
  • Message Sending: 500 tin nhắn/24 giờ mỗi tài khoản Twitter
  • Webhook Processing: 1000 events/phút

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642000000

Pagination

Tất cả list endpoints hỗ trợ pagination:

Query Parameters:

  • skip - Offset (mặc định: 0)
  • take - Limit (mặc định: 20, tối đa: 100)

Response:

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1234,
    "totalPages": 62
  }
}

Best Practices

1. Sử Dụng Pagination

Luôn sử dụng pagination cho list endpoints để tránh timeout.

2. Xử Lý Rate Limits

Implement exponential backoff khi nhận 429 errors.

3. Validate Input

Validate dữ liệu trước khi gửi để giảm lỗi validation.

4. Sử Dụng Webhooks

Sử dụng webhooks thay vì polling để nhận real-time updates.

5. Cache Responses

Cache responses khi phù hợp để giảm API calls.


Tài Nguyên Bổ Sung


Hỗ Trợ

Để được hỗ trợ về API: