POST/v1/finance/report

재무 요약 보고서 조회

finance_report

조직의 청구서나 결제 합계를 최대 세 개의 차원(카테고리, 그룹, 공급업체의 업종, 공급업체, 구매자, 거래처, 방향, 통화, 월, 분기, 연도)으로 묶어 측정값 invoiced, paid, unpaid, tax와 함께 반환해요. 합계에는 사용자가 볼 수 있는 문서만 들어가요(데이터 프로필의 컬렉션과 카테고리, “answer only from verified cards”(검증된 카드로만 답변) 설정 기준). 요청 필터는 이 범위를 좁힐 수만 있고 넓히지는 못해요.

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).

쿠키 파라미터

kb_view_asstring
세션의 “View as” 모드(다른 사용자로 보기) 쿠키. POST /auth/view-as 요청으로 설정하고 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자격 증명(세션 쿠키나 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 레퍼런스

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

사용해 보기

API 키

키는 이 탭의 메모리에만 보관되며 https://api.sursa.com 주소로만 전송돼요.

요청은 조직의 실제 데이터에 적용돼요.

X-View-As header

Idempotency-Key

비워 두면 요청마다 새 키가 생성돼요.

요청 본문(JSON)