USPS (Legacy) - Tích hợp Bưu điện Hoa Kỳ
Tích hợp USPS cho vận chuyển nội địa và quốc tế từ Hoa Kỳ
Module USPS (Legacy) tích hợp với dịch vụ Bưu điện Hoa Kỳ (United States Postal Service) để tính phí vận chuyển tự động dựa trên trọng lượng và địa chỉ, tạo nhãn vận chuyển cho đơn hàng, tạo nhãn trả hàng cho khách hàng, theo dõi lô hàng qua hệ thống USPS.
Đây là phiên bản cũ (Legacy). USPS khuyến nghị cài đặt module mới "United States Postal Service (USPS) Shipping" và gỡ bỏ module này càng sớm càng tốt.
Cảnh báo quan trọng
Đây là phiên bản cũ (Legacy). USPS khuyến nghị cài đặt module mới "United States Postal Service (USPS) Shipping" và gỡ bỏ module này càng sớm càng tốt.
Tính năng chính
Điểm chính
• Tính phí vận chuyển tự động dựa trên trọng lượng và địa chỉ
• Tạo nhãn vận chuyển (shipping labels) cho đơn hàng
• Tạo nhãn trả hàng (return labels) cho khách hàng
• Theo dõi lô hàng qua hệ thống USPS
• Hủy lô hàng khi cần thiết
• Hỗ trợ First Class (tối đa 4 pounds), Priority (không giới hạn), Express (không giới hạn)
• Hỗ trợ vận chuyển nội địa (Domestic) và quốc tế (International)
Yêu cầu
Điểm chính
• Tài khoản USPS Web Tools (User ID)
• Địa chỉ công ty phải ở Hoa Kỳ
• Số điện thoại công ty phải là số Hoa Kỳ (10 chữ số)
• Mã ZIP hợp lệ (định dạng 12345 hoặc 12345-6789)
Loại dịch vụ USPS
Các dịch vụ USPS
| Dịch vụ | Mô tả | Giới hạn trọng lượng |
|---|---|---|
| First Class | Hạng nhất - Tiết kiệm | Tối đa 4 pounds |
| Priority | Ưu tiên - Cân bằng | Không giới hạn |
| Express | Tốc hành - Nhanh nhất | Không giới hạn |
Bảng tra cứu thuật ngữ EN/VI
| Fields | Trường dữ liệu | Description |
|---|---|---|
| USPS User ID | ID người dùng USPS | ID tài khoản USPS Web Tools |
| Account Validated | Đã xác thực tài khoản | Tài khoản đã được USPS xác thực |
| USPS Service | Dịch vụ USPS | First Class, Priority, Express |
| Delivery Nature | Tính chất giao hàng | Domestic hoặc International |
| Content Type | Loại nội dung | Merchandise, Documents, Gift, Sample, Return |
| Label Format | Định dạng nhãn | PDF hoặc TIF |
| First Class | Hạng nhất | Dịch vụ tiết kiệm |
| Priority | Mức độ ưu tiên | Dịch vụ cân bằng |
| Express | Tốc hành | Dịch vụ nhanh nhất |
| Domestic | Nội địa | Trong Hoa Kỳ |
| International | Quốc tế | Ra ngoài Hoa Kỳ |
| Flat Rate Box | Khung giá cho thùng hàng | Hộp giá cố định |
| Flat Rate Envelope | Khung giá cho đóng gói | Phong bì giá cố định |
Cấu hình phương thức vận chuyển USPS
Các bước cấu hình chi tiết:
Các bước thực hiện
1. Vào Inventory → Configuration → Delivery → Shipping Methods
2. Nhấn New
3. Điền thông tin: Shipping Method (tên), Provider (USPS Legacy), Company
4. Tab USPS Configuration - Thông tin tài khoản: USPS User ID, Account Validated (đánh dấu nếu đã xác thực)
5. Cấu hình dịch vụ: USPS Service (First Class/Priority/Express), Delivery Nature (Domestic/International)
6. Content Type: Merchandise, Documents, Gift, Sample, Return (loại hàng hóa)
7. Cấu hình container (Domestic): Type of container (Regular/Rectangular/Non-rectangular), Type of USPS domestic regular container
8. Cấu hình container (International): USPS Mail Type, Type of USPS International regular container
9. Kích thước tùy chỉnh: Package Width, Length, Height, Girth (nếu cần)
10. Tùy chọn: Label Format (PDF/TIF), Machinable, Return Label on Delivery, Non delivery option
Tính phí vận chuyển
Quy trình tính phí từ Sale Order:
Điểm chính
• Yêu cầu: Địa chỉ công ty đầy đủ (street, city, state, ZIP, country US), địa chỉ khách hàng đầy đủ, tất cả sản phẩm có weight > 0, mã ZIP đúng định dạng
Các bước thực hiện
1. Tạo hoặc mở đơn bán hàng
2. Điền đầy đủ: Khách hàng với địa chỉ giao hàng hợp lệ, sản phẩm với trọng lượng đã cấu hình
3. Nhấn Add Shipping
4. Chọn phương thức USPS
5. Nhấn Get Rate để lấy giá từ USPS
6. Hệ thống hiển thị phí vận chuyển (tự động chuyển đổi từ USD)
7. Nhấn Add để thêm phí vào đơn hàng
Tạo nhãn vận chuyển
Quy trình tạo nhãn:
Điểm chính
• Thông tin trên nhãn: Barcode (mã vạch), địa chỉ gửi/nhận, tracking number, loại dịch vụ, trọng lượng
• Tải nhãn: Mở picking → Chatter → Tìm message "Shipment created into USPS" → Nhấn file đính kèm (PDF hoặc TIF)
Các bước thực hiện
1. Vào Inventory → Operations → Transfers
2. Mở picking cần tạo nhãn (trạng thái Ready hoặc Done)
3. Đảm bảo: Carrier = USPS, địa chỉ giao hàng hợp lệ, trọng lượng đã cập nhật
4. Nhấn Send to Shipper (hoặc Validate nếu chưa validate)
5. Hệ thống gọi API USPS và tạo nhãn
6. Nhãn được đính kèm vào chatter của picking
7. Số theo dõi (Tracking Number) được cập nhật tự động
Tạo nhãn trả hàng
Hai cách tạo nhãn trả hàng:
Điểm chính
• Tự động: Bật Return Label on Delivery trong cấu hình, nhãn trả hàng tự động tạo khi tạo nhãn giao hàng
• Thủ công: Mở picking đã giao → Nhấn Return → Tạo picking trả hàng mới với Operation Type = Returns, đảo ngược địa chỉ
• Lưu ý: Chỉ hỗ trợ Domestic, không thể tạo nhãn trả hàng cho International
• Địa chỉ người gửi và người nhận được đảo ngược, phí trả hàng có thể khác phí giao hàng
Theo dõi lô hàng
Tracking number và theo dõi trên USPS:
Điểm chính
• Xem tracking: Trường Tracking Reference (carrier_tracking_ref) trên picking, số có dạng 9400111899562941234567
• Theo dõi trực tuyến: Nhấn Tracking hoặc truy cập https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=[TRACKING_NUMBER]
• Cập nhật trạng thái: USPS không tự động cập nhật vào Odoo, cần kiểm tra thủ công hoặc tích hợp webhook/API
Hủy lô hàng
Điều kiện và quy trình hủy:
Điểm chính
• Điều kiện: Tài khoản USPS phải được xác thực (Account Validated = True), lô hàng chưa được USPS xử lý (thường trong 24 giờ), có tracking number hợp lệ
• Quy trình: Mở picking cần hủy → Nhấn Cancel Shipment → Hệ thống gọi API USPS
• Nếu thành công: Tracking number bị xóa, carrier price về 0, message "Shipment #[NUMBER] has been cancelled"
• Nếu thất bại: Kiểm tra tài khoản đã xác thực, liên hệ USPS để hủy thủ công, tạo nhãn mới nếu cần gửi lại
Xử lý lỗi thường gặp
Lỗi và giải pháp
| Lỗi | Nguyên nhân | Giải pháp |
|---|---|---|
| Address of company missing or wrong | Địa chỉ công ty thiếu | Settings → Companies → Update Info: Street, City, State, ZIP, Country (US), Phone (10 chữ số) |
| Please enter a valid ZIP code | ZIP không đúng định dạng | Sử dụng 12345 hoặc 12345-6789, kiểm tra trên USPS.com |
| Recipient address cannot be found | Địa chỉ không tồn tại | Xác minh với khách hàng, sử dụng công cụ xác thực USPS |
| Weight is missing | Sản phẩm chưa có trọng lượng | Inventory → Products → Điền Weight > 0 |
| Maximum weight 4 pounds | First Class giới hạn 4 pounds | Chuyển sang Priority hoặc Express, hoặc chia nhỏ đơn hàng |
| USPS Domestic for USA only | Dùng Domestic cho địa chỉ quốc tế | Đổi Delivery Nature thành International |
| USPS International for outside USA | Dùng International cho địa chỉ trong US | Đổi Delivery Nature thành Domestic |
| USPS Server Not Found | Không kết nối được API | Kiểm tra internet, firewall, thử lại sau |
| Service cannot deliver this package | Dịch vụ không khả dụng | Chọn dịch vụ khác (Express/Priority/First Class) |
Mẹo sử dụng thực tế
Điểm chính
• Tối ưu chi phí: First Class cho gói < 4 pounds (tiết kiệm nhất), Priority cân bằng giá/tốc độ (phù hợp đa số), Express chỉ khi khách cần gấp (giá cao nhất)
• Chuẩn bị dữ liệu: Luôn cập nhật trọng lượng sản phẩm, xác thực địa chỉ khách hàng ngay khi nhập, sử dụng địa chỉ công ty chuẩn
• Quản lý nhãn: In nhãn ngay sau khi tạo, lưu trữ tracking number, tạo nhãn trả hàng sẵn cho sản phẩm dễ trả (quần áo, giày dép)
• Xử lý vấn đề: Kiểm tra log XML nếu gặp lỗi (bật Log XML trong carrier), liên hệ USPS support nếu API lỗi không rõ, cân nhắc chuyển sang module USPS mới
• Tích hợp: Tự động tạo nhãn khi validate picking (cần customization), gửi email tracking tự động, tích hợp portal để khách tự in nhãn trả