跳到主要内容
Sursa Developers

POST/v1/finance/report

获取财务汇总报告

finance_report

返回组织发票或付款的合计，最多按三个维度分组（分类、分组、供应商的业务类型、供应商、买方、往来单位、方向、货币、月、季度、年），度量为 invoiced、paid、unpaid 和 tax。合计只包括用户可见的文档（其数据权限档案的合集和分类，以及“仅根据已核实的卡片作答”设置）；请求中的筛选条件可以缩小这一范围，但永远不会扩大它。

在 reporting 模式（默认）下，金额按单据日期的汇率折算为组织的报告货币，没有汇率的金额列在 conversion.unconverted 中。在 original 模式下，不同货币的金额不相加，货币成为行的一个维度。行数超过 limit 时，truncated 为 true，totals 仍涵盖所有行。需要可访问财务数据的数据权限档案（finance.forbidden）。

报告、发票和付款列表及其导出都是读取操作，尽管它们使用 POST：它们在“View as”模式下可用，具有 read 权限范围的 API 密钥也可以使用（与以前一样，具有 write 权限范围的密钥同样可以使用）。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

请求头参数

  • X-View-Asstring

    仅适用于具有 admin 角色的 API 密钥。以数据权限档案 <profile>[:viewer|verifier|editor] 的身份发出请求，例如 employee:viewer。部署密钥不能使用此头（403）。

Cookie 参数

  • kb_view_asstring

    会话的“View as”模式 Cookie。POST /auth/view-as 设置该 Cookie，DELETE /auth/view-as 将其清除。

请求体

application/json

对象：FinanceReportRequest

  • basisstring

    invoices：发票、贷项通知单和收据。payments：付款记录（现金流）。使用 payments 时，唯一的度量是 paid，direction 维度和合计显示资金流向（in 或 out），而您自己的法人实体之间的转账为 internal。

    可选值: invoicespayments

    默认值："invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    默认为 invoiced（payments 时为 paid）。

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    决定期间和 from/to 筛选条件的日期：单据日期或付款日期。

    可选值: documentpayment

    默认值："document"

  • filtersFinanceFilter
  • order_bystring

    排序依据的度量或维度。默认按第一个度量降序排列。

  • order_descboolean

    默认值：true

  • limitinteger

    默认值：1000≥ 1, ≤ 10000

  • languagestring

    分类和分组标签的语言，en|ru。默认为 en。

响应

200报告

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：FinanceReport

  • currency_modeFinanceCurrencyMode必填
  • currencystring

    报告货币（reporting 模式）。

  • rowsarray of FinanceReportRow必填
  • totalsarray of FinanceReportTotal必填

    截断前所有行的合计，每种货币一条记录（按方向拆分的报告中，每种货币和方向各一条，FinanceReportTotal.direction）。

  • truncatedboolean必填
  • limitinteger必填
  • total_rowsinteger必填

    截断前分组行的数量。

  • conversionFinanceConversion
  • warningsarray of string

    警告代码：profile_missing，未设置组织的公司信息，因此发票方向默认为 in；catalog_missing，未加载公司名录；fx_rate_missing，部分金额没有汇率（conversion.unconverted）；fx_rate_stale，部分汇率已过时；enrichment_pending，部分文档仍在处理中，未计入合计。遇到未知代码时显示通用消息。

400请求无效：参数值或对象状态不允许执行该操作（`detail` 为消息）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

  • Retry-After

    重试请求前需要等待的秒数。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

503此请求所依赖的服务暂时不可用。请稍后重试。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

安全重试

每个 POST 和 PATCH 请求都传入 Idempotency-Key 头（例如一个 UUID）。24 小时内用同一个键重试时，返回已保存的响应，不会再次执行请求。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← finance · API 参考