Hướng dẫn đồng bộ Xero sang PostgreSQL tự động chỉ trong 5 phút

Nếu bạn đang sử dụng Xero để quản lý kế toán và ứng dụng của bạn chạy trên PostgreSQL, có lẽ bạn đã từng mong muốn đưa cả hai bộ dữ liệu này về một nơi. Vấn đề là API của Xero không được thiết kế cho mục đích này. Từ quy trình bắt tay OAuth, lựa chọn tổ chức, giới hạn tốc độ khắt khe cho đến vòng đời của token, việc xây dựng một đường truyền đồng bộ dữ liệu đáng tin cậy tốn nhiều thời gian hơn đội ngũ kỹ thuật dự kiến — và việc bảo trì nó còn tốn thời gian hơn nữa.

AI có thể tạo ra mã tích hợp ban đầu trong một buổi chiều. Nhưng những gì nó không thể làm là giữ cho hệ thống chạy ổn định: làm mới token trước khi hết hạn, xử lý luồng kết nối đa người thuê (multi-tenant), tuân thủ giới hạn 60 lệnh gọi mỗi phút, hay khôi phục sau sự cố lúc 3 giờ sáng. Đó mới chính là nơi chi phí thực sự phát sinh — không phải ở khâu xây dựng, mà ở khâu vận hành.

Bài viết này sẽ giới thiệu một giải pháp thay thế chỉ mất 5 phút. Bạn chỉ cần kết nối cơ sở dữ liệu, cấp quyền cho tổ chức Xero của mình, và các dữ liệu như danh bạ, hóa đơn hoặc giao dịch ngân hàng sẽ xuất hiện dưới dạng bảng trong Postgres — được đồng bộ tự động theo lịch trình bạn lựa chọn.

Đồng bộ dữ liệu kế toán Xero sang PostgreSQL tự động

Tuy nhiên, trước khi đi sâu vào giải pháp, chúng ta hãy cùng tìm hiểu lý do tại sao làm việc với API của Xero lại khó khăn đến vậy.

Tại sao API của Xero lại phức tạp

API của Xero rất mạnh mẽ, nhưng nó không được xây dựng để trích xuất dữ liệu hàng loạt. Ngay cả các lập trình viên dày dạn kinh nghiệm cũng dễ dàng gặp trở ngại.

OAuth 2.0 với việc lựa chọn bắt buộc. Không có đơn giản là một API key. Mọi tích hợp với Xero đều yêu cầu quy trình OAuth 2.0 đầy đủ — đăng ký ứng dụng trong cổng nhà phát triển Xero, xử lý chuyển hướng ủy quyền, lưu trữ token và làm mới chúng trước khi hết hạn. Nhưng Xero còn thêm một lớp nữa: sau khi ủy quyền, bạn phải truy vấn điểm cuối /connections để liệt kê các tổ chức của người dùng, sau đó để họ chọn tổ chức nào muốn đồng bộ. Nếu bỏ qua bước này, bạn không thể thực hiện bất kỳ lệnh gọi API nào. Bỏ lỡ việc làm mới token sẽ khiến tích hợp của bạn ngừng hoạt động âm thầm.

Giới hạn tốc độ nghiêm ngặt. Xero áp dụng giới hạn 60 lệnh gọi API mỗi phút cho mỗi tổ chức và 5.000 lệnh gọi mỗi ngày cho mỗi ứng dụng. Con số này thấp hơn nhiều so với hầu hết các API thanh toán khác. Chạm đến giới hạn này và bạn sẽ bị throttling — quá trình đồng bộ sẽ bị đình trệ cho đến khi khung thời gian đặt lại. Việc xây dựng logic thử lại và xử lý đợi là bắt buộc, không phải tùy chọn.

Không có điểm cuối xuất hàng loạt. Bạn muốn tất cả các hóa đơn của mình? Bạn phải phân trang qua chúng từng trang một — mặc định là 100 bản ghi mỗi trang. Xero sử dụng phân trang dựa trên trang, nghĩa là bạn thực hiện các lệnh gọi lặp đi lặp lại, theo dõi số trang và xử lý các trường hợp cạnh khi bản ghi được thêm vào giữa quá trình phân trang. Đối với các tài khoản lớn có hàng ngàn liên hệ hoặc hóa đơn, điều này có nghĩa là hàng chục lệnh gọi API chỉ để lấy một bộ dữ liệu hoàn chỉnh.

