Yêu cầu đồng bộ hóa đơn

Tạo một yêu cầu đồng bộ để lấy hóa đơn mua vào theo khoảng ngày. Yêu cầu chạy bất đồng bộ; đối tác poll trạng thái rồi truy xuất kết quả.

POST /tax-accounts/{accountId}/sync

Request body

Field	Kiểu	Mặc định	Ý nghĩa
dateFrom	date	30 ngày trước	Ngày lập từ (YYYY-MM-DD)
dateTo	date	hôm nay	Ngày lập đến
direction	string	purchase	purchase = mua vào
fetchDetails	boolean	true	true = kèm dòng hàng; false = chỉ header (rẻ hơn)

Ví dụ request

{ "dateFrom": "2025-03-01", "dateTo": "2025-03-31", "fetchDetails": true }

Ví dụ response (202)

{ "id": "b6bf6a2a-9082-4882-b798-b35fc5985894", "status": "queued", "priority": 0 }

Ràng buộc khoảng ngày

Cổng thuế giới hạn mỗi truy vấn ~31 ngày. Khoảng dài hơn sẽ được hệ thống tự chia thành nhiều cửa sổ ≤31 ngày.

Theo dõi tiến trình

GET /sync-jobs/{jobId}

Ví dụ response

{
  "id": "b6bf6a2a-9082-4882-b798-b35fc5985894",
  "status": "succeeded",
  "totalFound": 12,
  "totalSaved": 12,
  "errorCode": null
}

status	Ý nghĩa
queued	Đang chờ xử lý
running	Đang đồng bộ hóa đơn
succeeded	Hoàn tất
failed	Thất bại (xem errorCode, errorMessage)

Các errorCode thường gặp: INVALID_CREDENTIALS (sai mật khẩu → cần cập nhật mật khẩu), SYNC_FAILED (captcha/mạng).

Poll GET /sync-jobs/{jobId} mỗi 1–2 giây đến khi status ∈ {succeeded, failed}, sau đó gọi Danh sách hóa đơn.

Danh sách yêu cầu đồng bộ

GET /sync-jobs?accountId=&status=&page=&limit= — liệt kê các yêu cầu đồng bộ (dùng cho theo dõi/vận hành).