Luồng 3B · Giao hàng Gearment Dropship

← Tổng quan
LUỒNG 3B · ĐỌC ~10 PHÚT

Giao hàng Gearment Dropship

Sau khi nhận đơn hàng có sản phẩm Gearment (SKU Gearment tồn tại), hệ thống tự routing vào luồng Dropship. Wizard Báo giá gọi API Gearment v3 draft → price → confirm. Mỗi lần có webhook từ Gearment (hoàn thành, hủy, cập nhật tracking), Odoo cập nhật trạng thái order + đẩy tracking lên Etsy. UAT 2026-05-28 confirm HMAC-SHA256 webhook signature, idempotency nonce + UNIQUE partial index, 9 webhook topic + 4 mục xử lý, tracking refresh từ GKE Excel.

Hoàn thành 100% UAT 2026-05-28 · E2E 2026-06-10 Nguồn: FLOW_GIAO_HANG_VN v1.0 · HUONG_DAN_GIAO_HANG_VN v1.2

AAi làm gì — sơ đồ vai trò

Luồng Gearment Dropship liên kết 5 vai trò + hệ thống Gearment API + webhook. BA Lead khởi tạo, hệ thống gọi API, Gearment webhook báo tiến độ, Odoo đẩy tracking sang Etsy. Bảng dưới đọc từ trái qua phải: mỗi cột là vai trò, mỗi hàng là mốc chính.

BA Lead
Hệ thống Odoo
Gearment API
Webhook
Etsy API
1. Bước trước
Đơn hàng có sản phẩm Gearment đã nhập (từ Luồng 2)
Kiểm tra SKU Gearment tồn tại
—
—
—
2. Mở Wizard
Bấm nút Request Gearment Quote trên order
Tự hiển thị wizard với dòng dữ liệu (địa chỉ, kích thước, hình ảnh)
—
—
—
3. Gọi draft → price
Bấm Send Draft (hoặc tự động)
Gọi 2 API: /draft → /price; log vào gearment_api_log
Trả {price, currency, ready_for_confirm} hoặc lỗi
—
—
4. Xác nhận confirm
Xem giá, bấm Confirm Order
Gọi /confirm; order chuyển trạng thái "Confirmed at Gearment"
Trả {success, reference_id} hoặc fail
—
—
5. In + vận chuyển
—
—
In sản phẩm (1–3 ngày), lấy tracking từ carrier
Gửi webhook order_completed + tracking_order_updated
Odoo nhận webhook, cập nhật order, đẩy tracking lên Etsy
6. Hoàn tất
Xem order -> Gearment status = Completed, Tracking trên tab
Trạng thái order = "Delivered at Gearment" (tự động từ webhook)
—
—
Etsy seeing tracking, customer can view shipment

