Chuẩn bị yêu cầu
Tạo một tờ khai yêu cầu tổ chức dữ liệu lô hàng của bạn thành cấu trúc phù hợp. API sử dụng cách tiếp cận phân cấp, nơi bạn trước tiên tạo tờ khai, sau đó thêm các dòng tờ khai chứa chi tiết lô hàng riêng lẻ.
Mỗi thành phần có các trường bắt buộc cụ thể để đảm bảo tuân thủ hải quan và tài liệu chính xác. Dưới đây chúng tôi đã phác thảo cấu trúc dữ liệu cần thiết và các đầu vào bắt buộc.
Các loại đầu vào chính
API tờ khai sử dụng nhiều loại đầu vào để tổ chức dữ liệu lô hàng:
ManifestInput: Thông tin lô hàng cấp cao bao gồm sân bay, loại hoá đơn vận chuyển và chi tiết chuyến bayManifestLineInput: Chi tiết lô hàng riêng lẻ được liên kết với tờ khaiManifestLineItemInput: Thông tin sản phẩm để phân loại hải quanCreatePartyInput: Chi tiết bên và vị trí cho nguồn gốc và đích đến
Xem các định nghĩa trường hoàn chỉnh và các tùy chọn trong tài liệu tham khảo API GraphQL của chúng tôi.
Tạo tờ khai thông qua API
Khi bạn đã tổ chức dữ liệu lô hàng, hãy gửi đột biến GraphQL để tạo tờ khai.
Bước 1: Tạo tiêu đề tờ khai
mutation ManifestCreate($input: ManifestInput!) { manifestCreate(input: $input) { id amount arrivalDate awbNumber awbPrefix carrierCode createdAt createdBy destinationCode operatorDestination operatorOrigin originCode postalOperatorCode serviceNumber source transportationMode updatedAt updatedBy weight weightUnit statusTransitions { createdAt createdBy note source } lines(first: 5) { totalCount edges { cursor node { id trackingNumber endUse currencyCode createdAt createdBy updatedAt updatedBy landedCost { id } } } } }}RESPONSE
json
{
"data": {
"manifestCreate": {
"id": "manifest_abc123def456",
"amount": "0",
"arrivalDate": "2026-03-15T14:30:00.000Z",
"awbNumber": "1234",
"awbPrefix": "001",
"carrierCode": "AA",
"createdAt": "2026-01-06T12:00:00.000Z",
"createdBy": "organization_xyz789",
"destinationCode": "JFK",
"operatorDestination": "US",
"originCode": "LHR",
"postalOperatorCode": "J1CGBA",
"serviceNumber": "1234",
"source": "API",
"transportationMode": "AIR",
"updatedAt": "2026-01-06T12:00:00.000Z",
"updatedBy": "organization_xyz789",
"weight": "0",
"weightUnit": "KILOGRAM",
"statusTransitions": [],
"lines": {
"totalCount": 0,
"edges": []
}
}
}
}
Bước 2: Thêm dòng tờ khai
Sử dụng ID được trả về từ đột biến manifestCreate, bây giờ bạn có thể liên kết các lô hàng riêng lẻ với tờ khai.
mutation ManifestLineCreate($manifestId: ID!, $input: ManifestLineInput!) { manifestLineCreate(manifestId: $manifestId, input: $input) { id manifestId trackingNumber endUse currencyCode referenceNumber arrivalDate createdAt createdBy updatedAt updatedBy landedCost { id } }}RESPONSE
json
{
"data": {
"manifestLineCreate": {
"id": "manifest_line_def456ghi789",
"manifestId": "manifest_abc123def456",
"trackingNumber": "LX123456789GB",
"endUse": "NOT_FOR_RESALE",
"currencyCode": "USD",
"referenceNumber": "ORDER-2026-001",
"arrivalDate": "2026-03-15T14:30:00.000Z",
"createdAt": "2026-01-06T12:05:00.000Z",
"createdBy": "organization_xyz789",
"updatedAt": "2026-01-06T12:05:00.000Z",
"updatedBy": "organization_xyz789",
"landedCost": null
}
}
}
Bước 3: Thêm nhiều dòng tờ khai (hàng loạt)
Để hiệu quả, bạn có thể thêm nhiều dòng tờ khai trong một yêu cầu duy nhất bằng cách sử dụng đột biến manifestLinesCreate. Mỗi dòng yêu cầu mảng parties riêng để xác định nguồn gốc và đích đến của lô hàng.
mutation ManifestLinesCreate($manifestId: ID!, $input: [ManifestLineInput!]!) { manifestLinesCreate(manifestId: $manifestId, input: $input) { id manifestId trackingNumber endUse currencyCode createdAt }}RESPONSE
json
{
"data": {
"manifestLinesCreate": [
{
"id": "manifest_line_aaa111bbb222",
"manifestId": "manifest_abc123def456",
"trackingNumber": "LX123456789GB",
"endUse": "NOT_FOR_RESALE",
"currencyCode": "USD",
"createdAt": "2026-01-06T12:10:00.000Z"
},
{
"id": "manifest_line_ccc333ddd444",
"manifestId": "manifest_abc123def456",
"trackingNumber": "LX987654321GB",
"endUse": "GIFT",
"currencyCode": "USD",
"createdAt": "2026-01-06T12:10:00.000Z"
}
]
}
}
Bước 4: Cập nhật tờ khai
Trong trường hợp chi tiết chuyến bay thay đổi, bạn có thể cập nhật chi tiết tờ khai bằng cách sử dụng đột biến sau. Trường source là bắt buộc và cho biết nguồn dữ liệu cho bản cập nhật.
mutation ManifestUpdate($id: ID!, $input: ManifestUpdateInput!) { manifestUpdate(id: $id, input: $input) { id amount arrivalDate awbNumber awbPrefix carrierCode createdAt createdBy destinationCode operatorDestination operatorOrigin originCode postalOperatorCode serviceNumber source transportationMode updatedAt updatedBy weight weightUnit statusTransitions { createdAt createdBy note source } }}RESPONSE
json
{
"data": {
"manifestUpdate": {
"id": "manifest_abc123def456",
"amount": "150.50",
"arrivalDate": "2026-03-16T10:00:00.000Z",
"awbNumber": "5678",
"awbPrefix": "001",
"carrierCode": "BA",
"createdAt": "2026-01-06T12:00:00.000Z",
"createdBy": "organization_xyz789",
"destinationCode": "JFK",
"operatorDestination": "US",
"originCode": "LHR",
"postalOperatorCode": "J1CGBA",
"serviceNumber": "5678",
"source": "RESDIT",
"transportationMode": "AIR",
"updatedAt": "2026-01-06T14:30:00.000Z",
"updatedBy": "organization_xyz789",
"weight": "25.5",
"weightUnit": "KILOGRAM",
"statusTransitions": [
{
"createdAt": "2026-01-06T14:30:00.000Z",
"createdBy": "organization_xyz789",
"note": "Flight rescheduled due to weather",
"source": "RESDIT"
}
]
}
}
}
Giá trị nguồn dữ liệu
Trường source trong ManifestUpdateInput chấp nhận các giá trị sau:
| Giá trị↕ | Mô tả↕ |
|---|---|
CARDIT | Trao đổi dữ liệu hãng vận chuyển |
PRECON | Thông báo trước khi ký gửi |
PREDES | Thông báo trước khi gửi hàng |
RESDIT | Phản hồi việc gửi hàng |
Chuẩn bị tờ khai hải quan cho lô hàng Mỹ.
Cung cấp cho Zonos dữ liệu lô hàng bưu chính nhập khẩu.Zonos sẽ chuẩn bị các tờ khai hải quan toàn diện bao gồm tất cả các thông tin cần thiết cho các lô hàng bưu chính vào Mỹ.