DNC list

Quản lý danh sách Do-Not-Call (DNC) của khách hàng: tra cứu, thêm/xoá đơn lẻ, bulk import CSV và export. Mọi số điện thoại đều được normalise sang E.164 (+84...) tự động ở phía server.

Tổng quan endpoint

Endpoint	Mục đích
GET /api/telesales/dnc	Liệt kê số điện thoại trong DNC
POST /api/telesales/dnc	Thêm một số vào DNC
DELETE /api/telesales/dnc/{phone}	Gỡ một số khỏi DNC
POST /api/telesales/dnc/import	Bulk import qua CSV (multipart)
GET /api/telesales/dnc/export	Export toàn bộ DNC ra CSV

GET /api/telesales/dnc — danh sách

Query parameters

Field	Type	Required	Mô tả	Giá trị hợp lệ
q	string	optional	Tìm theo số điện thoại (LIKE %keyword%)
source	string	optional	Lọc theo nguồn ghi nhận	manual / import / disposition / webhook
date_from	datetime	optional	Lọc added_at ≥ (ISO 8601 UTC)
date_to	datetime	optional	Lọc added_at ≤ (ISO 8601 UTC)
page	integer	optional	Số trang	≥ 1 (default 1)
per_page	integer	optional	Bản ghi mỗi trang	1-200 (default 50)

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
phone	string	Số điện thoại gốc (định dạng khi insert)
phone_e164	string	Số chuẩn hoá E.164	+84...
reason	string|null	Lý do thêm vào DNC	max 500 ký tự
source	string	Nguồn ghi nhận	manual / import / disposition / webhook
added_by	integer|null	User ID người thêm (null nếu từ webhook/system)
added_by_name	string|null	Tên hiển thị người thêm
added_at	datetime	Thời điểm thêm (ISO 8601 UTC)

Response 200:

{
  "data": [
    {
      "phone": "0900000000",
      "phone_e164": "+84900000000",
      "reason": "Customer opt-out",
      "source": "manual",
      "added_by": 7,
      "added_by_name": "Nguyen Van A",
      "added_at": "2026-04-01T03:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 124 }
}

POST /api/telesales/dnc — thêm một số

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
phone	string	✅	Số điện thoại — server tự normalise về +84...	0xxxxxxxxx hoặc +84xxxxxxxxx
reason	string	optional	Lý do thêm vào DNC	max 500 ký tự

Body:

{
  "phone": "0912345678",
  "reason": "Customer opt-out via inbound IVR"
}

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
phone	string	Số gốc khi POST
phone_e164	string	Số đã chuẩn hoá	+84...
reason	string|null	Lý do
source	string	Nguồn — luôn manual khi tạo qua endpoint này	manual
added_by	integer	User ID người tạo
added_at	datetime	Thời điểm tạo (ISO 8601 UTC)

Response 201:

{
  "data": {
    "phone": "0912345678",
    "phone_e164": "+84912345678",
    "reason": "Customer opt-out via inbound IVR",
    "source": "manual",
    "added_by": 7,
    "added_at": "2026-06-06T07:00:00Z"
  }
}

Response 422 — các trường hợp validate sai:

// Số điện thoại sai định dạng
{
  "message": "The given data was invalid.",
  "errors": { "phone": ["The phone format is invalid. Expected 0xxxxxxxxx or +84xxxxxxxxx."] }
}

// Số đã có trong DNC
{
  "message": "Phone number is already on the DNC list.",
  "errors": { "phone": ["Phone +84912345678 already in DNC since 2026-05-01."] }
}

DELETE /api/telesales/dnc/{phone}

{phone} chấp nhận cả 0xxxxxxxxx và +84xxxxxxxxx (server tự normalise).

Response 204 No Content (thành công).

Response 404 — số không có trong DNC:

{ "message": "Phone +84912345678 not found in DNC." }

POST /api/telesales/dnc/import — bulk CSV

Request: multipart/form-data

Field	Mô tả
file	File CSV (UTF-8). Cột bắt buộc: phone. Cột tuỳ chọn: reason.
dedupe	skip (mặc định — bỏ qua dòng đã tồn tại) | update (ghi đè reason)

Ví dụ định dạng file:

phone,reason
0912345678,Customer opt-out
0987654321,Wrong number

Response 200:

{
  "data": {
    "total_rows":   1500,
    "created":      1342,
    "skipped":      147,
    "errors":       11,
    "error_samples": [
      { "row": 23, "phone": "12345",       "error": "Invalid phone format" },
      { "row": 47, "phone": "0999999999",  "error": "Already exists" }
    ]
  }
}

Response 422 — file đọc không được:

{
  "message": "Unable to read the CSV file.",
  "errors": { "file": ["Missing required column: phone."] }
}

GET /api/telesales/dnc/export

Query params: cùng bộ filter với GET /api/telesales/dnc (q, source, date_from, date_to).

Response 200: text/csv — file stream với header Content-Disposition: attachment; filename="dnc-export-YYYYMMDD.csv". Các cột: phone, phone_e164, reason, source, added_by_name, added_at.