POST/v1/finance/invoices

แสดงรายการใบแจ้งหนี้

finance_invoices

ส่งคืนใบแจ้งหนี้ ใบลดหนี้ และใบเสร็จรับเงินขององค์กรทีละหน้า พร้อมตัวกรอง (ช่วงเวลา ทิศทาง หมวดหมู่ คู่ค้า สกุลเงิน ประเภทเอกสาร ชำระแล้ว เลยกำหนด ต้องตรวจทาน และค้นหาตามเลขที่และคู่สัญญา) การเรียงลำดับ และยอดเงินในสกุลเงินที่ใช้รายงานพร้อมอัตราการแปลงสกุลเงิน รวมเฉพาะเอกสารที่ผู้ใช้มองเห็น หากต้องการหน้าถัดไป ให้ส่ง next_cursor เป็น cursor พร้อมตัวกรองชุดเดิม ต้องมีโปรไฟล์ข้อมูลที่เข้าถึงข้อมูลการเงินได้

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

ส่งคีย์ 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

ออบเจ็กต์: FinanceListRequest

filtersFinanceFilter
date_basisstring
ค่าที่ใช้ได้: documentpayment
ค่าเริ่มต้น: "document"
orderstring
ค่าที่ใช้ได้: date_descdate_ascamount_descamount_asc
ค่าเริ่มต้น: "date_desc"
currency_modeFinanceCurrencyMode
limitinteger
ค่าเริ่มต้น: 100≥ 1, ≤ 1000
cursorstring
languagestring
ภาษาของป้ายชื่อหมวดหมู่ en|ru

การตอบกลับ

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

ออบเจ็กต์: FinanceInvoicePage

invoicesarray of FinanceInvoiceRowจำเป็น
totalintegerจำเป็น
จำนวนใบแจ้งหนี้ทั้งหมดที่ตรงกับตัวกรอง
next_cursorstring
เคอร์เซอร์ของหน้าถัดไป ถ้าไม่มีฟิลด์นี้ แสดงว่าเป็นหน้าสุดท้าย
currencystring
สกุลเงินที่ใช้รายงานของฟิลด์ reporting (โหมด reporting)
warningsarray of string
รหัสคำเตือน เหมือนกับใน FinanceReport.warnings
has_moreboolean
มีหน้าถัดไปหรือไม่ มีในการตอบกลับเมื่อคำขอส่ง limit หรือ cursor

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

curl -X POST 'https://api.sursa.com/v1/finance/invoices' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"from":"2026-10-24","to":"2026-10-24","directions":["in"]},"date_basis":"document","order":"date_desc"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

ลองใช้

คีย์ API

คีย์อยู่ในหน่วยความจำของแท็บนี้ และส่งไปยัง https://api.sursa.com เท่านั้น

คำขอมีผลกับข้อมูลจริงขององค์กรของคุณ

X-View-As header

Idempotency-Key

ถ้าเว้นว่างไว้ ระบบจะสร้างคีย์ใหม่ให้แต่ละคำขอ

เนื้อหาคำขอ (JSON)