BCác bước chi tiết (10 bước)

  1. 1
    BA · từ Luồng 2
    Đơn hàng có sản phẩm Gearment tới Odoo
    Đơn hàng từ Etsy có ≥1 line item có sản phẩm mà SKU Gearment không rỗng. Hệ thống tự detect và gắn flag fulfillment_method = 'gearment_dropship' trên đơn. Không cần BA can thiệp.
    Hệ thống: order.create() hook kiểm tra tất cả product trên order_line, nếu tìm thấy product.x_gearment_sku → set fulfillment_method. Script cron nền (P1-MSG-INBOUND) đẩy đơn từ Etsy API vào Odoo.
  2. 2
    BA · ~1 phút
    Mở order, xem tab Fulfillment
    Order trạng thái "Confirm". Mở form order, bấm tab Fulfillment. Hiển thị thông tin order (địa chỉ giao, tên sản phẩm, kích thước, hình ảnh, giá tính Gearment). Nút Request Gearment Quote sẵn sàng.
    Hệ thống: tab này là bản ghi Fulfillment liên kết với đơn, chứa 20 trường theo thiết kế (địa chỉ, kích thước, ảnh, nội dung cá nhân hoá …).
  3. 3
    BA · ~30 giây
    Bấm Request Gearment Quote → Wizard mở
    Nút Request Gearment Quote mở wizard gearment_quote_wizard. Form hiển thị: địa chỉ giao (tỉ/huyện/xã), kích thước gói (W×H×D), cân nặng, hình ảnh chính, mô tả cá nhân hoá nếu có. BA xem lại, có thể sửa địa chỉ. Sau đó bấm Send Draft to Gearment.
    Hệ thống: wizard là TransientModel, dữ liệu lấy từ order + product variant. Nút Send trigger action gọi gearment_adapter.draft().
  4. 4
    Hệ thống · ~3 giây
    Gọi API Gearment: /draft + /price
    Odoo gọi POST /api/v3/orders/draft với payload (reference_id, address, size, image_url, personalization_text). Gearment trả {sku_id, ready_for_price}. Nếu thành, hệ thống tiếp tục gọi POST /api/v3/orders/{reference_id}/price. Kết quả: {price_vnd, currency_code, ready_for_confirm}. Ghi log vào gearment_api_log (source='draft', 'quote'; http_status, request_headers ghi x-gearment-idempotency-key).
    Phía sau: 2 lời gọi tuần tự, cả 2 đều có idempotency header (HMAC-SHA256 của reference_id). Nếu /draft 500 thì /price bỏ qua, wizard hiển thị "error draft". Mỗi lần bấm Send Draft, nếu reference_id cũ → Gearment trả 409 (duplicate) → hệ thống detect và reuse sku_id cũ.
  5. 5
    Hệ thống · auto
    Cập nhật wizard với giá Gearment
    Wizard auto-refresh hiển thị: Giá Gearment (ví dụ 125,000 VND), Phí vận chuyển (+30,000 VND), Tổng tiền thanh toán. Nút Confirm Order at Gearment được active. BA kiểm tra giá, nếu OK bấm Confirm; nếu cao quá có thể bấm Cancel (luồng tạm dừng, BA có thể edit sản phẩm & retry).
  6. 6
    BA · ~10 giây
    Bấm Confirm Order at Gearment
    Wizard gọi POST /api/v3/orders/draft/labeled (confirm endpoint). Payload gồm tất cả data từ /draft + label address chuẩn. Gearment trả {success, reference_id, order_status='confirmed'}. Hệ thống lưu reference_id vào fulfillment record, order.fulfillment_status = 'awaiting_gearment_production'.
    Ghi log: source='confirm'; http_status 200 ✓ hoặc 400/500 ✗. Nếu 400, hiển thị lỗi wizard (ví dụ "Địa chỉ không hợp lệ"), BA quay lại sửa. Nếu 500, retry cron (every 5 min, max 3 lần).
  7. 7
    Gearment · 1–3 ngày
    In sản phẩm & gửi webhook order_completed
    Gearment in sản phẩm, dán label, lấy tracking. Gửi webhook POST /callback/gearment-webhook (topic: 'order_completed', reference_id, tracking_number, carrier_code). Payload kèm HMAC-SHA256 signature header. Odoo nhận webhook, verify HMAC, decompress nonce + timestamp, cập nhật fulfillment.
    Webhook handler: nonce dedup qua lookup + UNIQUE partial index trên (webhook_topic, nonce); nếu trùng → 200 OK (idempotent). Topic 'order_completed' trigger _on_gearment_order_completed(): cập nhật fulfillment_status='printing_completed', save tracking_number.
  8. 8
    Hệ thống · auto
    Đẩy tracking lên Etsy
    Ngay sau khi lưu mã tracking từ webhook, lịch đẩy tracking lên Etsy chạy (mỗi 10 phút). Hệ thống gọi Etsy với mã tracking + đơn vị vận chuyển. Etsy trả 200, đánh dấu đơn đã đẩy tracking. Nếu lỗi, ghi vào nhật ký Etsy + thử lại.
    Carrier mapping: Gearment trả carrier_code (ví dụ 'USPS', 'DHL', 'VietnamPost'). Script map sang Etsy carrier (pre-defined custom shipping.carrier model với etsy_carrier_code). Nếu không match → log warning, dùng mặc định 'Other'.
  9. 9
    Gearment · khi giao
    Webhook tracking_order_updated — đã giao
    Gearment gửi webhook tracking_order_updated khi status thay đổi (in transit, delivered, exception). Payload chứa reference_id + tracking_status ('in_transit', 'delivered', 'returned', …). Odoo cập nhật fulfillment_status → 'in_delivery' / 'delivered'. Không đẩy lại Etsy (Etsy theo tracking_number tự sync từ carrier).
    9 webhook topic tổng: 4 xử lý active (order_completed, tracking_order_updated, order_cancelled, order_on_hold); 5 log-only (tracking_exception, order_delayed, carrier_changed, batch_assigned, batch_dispatched). Cấu hình qua webhook_topic = ('order_completed', ...) trong environment model.
  10. 10
    BA · theo dõi
    Xem order hoàn tất trên Odoo + Etsy
    Order trạng thái tự update qua webhook: "Confirmed at Gearment" → "In Delivery" → "Delivered at Gearment". Tab Fulfillment hiển thị tracking_number, carrier, ngày dự giao. Trên Etsy, khách hàng thấy tracking link trực tiếp (tự sync từ carrier công khai).
    Bulk action (Story 4.7): nếu webhook cron tắt hoặc cần manual sync, BA dùng bulk action Resync Tracking from Gearment trên Fulfillment list (gọi API GKE Excel hoặc Gearment tracking endpoint). Mỗi resync đều log vào gearment_api_log (source='manual_sync').

