ข้ามไปยังเนื้อหา
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” และกับคีย์ API ที่มีขอบเขตสิทธิ์ read (และใช้กับคีย์ที่มีขอบเขตสิทธิ์ write ได้เหมือนเดิม)

การยืนยันตัวตน

ส่งคีย์ API ในเฮดเดอร์ Authorization: Authorization: Bearer <คีย์>

พารามิเตอร์เฮดเดอร์

  • X-View-Asstring

    สำหรับคีย์ API ที่มีบทบาท admin เท่านั้น ทำคำขอในนามโปรไฟล์ข้อมูล <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 (paid สำหรับ payments)

  • 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ 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 นอกเหนือจากรหัสทั่วไปของทุกคำขอ

การลองใหม่อย่างปลอดภัย

ส่งเฮดเดอร์ Idempotency-Key (เช่น UUID) ไปกับทุกคำขอ POST และ PATCH เมื่อลองใหม่ด้วยคีย์เดียวกันภายใน 24 ชั่วโมง Sursa จะส่งคืนการตอบกลับที่บันทึกไว้แทนการดำเนินการคำขอซ้ำ

ขีดจำกัดอัตราการเรียก

การตอบกลับมีเฮดเดอร์ RateLimit และ RateLimit-Policy รวมถึงเฮดเดอร์แบบเดิม X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset การตอบกลับ 429 มี Retry-After เป็นวินาที ให้รอตามนั้นแล้วลองใหม่

← finance · เอกสารอ้างอิง API