POST/v1/finance/report/export

Xuất báo cáo tổng hợp tài chính

finance_report_export

Trả về cùng báo cáo như POST /v1/finance/report dưới dạng tệp: CSV (UTF-8, dấu phân tách “,”, với các chiều, tiền tệ và chỉ số trong dòng tiêu đề) hoặc XLSX (trang tính “Report” và trang tính “Totals”, cùng trang tính “Unconverted” khi một số số tiền không có tỷ giá). Với báo cáo chia theo hướng, hướng là cột direction của các dòng và của trang tính “Totals”. Tệp CSV cũng chứa tổng cộng và các số tiền không có tỷ giá: sau các dòng của báo cáo là một dòng trống, một dòng Totals, một dòng tiêu đề và các tổng cộng, tiếp theo theo cùng cách là Unconverted (tiền tệ, số tài liệu, số tiền theo tiền tệ gốc) nếu có những số tiền như vậy.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số truy vấn

formatstring
Định dạng tệp xuất tài chính: csv (mặc định) hoặc xlsx.
Giá trị cho phép: csvxlsx
Mặc định: "csv"

Tham số header

X-View-Asstring
Chỉ dành cho khóa API có vai trò admin. Thực hiện yêu cầu với tư cách hồ sơ dữ liệu <profile>[:viewer|verifier|editor], ví dụ employee:viewer. Khóa cài đặt không thể dùng header này (403).

Tham số cookie

kb_view_asstring
Cookie của chế độ “View as” cho một phiên. POST /auth/view-as đặt cookie này, còn DELETE /auth/view-as xóa nó.

Phần thân yêu cầu

application/json

Đối tượng: FinanceReportRequest

basisstring
invoices: hóa đơn, giấy báo có và biên lai. payments: nhật ký thanh toán (dòng tiền). Với payments, chỉ số duy nhất là paid, còn chiều direction và tổng cho thấy hướng di chuyển của tiền, in hoặc out, trong khi khoản chuyển giữa các pháp nhân của chính bạn là internal.
Giá trị cho phép: invoicespayments
Mặc định: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Mặc định là invoiced (paid với payments).
currency_modeFinanceCurrencyMode
date_basisstring
Ngày nào xác định kỳ báo cáo và bộ lọc from/to: ngày chứng từ hoặc ngày thanh toán.
Giá trị cho phép: documentpayment
Mặc định: "document"
filtersFinanceFilter
order_bystring
Chỉ số hoặc chiều dùng để sắp xếp. Mặc định là chỉ số đầu tiên theo thứ tự giảm dần.
order_descboolean
Mặc định: true
limitinteger
Mặc định: 1000≥ 1, ≤ 10000
languagestring
Ngôn ngữ của tên hiển thị của danh mục và nhóm, en|ru. Mặc định là en.

Phản hồi

200Tệp báo cáo (Content-Disposition: attachment)

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

text/csv

string

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

string (binary)

400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

Retry-After
Số giây cần chờ trước khi thử lại yêu cầu.
RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

503Một dịch vụ mà yêu cầu này phụ thuộc vào tạm thời không khả dụng. Hãy thử lại sau.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← finance · Tài liệu tham chiếu API

curl -X POST 'https://api.sursa.com/v1/finance/report/export' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"basis":"invoices","group_by":["category"],"measures":["invoiced"]}' \
  -o download.csv \
  -H "Authorization: Bearer $SURSA_API_KEY"

Dùng thử

Khóa API

Khóa chỉ được giữ trong bộ nhớ của tab này và chỉ được gửi tới https://api.sursa.com.

Yêu cầu tác động lên dữ liệu thật của tổ chức bạn.

X-View-As header

format query

Idempotency-Key

Khi để trống, mỗi yêu cầu sẽ được tạo một khóa mới.

Phần thân yêu cầu (JSON)