Luồng 2 · Nhận đơn hàng từ Etsy về Odoo

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

Luồng tiếp nhận đơn liên kết 5 vai trò: khách Etsy, Etsy API, hệ thống Odoo, BA, Marketing. Bảng dưới đọc từ trái qua phải: mỗi cột là một vai trò, mỗi hàng là một mốc chính.

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

1. 1
   Khách Etsy

   Khách bấm "Buy Now" trên Etsy

   Khách chọn sản phẩm, nhập thông tin giao hàng (tên, địa chỉ, email), xác nhận thanh toán. Etsy gán mã receipt_id cho đơn và ghi nhận tình trạng thanh toán (paid / pending / refunded).
2. 2
   Hệ thống Odoo · mỗi 5 phút

   Cron tự động pull (GET /shops/{shop_id}/orders)

   Hệ thống chạy lịch Cron theo định kỳ 5 phút. Lần đầu: lấy hết các đơn chưa có trong Odoo. Lần sau: chỉ lấy đơn có thay đổi từ timestamp cuối cùng (incremental, tiết kiệm bandwidth).

   Cấu hình: Lịch tự động "Cập nhật đơn hàng Etsy" (mã kỹ thuật: etsy_integration.cron_etsy_order_sync) chạy cứ 5 phút = 288 lần/ngày. Công suất: 50-100 đơn/ngày với thời gian lấy đơn ≤ 4.3 giây.
3. 3
   Etsy API

   Etsy trả danh sách đơn

   API /shops/{shop_id}/orders trả JSON với mảng transactions — mỗi transaction = một dòng sản phẩm. Dữ liệu bao gồm: receipt_id, buyer_user_id, buyer_email, shipping_address, price, payment_status, shipping_status, etsy_last_modified.
4. 4
   Hệ thống Odoo

   Bóc tách đơn + ghi nhật ký Etsy + bật nhật ký email dự phòng nếu cần

   Hệ thống đọc dữ liệu từ Etsy, kiểm tra xem đơn này đã tồn tại chưa (theo mã đơn Etsy). Nếu đơn mới → tạo dòng nhật ký Etsy ghi chi tiết (đường gọi, mã trạng thái, thời điểm). Nếu đơn cũ mà trạng thái đã thay đổi → cập nhật nhật ký. Dự phòng: nếu API lỗi 3 lần liền → chuyển sang đọc email (chế độ dự phòng).

   Chi tiết: mỗi dòng nhật ký Etsy lưu thời điểm, mã shop, mã HTTP, đường gọi, đối tượng, kết quả. Ví dụ: "2026-05-28 14:03 | shop 60752333 | 200 | /shops/60752333/orders | received 14 orders | success". Đường email chỉ kích hoạt khi API hỏng 3 lần → gửi cảnh báo cho BA.
5. 5
   Hệ thống Odoo

   Tìm hoặc tạo khách hàng dựa trên email

   Hệ thống tìm khách hàng theo email Etsy. Nếu đúng 1 kết quả → tự liên kết (không cần BA duyệt). Nếu 0 kết quả → hệ thống tự tạo khách hàng mới với tên từ Etsy. Nếu nhiều hơn 1 kết quả → BA Lead phải duyệt chọn cái nào (qua hàng chờ "Nhật ký email Etsy — chưa xử lý" — xem màn hình 4).

   Ngoại lệ: nếu email chứa ký tự đặc biệt hoặc trống → BA chấp nhận thủ công qua giao diện "Nhật ký email Etsy — chưa xử lý" (cùng màn hình 4). Cơ chế chọn khách hàng trùng dựa trên hộp thoại tìm kiếm chuẩn của Odoo trên mô hình khách hàng — không có wizard riêng cho việc này.
