Giao diện
API · fulfillment
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 · 7 mutation.
Query
cycleScheduleForStaff
Cycle schedule of Recurring orders for Operations, by campaign, order, state and date. Requires order.read (OPS-02).
query · quyền: order.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
filter | StaffCycleScheduleFilter | ||
page | Int | 1 | |
pageSize | Int | 20 |
Trả về StaffCyclePage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [StaffCycle!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! |
fulfillmentExceptions
Exceptions of a shipment or an order, newest first. Requires order.read (GAP-51).
query · quyền: order.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
shipmentId | ID | ||
orderId | ID | ||
page | Int | ||
pageSize | Int |
Trả về FulfillmentExceptionPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [FulfillmentException!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! |
orderDeliveryProgress
Delivery progress of one order, per Group Buy order / Recurring cycle. Requires order.read (U-01 own, M-02 TEAM). A missing or out-of-scope order is not_found.
query · quyền: order.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
orderId | ID! |
Trả về OrderDeliveryProgress!
| Field | Kiểu | Mô tả |
|---|---|---|
orderId | ID! | |
campaignType | OrderCampaignType! | |
orderState | OrderState! | |
committedUnits | Int! | Delivery units the order commits to (1 for Group Buy). |
deliveredUnits | Int! | Units whose shipment is DELIVERED (a skipped cycle never counts). |
units | [DeliveryProgressUnit!]! |
shipment
One shipment with items and timeline. Requires shipment.read.
query · quyền: shipment.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
id | ID! |
Trả về Shipment!
| Field | Kiểu | Mô tả |
|---|---|---|
id | ID! | |
carrierCode | String! | Opaque partner code (logistics provider undecided). |
carrierRef | String! | Partner reference / tracking number, distinct from the internal id. |
scheduleKind | ShipmentScheduleKind! | |
campaignId | ID | Null for a MIXED shipment (several campaigns or Group Buy + Recurring): read the campaign per component through its order. |
milestoneId | ID | |
cycleNo | Int | |
deliversFromVn | String! | |
deliversToVn | String! | |
expectedOn | String! | |
recipient | ShipmentRecipient! | |
handedOverAt | DateTime! | |
state | ShipmentState! | |
version | Int! | |
stateChangedAt | DateTime! | |
lastEventAt | DateTime! | |
deliveredAt | DateTime | |
createdBy | ID! | |
createdAt | DateTime! | |
items | [ShipmentItem!]! | |
codTotalVnd | VndAmount | Trip COD = sum of the remaining COD obligations of the items (A-FF-01 AC06). Null = unavailable. |
timeline | [FulfillmentEvent!]! | |
shipmentCode | String | Internal shipment code generated by the server; null for shipments created before the code existed. |
packedAt | DateTime | Ngày đóng gói: its own milestone, null until packing completes. It is never the handover date. |
package | ShipmentPackage | Null when no package fact was stored. |
deliveryRequest | ShipmentDeliveryRequest | |
note | String | Shipment note of the operator (not the customer's order note). |
feeVnd | VndAmount | Partner fee in VND; null = not recorded. Never part of the COD total. |
feePayer | ShipmentFeePayer | |
reconciliation | ShipmentReconciliation! | |
codTotalBasis | ShipmentCodBasis! | SNAPSHOT when a handover snapshot exists (frozen), else LIVE; see ShipmentCodBasis. |
codTotalSnapshotVnd | VndAmount | The raw handover snapshot; null for shipments without one. |
codOpenVnd | VndAmount | Sum of the OPEN COD obligations of the items now (what is still to collect); null = unavailable. |
deliveryAttempts | Int! | U19-P2-34 (ASSUME-05, GAP-W-VD-03): delivery attempts so far, derived (moves into WAITING_REDELIVERY + DELIVERY_FAILED). |
carrierLabel | String! | PIDEAL = Vận chuyển nội bộ PIDEAL; any other partner = its code. |
driverName | String | G2I-P3-03: driver name; null = not given. Set only with a status update (updateShipmentStatus). |
driverPhone | String | Driver phone in full (an operations contact, not customer PII), E.164; null = not given. |
deliverySlotText | String | Delivery time slot as typed; null = not given. |
nextStates | [ShipmentState!] | U28-P2-09. Legal manual moves from state for this caller (ASSUME-04 machine); empty when terminal or without shipment.update. |
codCollect | ShipmentCodCollectAction | U28-P2-10. Đã thu đủ COD of this shipment; null when it was not computed. |
shipmentCandidates
Shipment wizard step 1 (U19-P2-28, VD-US-03 AC01/AC07/AC08): Group Buy orders and Recurring cycles in Chờ đóng gói without a shipment link, in groups (recipient + phone + address + delivery date). search (trimmed, 1..100 characters, else validation_failed search_invalid): order code prefix, recipient name (case and diacritics ignored) or the exact phone; it keeps the matching components of each group. deliveryDate (VN day) keeps components whose delivery window contains it; campaignType narrows the type; all ANDed. Never creates a mapping or locks a payment method. Requires shipment.create (order.read still admits until U19-P4-02).
query · quyền: shipment.create
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String | ||
deliveryDate | String | ||
campaignType | OrderCampaignType | ||
page | Int | ||
pageSize | Int |
Trả về ShipmentCandidatePage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [ShipmentCandidateGroup!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
deliveryDays | [String!]! | Distinct delivery days (VN, YYYY-MM-DD, window start) of the whole candidate set, ascending: the Ngày giao dropdown. |
shipmentCodCollectPreview
U28-FU-API-B. Preview of recordShipmentCodCollection (per order / cycle payment status after, reward points released). Read-only. Requires cod.collect (COD-01). Errors: not_found, forbidden, validation_failed.
query · quyền: cod.collect
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
shipmentId | ID! |
Trả về ShipmentCodCollectPreview!
| Field | Kiểu | Mô tả |
|---|---|---|
shipmentId | ID! | |
version | Int! | The version the preview read: send it as expectedVersion. |
totalVnd | VndAmount! | The total the command accepts (Σ OPEN COD); 0 when nothing is due. |
units | [ShipmentCodCollectPreviewUnit!]! | Empty when the shipment is not DELIVERED or has no COD open. |
shipments
Shipments, newest first; search + filters + tab ANDed, pageSize 1..500 (default 50). Requires shipment.read.
query · quyền: shipment.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String | ||
state | ShipmentState | ||
carrierCode | String | ||
reconciliation | ShipmentReconciliation | ||
packedOnFrom | String | ||
packedOnTo | String | ||
page | Int | ||
pageSize | Int |
Trả về ShipmentPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [Shipment!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
stateCounts | [ShipmentStateCount!]! | Every Word tab in display order (PACKING, PACKED, SHIPPING, WAITING_REDELIVERY, DELIVERED, DELIVERY_FAILED, RETURNED), 0 included. |
totalAll | Int! | The count of the tab Tất cả (all states) under the same search and filters. |
shipmentStatusPreview
U28-P2-09. Preview of updateShipmentStatus for one target state (per order / cycle consequences, attempt number). Read-only. Requires shipment.update (SHP-03). Errors: not_found, validation_failed. U28-FU-API-D: codCollected = the Đã thu đủ tiền COD tick the save would send (applied with DELIVERED while COD is due).
query · quyền: shipment.update
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
shipmentId | ID! | ||
toState | ShipmentState! | ||
codCollected | Boolean |
Trả về ShipmentStatusPreview!
| Field | Kiểu | Mô tả |
|---|---|---|
shipmentId | ID! | |
version | Int! | The version the preview read: send it as expectedVersion. |
fromState | ShipmentState! | |
toState | ShipmentState! | |
legal | Boolean! | False when toState is not a legal move from fromState (effects is then empty). |
attemptNo | Int | Delivery attempt the update would record (Lần giao thứ n); null when not an attempt. |
codDueVnd | VndAmount | COD codCollected would collect with DELIVERED; null when not applicable. |
effects | [ShipmentUnitEffect!]! | Status of every order / cycle of the shipment after the update, consequences of DELIVERY_FAILED / RETURNED included. |
effectsBefore | [ShipmentUnitEffect!]! | U28-FU-API-D. Status of every order / cycle NOW (same reader as effects, read before the dry run): the before of before -> after. |
attemptsBefore | Int! | U28-FU-API-D. Delivery attempts of the shipment now (ASSUME-05 count). |
attemptsAfter | Int | U28-FU-API-D. Delivery attempts after the update; null when the move is not legal. |
Mutation
groupShipment
Retired (U19-P4-02, B013.R15): every new call answers conflict reason retired; use handoverShipment. Requires shipment.create.
mutation · quyền: shipment.create
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | GroupShipmentInput! |
Trả về FulfillmentCommandResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
state | ShipmentState! | |
fulfillmentEventId | ID! | |
fulfilledOrderIds | [ID!]! | Orders this fact moved LOCKED -> FULFILLED. |
codTotalVnd | VndAmount | groupShipment only: the trip COD total at creation (A-FF-01 AC06). |
handoverShipment
Atomic create + handover of the selected orders/cycles: shipment, mapping, code, COD snapshot, locked payment mode per unit, CREATED -> PACKING. Requires shipment.create.
mutation · quyền: shipment.create
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | HandoverShipmentInput! |
Trả về HandoverShipmentResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | 2 after a handover: CREATED (1) then PACKING (2). |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
state | ShipmentState! | |
shipmentCode | String! | Generated by the server at commit (VD + 8 digits); a preview code is only an estimate. |
fulfillmentEventId | ID! | |
codTotalVnd | VndAmount! | At-handover COD snapshot: the COD locked on the units (unpaid online included); an Online-paid unit contributes 0; the fee is excluded. |
recordDeliveryAttempt
Deprecated (U19-P4-02, B190.R02): logs one failed attempt on a SHIPPING shipment, state kept. Requires shipment.update.
mutation · quyền: shipment.update
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | RecordDeliveryAttemptInput! |
Trả về DeliveryAttemptResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
state | ShipmentState! | Always SHIPPING: an attempt never moves the shipment. |
fulfillmentEventId | ID! | |
issueCode | DeliveryIssueCode! | |
attemptNo | Int! | 1-based number of this attempt, derived from the shipment's stored ISSUE facts. There is no limit (OI-FF-01). |
recordFulfillmentEvent
Legacy manual status change or delivery issue. Requires shipment.update.
mutation · quyền: shipment.update
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | RecordFulfillmentEventInput! |
Trả về FulfillmentCommandResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
state | ShipmentState! | |
fulfillmentEventId | ID! | |
fulfilledOrderIds | [ID!]! | Orders this fact moved LOCKED -> FULFILLED. |
codTotalVnd | VndAmount | groupShipment only: the trip COD total at creation (A-FF-01 AC06). |
recordFulfillmentException
Records a delivery incident; moves no shipment. Requires order.manage (GAP-01/GAP-51).
mutation · quyền: order.manage
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | RecordFulfillmentExceptionInput! |
Trả về FulfillmentExceptionResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The exception id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
exceptionId | ID! | |
shipmentId | ID! | |
kind | FulfillmentExceptionKind! | |
exceptionStatus | FulfillmentExceptionStatus! | |
codSignal | FulfillmentCodSignal! | |
codPolicy | String |
recordShipmentCodCollection
Collect every OPEN COD obligation of a DELIVERED shipment in one transaction (Operations confirms, Word B186.R02). Requires cod.collect.
mutation · quyền: cod.collect
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | RecordShipmentCodCollectionInput! |
Trả về ShipmentCodCollectionResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
totalVnd | VndAmount! | |
collected | [ShipmentCodCollected!]! | |
fulfilledOrderIds | [ID!]! | Orders this call moved to FULFILLED: the ones a DELIVERED shipment held back until its COD was collected (empty otherwise). |
updateShipmentStatus
Updates a shipment and every order / cycle in it, optionally with the COD collected, in one transaction. Requires shipment.update.
mutation · quyền: shipment.update
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | UpdateShipmentStatusInput! |
Trả về UpdateShipmentStatusResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The shipment id. |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
state | ShipmentState! | |
fulfillmentEventId | ID! | |
fulfilledOrderIds | [ID!]! | Orders this update moved to FULFILLED (directly, or released by the COD collected in the same call). |
codCollected | [ShipmentCodCollected!]! | COD obligations collected by this update (empty unless codCollected). |
effects | [ShipmentUnitEffect!]! | New status of every order / cycle, after the consequences of DELIVERY_FAILED (DH-US-14) and RETURNED (DH-US-09) applied in the same transaction. |
attemptNo | Int | U28-P2-09. Delivery attempt this update recorded or closed (Lần giao thứ n); null when the move is not an attempt. |