Màn hình Odoo trong luồng này

5 màn hình mô phỏng. Cuộn xuống để xem từng cảnh — từ tab Fulfillment order, wizard báo giá, gearment_api_log list, webhook log, và fulfillment tracking form.
Màn hình 1 · Order detail — tab Fulfillment với nút Request Gearment Quote
Bán hàngĐơn hàng › Order #2854 ba.lead@hatafa
Đơn hàng›#2854 · Custom Mug Order from JaHandmadeArt
Confirmed›In Delivery›Delivered
Order #2854 — Order detail SO-2854
Order LinesFulfillmentPaymentsDelivery
Order Date
2026-05-28 09:15
Customer
Jane Doe · jane@example.com
Fulfillment Method
Gearment Dropship
Total Amount
125.50 USD
Sản phẩm trong order:
Sản phẩmSố lượngMã SKUMã GearmentGiá đơn
Custom Coffee Mug 11oz1MUG-CR-F11GM-MUG-00114.50 USD
Gift Box Kraft 4x4x41BOX-KR-SGM-BOX-0012.00 USD
Tab Fulfillment (bấm để xem): hiển thị fulfillment record với button Request Gearment Quote
Tab Fulfillment chứa bản ghi Giao hàng (Fulfillment) + nút Request Gearment Quote. Đây là điểm khởi đầu luồng Dropship. BA bấm nút → mở wizard.
Mockup gốc: form đơn hàng chuẩn của Odoo (sale.view_order_form @ addons/sale/views/sale_order_views.xml); chỗ khác biệt: tab "Fulfillment" mở rộng + nút "Request Gearment Quote" trong multichannel_hub_fulfillment/views/sale_order_views.xml.
Màn hình 2 · Wizard báo giá — gearment_quote_wizard after /draft + /price call
Bán hàngĐơn hàng › Gearment Quote ba.lead@hatafa
Đơn hàng›#2854›Gearment Quote
📋 Báo giá từ Gearment — Order #2854
Thông tin giao hàng:
Người nhận: Jane Doe
Địa chỉ: 123 Main St, District 1, Ho Chi Minh City
Phone: +84 9xxxxxxxx
Sản phẩm: Custom Coffee Mug 11oz + Gift Box
Hình ảnh: Uploaded
✓ Gearment đã nhận draft + tính giá
reference_id: GEA-2854-20260528-001 · sku_id: 54321
Giá Gearment (2 sản phẩm)125,000 VND
Phí vận chuyển (USPS)+ 30,000 VND
Phí xử lý+ 5,000 VND
Tổng chi phí giao hàng160,000 VND
Khách hàng sẽ thanh toán trên Etsy: 125.50 USD (giá sản phẩm) · Gearment cost: 160,000 VND ≈ 6.40 USD · Lợi nhuận: +119.10 USD
Wizard hiển thị giá Gearment sau khi gọi /draft + /price API. BA xem lại địa chỉ (có thể sửa nếu cần), kiểm tra giá, rồi bấm Confirm Order at Gearment để gọi endpoint /draft/labeled.
Mockup gốc: TransientModel + view tuỳ biến cho wizard báo giá Gearment trong multichannel_hub_fulfillment (cộng đồng "Gearment adapter" trong graphify); không có view chuẩn Odoo cho wizard báo giá nhà cung cấp dropship.
Màn hình 3 · Nhật ký API Gearment — gearment_api_log list với filter
Bán hàngGearment › API Logs tech.support@hatafa
Gearment›API Logs
8 log hôm nay · 6 OK · 2 lỗi
Thời gianOrderEndpointSourceHTTP StatusThời gian (ms)Lỗi
2026-05-28 10:38#2854/pricequote200847—
2026-05-28 10:38#2854/draftdraft2001123—
2026-05-28 10:42#2854/draft/labeledconfirm200756—
2026-05-28 14:15#2851/draftdraft5005042Server error · retry queued
2026-05-28 14:20#2851/draftdraft_retry_1200892—
2026-05-28 15:01#2852/pricequote400234Invalid address · BA to verify
Nhật ký API Gearment ghi tất cả lời gọi: draft, quote, confirm, cron sync, webhook. Tech support dùng để debug. Cột Source = draft/quote/confirm/callback/health_check/inbound_webhook. Direction = outbound (Odoo→Gearment) hoặc inbound (webhook incoming). Phía sau: request_body/response_summary truncate ≤4KB, PII scrubbed (first_name, address, email, phone).
Mockup gốc: view list + form tuỳ biến cho mô hình gearment.api.log trong multichannel_hub_fulfillment; không có view chuẩn Odoo cho nhật ký API vendor.
Màn hình 4 · Webhook log — gearment.webhook.log list với nonce dedup status
Bán hàngGearment › Webhook Logs tech.support@hatafa
Gearment›Webhook Logs
124 webhook hôm nay
Thời gianTopicOrder RefNonceNonce Dup?Signature OK?StatusAction
2026-05-28 11:15order_completedGEA-2854-001no-2854-…New✓ SHA256Processedtracking saved
2026-05-28 11:16order_completedGEA-2854-001no-2854-…Dup (OK)✓ SHA256Idempotent200 OK
2026-05-28 12:30tracking_order_updatedGEA-2854-001tu-2854-…New✓ SHA256Processedstatus=in_transit
2026-05-28 13:00batch_dispatchedGEA-2854-001bd-2854-…New✓ SHA256Log onlyarchived
2026-05-28 16:45tracking_order_updatedGEA-2854-001tu-2854-bNew✓ SHA256Processedstatus=delivered
Webhook log ghi nhận mỗi webhook từ Gearment. Nonce Dup? = "New" hoặc "Dup (OK)" (tìm thấy trong UNIQUE partial index). Signature OK? = verify HMAC-SHA256 header. Status = "Processed" (4 topic active) hoặc "Log only" (5 topic tracked nhưng không hành động). Action = ghi result (tracking saved, status=in_transit, …). Nếu topic='order_completed' thì auto-push tracking sang Etsy qua P1-TRK-PUSH-ETSY cron.
Mockup gốc: view list tuỳ biến cho mô hình gearment.webhook.log trong multichannel_hub_fulfillment (cộng đồng "Gearment adapter" + dispatcher trong graphify); không có view chuẩn Odoo cho nhật ký webhook.
Màn hình 5 · Sale Order Fulfillment detail — tab Tracking with Gearment status
Bán hàngĐơn hàng › Fulfillment › #2854 ba.lead@hatafa
Fulfillment›#2854 · Gearment Tracking
Status: Delivered at Gearment
✓ Giarment đã hoàn thành
Đơn hàng được xác nhận, in xong, đang giao hoặc đã giao.
Gearment Order Ref
GEA-2854-20260528-001
Gearment Status
Delivered
Tracking Number
1Z999AA10123456784 (USPS)
Carrier
United States Postal Service (USPS)
Date Confirmed at Gearment
2026-05-28 10:45
Date Printing Completed
2026-05-28 12:30 (webhook)
Date In Transit
2026-05-28 12:45 (webhook)
Date Delivered
2026-05-28 16:45 (webhook)
Trạng thái Etsy:
Etsy Tracking Pushed?
Yes · 2026-05-28 16:50
Etsy Shipment ID
etsy-ship-54321
Customer Can Track?
Yes (public carrier link)
Fulfillment detail hiển thị toàn bộ quá trình Gearment: reference_id, tracking_number, carrier, 4 mốc thời gian (confirm/print done/in transit/delivered từ webhook). Etsy Tracking Pushed = Yes nghĩa là khách hàng trên Etsy có thể click link tracking trực tiếp. Nó P1-TRK-PUSH-ETSY cron gọi API shipping-fulfillments, Etsy tự sync tracking từ carrier (USPS, DHL, …). Button Resync from Gearment dùng khi cron tắt (Story 4.7).
Mockup gốc: form đơn hàng (sale.view_order_form) + view tuỳ biến @ multichannel_hub_fulfillment/views/logistics_partner_views.xml và tracking_import_views.xml cho chi tiết Fulfillment.