Mối quan hệ kế toán phức tạp. Các thực thể trong Xero có mối quan hệ sâu sắc. Một hóa đơn tham chiếu đến một liên hệ, các mục dòng tham chiếu đến tài khoản, thanh toán tham chiếu đến hóa đơn và tài khoản ngân hàng. Để có được bức tranh toàn cảnh, bạn phải truy vấn nhiều điểm cuối và tự nối kết quả lại.

Hầu hết các đội nhóm cần dữ liệu Xero trong PostgreSQL thường kết thúc ở một trong ba chỗ: tích hợp tùy chỉnh (tốn kém bảo trì), sử dụng công cụ ETL doanh nghiệp (quá tải và đắt đỏ cho nhu cầu nhỏ), hoặc xuất thủ công qua CSV (không thể tự động hóa).

Tại sao lại chọn PostgreSQL cho dữ liệu kế toán?

Khi dữ liệu Xero của bạn nằm trong PostgreSQL, kế toán không còn là một hệ thống riêng biệt mà trở thành một phần của ứng dụng của bạn:

• Truy vấn JOIN chéo hệ thống — kết nối danh bạ Xero với bảng users của bạn qua email, liên kết hóa đơn với các đơn đặt hàng nội bộ, hoặc đối soát thanh toán với hồ sơ thanh toán riêng của bạn. Không cần gọi API, chỉ cần SQL.
• Không có trần giới hạn tốc độ — Xero giới hạn bạn ở 60 yêu cầu mỗi phút. Một bảng Postgres không có giới hạn như vậy. Chạy cùng một báo cáo trăm lần khi đang phát triển.
• Báo cáo SQL thuần túy — doanh thu hàng tháng, hóa đơn quá hạn, giao dịch ngân hàng đã đối soát, số dư liên hệ. Viết câu truy vấn một lần, lên lịch, hoặc cắm nó vào công cụ bảng điều khiển của bạn.
• Phân tích lịch sử sâu — API của Xero ưu tiên dữ liệu gần đây. Một bảng đồng bộ cho phép bạn thực hiện GROUP BY trong nhiều năm mà không cần phân trang hay các thao tác API phức tạp.
• Không phụ thuộc máy chủ — Supabase, Neon, Railway, AWS RDS, tự lưu trữ — bất cứ đâu Postgres của bạn chạy, đó là nơi dữ liệu Xero của bạn sẽ đến.

Năm bước để đồng bộ tự động

Dưới đây là hướng dẫn thiết lập sử dụng Codeless Sync, công cụ xử lý quy trình OAuth, lựa chọn tổ chức, đồng bộ tăng dần, làm mới token và ánh xạ lược đồ — để bạn chỉ cần thiết lập một lần và hệ thống sẽ tự chạy.

Bước 1: Kết nối cơ sở dữ liệu

Trong Codeless Sync, bắt đầu bằng cách thêm cơ sở dữ liệu PostgreSQL của bạn. Dán chuỗi kết nối của bạn — nó hoạt động với bất kỳ máy chủ PostgreSQL nào:

postgresql://user:[email protected]/dbname

Kết nối sẽ được kiểm tra tự động để đảm bảo mọi thứ hoạt động trước khi bạn tiếp tục.

Bước 2: Chọn loại dữ liệu

Nhấp vào Create Sync Configuration để mở trình hướng dẫn. Chọn Xero làm nhà cung cấp và chọn loại dữ liệu. Các loại dữ liệu có sẵn bao gồm:

• Contacts (Liên hệ) — khách hàng và nhà cung cấp với tên, email, số điện thoại và phân loại.
• Invoices (Hóa đơn) — hóa đơn bán hàng và hóa đơn mua hàng với các mục dòng, số tiền và trạng thái thanh toán.
• Payments (Thanh toán) — hồ sơ thanh toán được liên kết với hóa đơn có số tiền và ngày tháng.
• Accounts (Tài khoản) — biểu đồ tài khoản của bạn với các loại tài khoản và phân loại.
• Bank Transactions (Giao dịch ngân hàng) — tiền nhận và chi với trạng thái đối soát.

