Giao diện
API · customer
Trang sinh tự động
Parse từ schema.graphql (SDL backend export) bằng parser graphql. Mô tả và quyền lấy nguyên văn từ description trong SDL.
8 query · 6 mutation.
Query
customer
One customer (not found and out of scope look the same). Requires customer.read.
query · quyền: customer.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
accountId | ID! |
Trả về Customer!
| Field | Kiểu | Mô tả |
|---|---|---|
accountId | ID! | The User App account id (the customer is the account; no copy is kept). |
customerCode | String | Rule #13 code. Null until registration generates it (GAP-CUST-CODE). |
fullName | String | Profile name (null until the customer sets one). |
phoneMasked | String | Always the database mask; null for an email-only customer (PPI-P3-01). |
group | CustomerGroupRef | Null only while no customer group exists yet. |
status | CustomerStatus! | |
accountLocked | Boolean! | Locked or suspended at account level: status cannot be changed here. |
isSale | Boolean! | Also a Sale whose Sale account is ACTIVE or LOCKED (Rule #1, #299); the code is in sale. |
description | String | |
tags | [String!]! | |
joinedAt | DateTime! | |
version | Int! | |
updatedAt | DateTime | Last Admin edit; null if never edited. |
purchase | CustomerPurchase! | |
debt | CustomerDebt! | |
pointBalance | PointBalance! | KH-US-03 "Pi-Point hiện tại": read from PiPoint (external) on every request through the bounded per-request port (U6-P3-33), never stored, summed or computed in PIDEAL. Provider figures as reported (GAP-05, decided Q-4: PIDEAL adds and subtracts nothing; available is the figure shown as "Pi-Point hiện tại"). NOT_LINKED differs from 0; a provider failure is UNAVAILABLE, an answer that cannot be read has sourceStatus UNKNOWN: no number in either case, never 0. |
addresses | [CustomerAddress!]! | Every live delivery address (KH-US-03 AC10), the default first, read only (Rule #4: no add, edit or delete on the Admin Portal). recipientPhone and addressLine are full for a caller holding customer.pii.read (piiMasked false), masked otherwise; province, district and ward are readable. Same customer.read as the parent. |
openOrderCount | Int! | Orders not in a terminal state (deposit pending, placed, locked): the N of the lock banner (KH-US-03 AC19). A real 0 means none; a read that cannot be answered is an error, never 0. |
phone | String | Display phone (0 + 9 digits for +84, else E.164): the full number for a caller holding customer.pii.read (O-05), otherwise the database mask; null for an email-only customer (PPI-P3-01, E-01). |
piiMasked | Boolean! | True when the caller lacks customer.pii.read: phone, login email and address lines are masked, profile email and date of birth are null. |
email | String | User App profile (contact) email; null when not declared. Kept apart from loginEmail (B-05). |
loginEmail | String | Login email (the PiPoint identity, B-05; PPI-P3-07): in full for a caller holding customer.pii.read (O-05), otherwise the database mask (n***@domain); null for an account without one. |
dateOfBirth | String | Calendar date YYYY-MM-DD (no time zone); null when not declared. |
gender | CustomerGender | Null when not declared. |
referralCode | String | Referral code from the profile (read only; attribution is not rewritten). |
sale | CustomerSaleRef | Set when the customer is also a Sale whose Sale account is ACTIVE or LOCKED (Rule #1, #299); null for a pending or rejected applicant or a suspended Sale. |
defaultAddress | CustomerAddress | The live address flagged default; null when there is none. |
tier | CustomerTier | Null when Loyalty holds no Tier for the customer. |
customerColumnPreference
The calling Admin's customer-list columns, or the default when none are saved (AC16, AC20). Requires customer.read.
query · quyền: customer.read
Không có tham số.
Trả về CustomerColumnPreference!
| Field | Kiểu | Mô tả |
|---|---|---|
columns | [CustomerColumn!]! | Visible columns in the fixed order; CODE, NAME and PHONE always included. |
isDefault | Boolean! | The columns are the default set: CODE, NAME, PHONE, GROUP, DEBT, ORDER_COUNT, TOTAL_SPEND, STATUS (AC19). |
updatedAt | DateTime | Last save of this Admin; null while nothing is saved (the default applies). |
customerGroupAvailability
Code/name already used by another live group (deleted groups do not count). Requires customer_group.write.
query · quyền: customer_group.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
code | String | ||
name | String | ||
excludeId | ID |
Trả về CustomerGroupAvailability!
| Field | Kiểu | Mô tả |
|---|---|---|
codeTaken | Boolean! | A live group other than excludeId has this code (trim, case-insensitive); false when not asked. |
nameTaken | Boolean! | A live group other than excludeId has this name (trim, case-insensitive); false when not asked. |
customerGroups
Live customer groups with their counts (NK-US-01); search is partial and case-insensitive on the name only. 50 rows per page by default, up to 500. Order by "sort" (default CREATED_ASC: oldest first, NEW-NK-01 owner-accepted 2026-10-09), then id. Requires customer_group.read.
query · quyền: customer_group.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String | ||
sort | CustomerGroupSort | CREATED_ASC | |
page | Int | 1 | |
pageSize | Int | 50 |
Trả về CustomerGroupPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [CustomerGroup!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
sourceStatus | SourceStatus! | |
defaultGroup | CustomerGroup | The current default group, whatever the search and page; null only if the seeded default group was removed by hand; the migration seeds MAC_DINH (U6-P7-67, Q-9). |
customerOrders
Purchase history of one customer (KH-US-03 AC07): every status, newest creation first; the default page of 5 is the detail block. Unknown, not a User App customer (Rule #1) and out of scope look the same (not_found). Requires customer.read.
query · quyền: customer.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
accountId | ID! | ||
page | Int | 1 | |
pageSize | Int | 5 |
Trả về CustomerOrderPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [CustomerOrder!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
sourceStatus | SourceStatus! |
customers
User App customers only (Rule #1), all filter conditions AND. Order by "sort" (default JOINED_DESC: newest join first, KH-US-01 AC01), ties by account id. pageSize 1..500, default 50 (Rule #7). Requires customer.read; personal data in full needs customer.pii.read.
query · quyền: customer.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
filter | CustomerFilterInput | ||
sort | CustomerSort | JOINED_DESC | |
page | Int | 1 | |
pageSize | Int | 50 |
Trả về CustomerPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [Customer!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
sourceStatus | SourceStatus! |
customerTierOptions
U6-P3-28 Tier filter options: USER Tiers in force (Loyalty), Standard included, by rank. Requires customer.read.
query · quyền: customer.read
Không có tham số.
Trả về [CustomerTierOption!]!
| Field | Kiểu | Mô tả |
|---|---|---|
tierId | ID! | |
name | String! | |
rankOrder | Int! |
provinces
U6-P3-28 Province / City catalogue of the address filter: the 34 provincial-level units, by name (NEW-KH-13, Q-11). Requires customer.read.
query · quyền: customer.read
Không có tham số.
Trả về [Province!]!
| Field | Kiểu | Mô tả |
|---|---|---|
code | String! | |
name | String! |
Mutation
deleteCustomerGroup
Soft-delete a non-default group after moving its customers to the default (NKH-US-03).
mutation · SDL không ghi quyền
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | DeleteCustomerGroupInput! |
Trả về DeleteCustomerGroupResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
movedCount | Int! | Customers moved to the default group before the delete (NKH-US-03 AC02). |
defaultGroupId | ID! |
exportCustomers
Export every customer matching the filter (all pages, 21 columns, personal data in full) as a private .xlsx (KH-US-02). Requires customer.export (MFA step-up) and customer.pii.read; no match creates no file and no log.
mutation · quyền: customer.export
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | ExportCustomersInput! |
Trả về ExportCustomersResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
rowCount | Int! | 0 with file null: nothing matched and nothing was created (AC05). |
file | CustomerExportFile |
saveCustomer
Edit group/status/description/tags of one customer (KH-US-03).
mutation · SDL không ghi quyền
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SaveCustomerInput! |
Trả về SaveCustomerResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when nothing differed and nothing was written (AC24). |
customer | Customer! |
saveCustomerColumnPreference
Save the calling Admin's customer-list columns ("Áp dụng", AC18; "Đặt lại mặc định" then "Áp dụng" saves the default set, AC19). Last write wins per account; not audited (personal display setting). Requires customer.read.
mutation · quyền: customer.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SaveCustomerColumnPreferenceInput! |
Trả về SaveCustomerColumnPreferenceResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The Admin account id (one configuration per Admin). |
version | Int! | Version of the stored configuration; 0 while nothing is stored. |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when the columns equal what already applies: nothing written. |
preference | CustomerColumnPreference! |
saveCustomerGroup
Create or edit a customer group, optionally making it the default (NKH-US-02).
mutation · SDL không ghi quyền
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SaveCustomerGroupInput! |
Trả về SaveCustomerGroupResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when an edit equals the stored group: nothing written, no audit row (U6-P3-36). |
group | CustomerGroup! |
transferCustomerGroup
Move customers to one group, all or nothing (KH-US-01).
mutation · SDL không ghi quyền
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | TransferCustomerGroupInput! |
Trả về TransferCustomerGroupResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
transferredCount | Int! | |
customers | [TransferredCustomer!]! |