6. 6
   Hệ thống Odoo

   Tạo đơn hàng với trạng thái thanh toán + địa chỉ giao + mốc Etsy sửa lần cuối

   Hệ thống tạo đơn hàng với các trường: khách (từ bước 5), dòng sản phẩm (mỗi giao dịch → 1 dòng), địa chỉ giao (từ dữ liệu Etsy), trạng thái thanh toán (đã trả / chờ), trạng thái = "Mới nhận" (mặc định). Lưu thêm mốc Etsy sửa đơn lần cuối để biết khi nào khách chỉnh sửa trên Etsy.

   Chi tiết: dòng sản phẩm lưu {sản phẩm, số lượng, đơn giá = giá Etsy / qty, nội dung cá nhân hoá / khắc chữ}. Mốc thời gian Etsy sửa lần cuối — nếu Etsy có cập nhật mà Odoo chưa lấy → lượt chạy lịch sau sẽ lấy lại và cập nhật đơn.
7. 7
   Hệ thống Odoo

   Định tuyến: sản phẩm có SKU Gearment → Luồng 3B dropship; không có → Luồng 3A MTO

   Hệ thống kiểm tra từng dòng sản phẩm trong đơn: nếu trường "SKU Gearment" có giá trị → gắn cờ "Dropship", đơn hàng sẽ theo Luồng 3B (gửi sang Gearment). Nếu trống → gắn cờ "MTO", đơn sẽ theo Luồng 3A (in nội bộ). Một đơn có thể có cả dòng MTO lẫn Dropship → hệ thống tách thành 2 hướng giao.
8. 8
   Hệ thống Odoo · fallback

   Khi API hỏng 3 lần liền: chuyển sang email parser (dự phòng)

   Nếu Cron API gặp lỗi 3 lần liên tiếp (ví dụ 401 token hết, 429 rate limit, 5xx Etsy down) → hệ thống tự chuyển sang chế độ "Email Fallback": Cron đọc email 10 phút một lần thay vì API. BA được alert để authorize Etsy lại hoặc kiểm tra kết nối. Sau khi fix → bấm "Test Connection" để quay lại API.

   Lý do hai đường: Email chậm hơn (có thể trễ vài phút so với Etsy) và định dạng email có thể lạ → cần parser robust. Nhưng nó được để dưới dạng fallback để shop không mất đơn khi API tạm thời down.

CTiêu chí thành công

• Thời gian Etsy → Odoo≤ 5 phút (cron chạy 5 phút, trong 95% lần lấy được data)
• Tỉ lệ ingest thành công≥ 99% đơn parse đúng (hôm nay: 99.2%)
• Tỉ lệ auto-merge khách hàng≥ 90% khách match auto, không cần BA duyệt (hôm nay: 91%)
• Capacity50-100 đơn/ngày bình thường, API time < 5 giây mỗi lần
• Fallback failover time≤ 30 phút từ lúc API hỏng đến khi email parser chạy

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

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

Hai con đường vào hệ thống: JaHandmadeArt đã chuyển sang API (chính thức 2026-05-12); 18 shop còn lại vẫn dùng email parser. Lộ trình P1-13 sẽ cutover shop thứ hai vào API vào tuần W7. Email parser vẫn chạy như fallback — khi API hỏng 3 lần liền, hệ thống tự chuyển sang email 10 phút một lần cho đến khi API fix.

Etsy shop_id là số thực, không phải Odoo PK: JaHandmadeArt có etsy_api_shop_id = 60752333 (Etsy gán). Trước đó dùng Odoo ID (Sandbox test) nhưng đã deprecated. Tất cả URL /shops/{shop_id}/* phải dùng etsy_api_shop_id, không dùng Odoo record ID.

Etsy app scope approved cho 4 scopes: transactions_r/w (đọc-ghi đơn), listings_r/w (đọc-ghi sản phẩm), shops_r (đọc info shop), email_r (đọc email báo đơn). Scope conversations_r (buyer messaging) chưa approved — cần re-submit với Etsy khi feature buyer-msg phát triển.