Liên hệ là một điểm khởi đầu tốt — nó dễ xác minh và giúp bạn cảm nhận được cách đồng bộ hoạt động.

Bước 3: Ủy quyền cho Xero

Thay vì xây dựng và duy trì quy trình OAuth 2.0 với lựa chọn tổ chức, bạn chỉ cần nhấp vào Connect to Xero và cấp quyền truy cập thông qua màn hình đồng ý tiêu chuẩn của Xero. Sau khi ủy quyền, bạn chọn tổ chức nào để đồng bộ — Xero hỗ trợ nhiều tổ chức cho mỗi tài khoản, vì vậy bạn chọn cái bạn cần.

Codeless Sync xử lý đăng ký ứng dụng nhà phát triển, URI chuyển hướng, lưu trữ token, làm mới token tự động và quản lý tổ chức behind the scenes — đó là một điều ít lo lắng về việc bị "gãy" âm thầm trong môi trường production.

Bước 4: Tạo bảng

Codeless Sync cần một bảng đích trong cơ sở dữ liệu của bạn. Nhấp vào Auto-Create Table và lược đồ chính xác sẽ được tạo tự động — các cột khớp với các trường của Xero, kiểu dữ liệu phù hợp và chỉ mục cho các truy vấn phổ biến.

Nếu bạn muốn xem lại SQL trước, hãy sao chép mẫu và chạy nó trong máy khách cơ sở dữ liệu của bạn.

Nhấp vào Verify Table để xác nhận cấu trúc chính xác trước khi tiếp tục.

Bước 5: Đồng bộ và xác minh

Đặt tên cho cấu hình của bạn, nhấp vào Create, sau đó nhấn Sync Now từ bảng điều khiển. Lần đồng bộ đầu tiên sẽ kéo tất cả các bản ghi khớp từ Xero. Tùy thuộc vào lượng dữ liệu của bạn, điều này thường mất từ vài giây đến vài phút.

Sau khi hoàn tất, hãy mở máy khách cơ sở dữ liệu của bạn và kiểm tra:

SELECT contact_id, name, email_address, is_customer, is_supplier, updated_date_utc
FROM xero_contacts
ORDER BY updated_date_utc DESC
LIMIT 10;

Nếu bạn thấy danh bạ Xero của mình, bạn đã hoàn tất.

Các truy vấn làm nên giá trị của giải pháp này

Đồng bộ dữ liệu chỉ là bước một. Lợi ích thực sự nằm ở những gì bạn có thể làm với nó khi dữ liệu đã nằm trong Postgres. Dưới đây là một số truy vấn trở nên đơn giản khi các bảng Xero của bạn nằm cạnh dữ liệu ứng dụng.

Doanh thu từ các hóa đơn đã thanh toán theo tháng:

SELECT
  DATE_TRUNC('month', date) AS month,
  COUNT(*) AS invoice_count,
  SUM(total) AS revenue
FROM xero_invoices
WHERE type = 'ACCREC'
  AND status = 'PAID'
GROUP BY month
ORDER BY month DESC
LIMIT 12;

Trong Xero, ACCREC có nghĩa là khoản phải thu — các hóa đơn bạn đã gửi cho khách hàng. Lọc theo PAID cho bạn doanh thu thực tế đã thu được, không chỉ là số tiền được lập hóa đơn.

Các hóa đơn chưa thanh toán — ai nợ bạn tiền:

SELECT
  invoice_number,
  contact_name,
  total,
  amount_due,
  due_date,
  CURRENT_DATE - due_date AS days_overdue
FROM xero_invoices
WHERE type = 'ACCREC'
  AND status = 'AUTHORISED'
  AND amount_due > 0
ORDER BY due_date ASC;

Thông qua API, điều này sẽ có nghĩa là phân trang qua tất cả các hóa đơn, lọc các hóa đơn chưa thanh toán trong mã của bạn và tính toán số ngày quá hạn thủ công — tất cả trong khi vẫn giữ dưới mức giới hạn 60 req/phút. Trong Postgres, chỉ là sáu dòng SQL.

Khớp danh bạ Xero với người dùng ứng dụng của bạn:

SELECT u.id AS user_id, u.email,
       xc.name AS xero_name, xc.is_customer, xc.is_supplier, xc.updated_date_utc
