Chuyển tới nội dung
Sursa Developers

POST/v1/finance/report

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

finance_report

Trả về tổng cộng của hóa đơn hoặc khoản thanh toán của tổ chức, nhóm theo tối đa ba chiều (danh mục, nhóm, loại hình kinh doanh của nhà cung cấp, nhà cung cấp, bên mua, đối tác giao dịch, hướng, tiền tệ, tháng, quý, năm), với các chỉ số invoiced, paid, unpaid và tax. Tổng cộng chỉ gồm các tài liệu mà người dùng nhìn thấy (bộ sưu tập và danh mục trong hồ sơ dữ liệu của họ, và cài đặt “chỉ trả lời từ thẻ đã kiểm chứng”); bộ lọc của yêu cầu thu hẹp phạm vi này nhưng không bao giờ mở rộng nó.

Ở chế độ reporting (mặc định), số tiền được quy đổi sang tiền tệ báo cáo của tổ chức theo tỷ giá tại ngày của tài liệu, và các số tiền không có tỷ giá được liệt kê trong conversion.unconverted. Ở chế độ original, số tiền bằng các loại tiền tệ khác nhau không được cộng gộp, và tiền tệ trở thành một chiều của dòng. Nếu có nhiều dòng hơn limit, truncated là true, và totals vẫn bao gồm mọi dòng. Cần hồ sơ dữ liệu có quyền truy cập dữ liệu tài chính (finance.forbidden).

Báo cáo, danh sách hóa đơn và khoản thanh toán cùng các bản xuất của chúng là thao tác đọc dù dùng POST: chúng khả dụng ở chế độ “View as” và cho khóa API có phạm vi read (và, như trước đây, cho khóa có phạm vi write).

Xác thực

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

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

200Báo cá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: FinanceReport

  • currency_modeFinanceCurrencyModebắt buộc
  • currencystring

    Tiền tệ báo cáo (chế độ reporting).

  • rowsarray of FinanceReportRowbắt buộc
  • totalsarray of FinanceReportTotalbắt buộc

    Tổng trên mọi dòng trước khi cắt bớt, mỗi tiền tệ một bản ghi (với báo cáo chia theo hướng tiền, mỗi tiền tệ và mỗi hướng một bản ghi, FinanceReportTotal.direction).

  • truncatedbooleanbắt buộc
  • limitintegerbắt buộc
  • total_rowsintegerbắt buộc

    Số dòng đã nhóm trước khi cắt bớt.

  • conversionFinanceConversion
  • warningsarray of string

    Mã cảnh báo: profile_missing, thông tin doanh nghiệp của tổ chức chưa được thiết lập, nên hướng của hóa đơn mặc định là in; catalog_missing, danh bạ doanh nghiệp chưa được tải; fx_rate_missing, một số khoản tiền không có tỷ giá (conversion.unconverted); fx_rate_stale, một số tỷ giá đã cũ; enrichment_pending, một số tài liệu vẫn đang được xử lý và chưa được tính vào tổng. Với mã không xác định, hãy hiển thị một thông báo chung.

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