Skip to content

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ểuMặc địnhMô tả
filterStaffCycleScheduleFilter
pageInt1
pageSizeInt20

Trả về StaffCyclePage!

FieldKiểuMô tả
items[StaffCycle!]!
pageInt!
pageSizeInt!
totalInt!

fulfillmentExceptions ​

Exceptions of a shipment or an order, newest first. Requires order.read (GAP-51).

query · quyền: order.read

Tham sốKiểuMặc địnhMô tả
shipmentIdID
orderIdID
pageInt
pageSizeInt

Trả về FulfillmentExceptionPage!

FieldKiểuMô tả
items[FulfillmentException!]!
pageInt!
pageSizeInt!
totalInt!

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ểuMặc địnhMô tả
orderIdID!

Trả về OrderDeliveryProgress!

FieldKiểuMô tả
orderIdID!
campaignTypeOrderCampaignType!
orderStateOrderState!
committedUnitsInt!Delivery units the order commits to (1 for Group Buy).
deliveredUnitsInt!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ểuMặc địnhMô tả
idID!

Trả về Shipment!

FieldKiểuMô tả
idID!
carrierCodeString!Opaque partner code (logistics provider undecided).
carrierRefString!Partner reference / tracking number, distinct from the internal id.
scheduleKindShipmentScheduleKind!
campaignIdIDNull for a MIXED shipment (several campaigns or Group Buy + Recurring): read the campaign per component through its order.
milestoneIdID
cycleNoInt
deliversFromVnString!
deliversToVnString!
expectedOnString!
recipientShipmentRecipient!
handedOverAtDateTime!
stateShipmentState!
versionInt!
stateChangedAtDateTime!
lastEventAtDateTime!
deliveredAtDateTime
createdByID!
createdAtDateTime!
items[ShipmentItem!]!
codTotalVndVndAmountTrip COD = sum of the remaining COD obligations of the items (A-FF-01 AC06). Null = unavailable.
timeline[FulfillmentEvent!]!
shipmentCodeStringInternal shipment code generated by the server; null for shipments created before the code existed.
packedAtDateTimeNgày đóng gói: its own milestone, null until packing completes. It is never the handover date.
packageShipmentPackageNull when no package fact was stored.
deliveryRequestShipmentDeliveryRequest
noteStringShipment note of the operator (not the customer's order note).
feeVndVndAmountPartner fee in VND; null = not recorded. Never part of the COD total.
feePayerShipmentFeePayer
reconciliationShipmentReconciliation!
codTotalBasisShipmentCodBasis!SNAPSHOT when a handover snapshot exists (frozen), else LIVE; see ShipmentCodBasis.
codTotalSnapshotVndVndAmountThe raw handover snapshot; null for shipments without one.
codOpenVndVndAmountSum of the OPEN COD obligations of the items now (what is still to collect); null = unavailable.
deliveryAttemptsInt!U19-P2-34 (ASSUME-05, GAP-W-VD-03): delivery attempts so far, derived (moves into WAITING_REDELIVERY + DELIVERY_FAILED).
carrierLabelString!PIDEAL = Vận chuyển nội bộ PIDEAL; any other partner = its code.
driverNameStringG2I-P3-03: driver name; null = not given. Set only with a status update (updateShipmentStatus).
driverPhoneStringDriver phone in full (an operations contact, not customer PII), E.164; null = not given.
deliverySlotTextStringDelivery 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.
codCollectShipmentCodCollectActionU28-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ểuMặc địnhMô tả
searchString
deliveryDateString
campaignTypeOrderCampaignType
pageInt
pageSizeInt

Trả về ShipmentCandidatePage!

FieldKiểuMô tả
items[ShipmentCandidateGroup!]!
pageInt!
pageSizeInt!
totalInt!
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ểuMặc địnhMô tả
shipmentIdID!

Trả về ShipmentCodCollectPreview!

FieldKiểuMô tả
shipmentIdID!
versionInt!The version the preview read: send it as expectedVersion.
totalVndVndAmount!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ểuMặc địnhMô tả
searchString
stateShipmentState
carrierCodeString
reconciliationShipmentReconciliation
packedOnFromString
packedOnToString
pageInt
pageSizeInt

Trả về ShipmentPage!

FieldKiểuMô tả
items[Shipment!]!
pageInt!
pageSizeInt!
totalInt!
stateCounts[ShipmentStateCount!]!Every Word tab in display order (PACKING, PACKED, SHIPPING, WAITING_REDELIVERY, DELIVERED, DELIVERY_FAILED, RETURNED), 0 included.
totalAllInt!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ểuMặc địnhMô tả
shipmentIdID!
toStateShipmentState!
codCollectedBoolean

Trả về ShipmentStatusPreview!

FieldKiểuMô tả
shipmentIdID!
versionInt!The version the preview read: send it as expectedVersion.
fromStateShipmentState!
toStateShipmentState!
legalBoolean!False when toState is not a legal move from fromState (effects is then empty).
attemptNoIntDelivery attempt the update would record (Lần giao thứ n); null when not an attempt.
codDueVndVndAmountCOD 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.
attemptsBeforeInt!U28-FU-API-D. Delivery attempts of the shipment now (ASSUME-05 count).
attemptsAfterIntU28-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ểuMặc địnhMô tả
inputGroupShipmentInput!

Trả về FulfillmentCommandResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
stateShipmentState!
fulfillmentEventIdID!
fulfilledOrderIds[ID!]!Orders this fact moved LOCKED -> FULFILLED.
codTotalVndVndAmountgroupShipment 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ểuMặc địnhMô tả
inputHandoverShipmentInput!

Trả về HandoverShipmentResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!2 after a handover: CREATED (1) then PACKING (2).
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
stateShipmentState!
shipmentCodeString!Generated by the server at commit (VD + 8 digits); a preview code is only an estimate.
fulfillmentEventIdID!
codTotalVndVndAmount!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ểuMặc địnhMô tả
inputRecordDeliveryAttemptInput!

Trả về DeliveryAttemptResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
stateShipmentState!Always SHIPPING: an attempt never moves the shipment.
fulfillmentEventIdID!
issueCodeDeliveryIssueCode!
attemptNoInt!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ểuMặc địnhMô tả
inputRecordFulfillmentEventInput!

Trả về FulfillmentCommandResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
stateShipmentState!
fulfillmentEventIdID!
fulfilledOrderIds[ID!]!Orders this fact moved LOCKED -> FULFILLED.
codTotalVndVndAmountgroupShipment 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ểuMặc địnhMô tả
inputRecordFulfillmentExceptionInput!

Trả về FulfillmentExceptionResult!

FieldKiểuMô tả
aggregateIdID!The exception id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
exceptionIdID!
shipmentIdID!
kindFulfillmentExceptionKind!
exceptionStatusFulfillmentExceptionStatus!
codSignalFulfillmentCodSignal!
codPolicyString

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ểuMặc địnhMô tả
inputRecordShipmentCodCollectionInput!

Trả về ShipmentCodCollectionResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
totalVndVndAmount!
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ểuMặc địnhMô tả
inputUpdateShipmentStatusInput!

Trả về UpdateShipmentStatusResult!

FieldKiểuMô tả
aggregateIdID!The shipment id.
versionInt!
statusCommandStatus!
requestIdID!
correlationIdID!
nextActionNextAction
stateShipmentState!
fulfillmentEventIdID!
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.
attemptNoIntU28-P2-09. Delivery attempt this update recorded or closed (Lần giao thứ n); null when the move is not an attempt.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17