FROM users u
INNER JOIN xero_contacts xc ON u.email = xc.email_address
ORDER BY xc.updated_date_utc DESC;

Bảng người dùng của ứng dụng và danh sách liên hệ của Xero, được nối lại bằng email trong một truy vấn duy nhất. Đó là loại thông tin sâu sắc chéo hệ thống mà không thể thực hiện nếu không có cả hai bộ dữ liệu trong cùng một cơ sở dữ liệu.

Cài đặt một lần và quên nó đi

Một lần đồng bộ thì hữu ích. Một đường truyền tự duy trì chính nó là mang tính thay đổi. Lên lịch đồng bộ theo mỗi giờ, mỗi ngày hoặc khoảng tùy chỉnh và các bảng Xero của bạn sẽ luôn mới nhất mà không cần bất kỳ sự can thiệp thủ công nào.

Sau lần kéo toàn bộ đầu tiên, mỗi lần chạy tiếp theo sẽ tăng dần — chỉ tìm nạp các bản ghi được sửa đổi kể từ lần đồng bộ cuối cùng. Điều này giữ cho mỗi lần chạy nhanh chóng và nằm trong các giới hạn an toàn 60 req/phút và 5.000 req/ngày của Xero. Bạn không cần phải tính toán giới hạn tốc độ.

Làm mới token, kết nối tổ chức, khôi phục lỗi — tất cả được xử lý tự động. Nếu có sự cố xảy ra, bạn sẽ được thông báo ngay lập tức thay vì phát hiện ra dữ liệu cũ vài tuần sau đó. Đó là hạ tầng dữ liệu cấp sản xuất mà không có gánh nặng bảo trì.

Tổng kết

Xero có dữ liệu kế toán. PostgreSQL có dữ liệu ứng dụng của bạn. Giữ chúng riêng biệt có nghĩa là các lệnh gọi API mỗi khi bạn cần cả hai — và xây dựng một đường truyền tùy chỉnh để bắc cầu khoảng cách có nghĩa là bạn sẽ phải sở hữu mã OAuth, quản lý tổ chức, giới hạn tốc độ và xử lý lỗi mãi mãi.

Năm phút cài đặt sẽ thay thế tất cả những điều đó. Lên lịch đồng bộ, và dữ liệu Xero của bạn trở thành một bộ bảng khác nằm cạnh phần còn lại của ứng dụng — có thể truy vấn, có thể nối và luôn mới nhất.

Hãy thử ngay: codelesssync.com

Câu hỏi thường gặp

Bạn có thể kết nối Xero với PostgreSQL không?

Có. API của Xero cung cấp dữ liệu kế toán (liên hệ, hóa đơn, thanh toán, giao dịch ngân hàng, v.v.) có thể được ghi vào các bảng PostgreSQL. Thách thức nằm ở việc xây dựng và duy trì quy trình OAuth 2.0, lựa chọn tổ chức, làm mới token và logic thăm dò tăng dần. Các công cụ như Codeless Sync xử lý toàn bộ đường truyền để bạn không phải tự xây dựng.

Các loại dữ liệu Xero nào có thể đồng bộ sang PostgreSQL?

Xero cung cấp 10 loại dữ liệu cốt lõi thông qua API: liên hệ, hóa đơn, thanh toán, tài khoản, giao dịch ngân hàng, ghi chú tín dụng, mặt hàng, đơn đặt hàng mua, nhật ký chung và tổ chức. Mỗi loại ánh xạ đến bảng PostgreSQL riêng của nó (ví dụ: xero_invoices, xero_contacts) với các cột khớp với các trường của Xero.

API của Xero có giới hạn tốc độ không?

Có — và nó rất nghiêm ngặt. Xero cho phép 60 lệnh gọi API mỗi phút, 5.000 mỗi ngày và 5 yêu cầu đồng thời cho mỗi tổ chức được kết nối. Các giới hạn này áp dụng cho từng tenant, không phải cho mỗi ứng dụng. Bất kỳ giải pháp đồng bộ nào cũng cần tôn trọng các giới hạn này, đó là lý do tại sao đồng bộ tăng dần (chỉ tìm nạp các bản ghi đã thay đổi) là rất cần thiết để giữ trong giới hạn.