CTiêu chí thành công

DLiên kết với các luồng khác

TrướcLuồng 2 — Đơn hàng Etsy về Odoo (điều kiện tiên quyết) Song songLuồng 3A — Giao hàng MTO in nội bộ (sản phẩm không có SKU Gearment) Tiếp theoLuồng 4 — After-sales (return, refund, dispute) Vai tròBA Lead — quản lý order và gọi wizard báo giá Vai tròTech Support — monitor API logs + webhook + debug

ELưu ý và câu hỏi mở

Story 4.7 bulk-send: Nếu cron P1-TRK-PUSH-ETSY tắt hoặc bị backlog, BA dùng bulk action Resync Tracking from Gearment trên Fulfillment list để manual resync. Mỗi resync log vào gearment_api_log (source='manual_sync'), không ghi đè nếu Etsy đã có tracking.

Dual-use GEARMENT_API_SECRET: Cả 2 API call (/draft, /price) và webhook HMAC verify dùng chung 1 key từ environment. Thay đổi key trên Gearment dashboard cần cập nhật .env và restart container (P1-11-SHOPID-BOOTSTRAP xử lý on-the-fly reload).

9 webhook topic + 4 xử lý + 5 log-only: Gearment hỗ trợ: order_completed, order_cancelled, order_on_hold (active); tracking_order_updated (active); tracking_exception, order_delayed, carrier_changed, batch_assigned, batch_dispatched (log-only). Cấu hình topic via webhook_topic field trên environment model. Thêm topic mới không cần code, chỉ cần cấu hình.

Custom shipping.carrier model: Gearment trả carrier_code (USPS, DHL, VietnamPost, …). Script map sang shipping.carrier với field etsy_carrier_code pre-defined. Nếu không match → log warning, dùng mặc định 'Other'. Thêm carrier mới vào setup data (P1-SETUP-CARRIERS).

tracking_order_updated refresh behavior: Webhook này không đẩy lại Etsy (vì Etsy tự fetch từ carrier link tracking_number). Chỉ cập nhật fulfillment_status trên Odoo. Ngoại lệ: nếu tracking_order_updated chứa tracking_status='returned' → auto-gọi API Etsy create return request (P1-TRK-AUTO-RETURN).

Webhook retry: Nếu Odoo không 200 OK webhook, Gearment retry (exponential backoff, max 3 attempts). Nếu Odoo 500 Server Error, log vào gearment_api_log (source='webhook_failed'), tech support có thể manual replay qua button Resend trên log record.

GEARMENT_WEBHOOK_SECRET từ ADR-009: Bây giờ không còn dùng (bị gộp vào GEARMENT_API_SECRET). Nếu có cấu hình cũ .env, hệ thống ignore + log warning.