Open API ภาพรวม

Ocriva Open API เปิดให้นักพัฒนาภายนอกเข้าถึงการประมวลผลเอกสาร, การจัดการ Template และประวัติการประมวลผลแบบ Programmatic เหมาะสำหรับการเชื่อมต่อแบบ Server-to-Server, Automated Pipeline และเครื่องมือที่พัฒนาบนพื้นฐานของ Ocriva

Base URL

https://api.ocriva.com/v1

Endpoint ทั้งหมดในส่วนนี้อิงจาก Base URL นี้

Authentication

Open API รองรับวิธีการยืนยันตัวตน 2 แบบ แนะนำให้ใช้ API Key สำหรับการเชื่อมต่อใหม่ทุกรายการ

API Key (แนะนำ)

ส่ง API key ผ่าน Header X-API-Key:

curl https://api.ocriva.com/v1/openapi/projects \
  -H "X-API-Key: ocr_your_api_key"

หรือจะใช้ Header Authorization กับ Bearer scheme ก็ได้:

curl https://api.ocriva.com/v1/openapi/projects \
  -H "Authorization: Bearer ocr_your_api_key"

JWT (Legacy)

แลก API key เป็น JWT อายุสั้นโดยเรียก Login Endpoint จากนั้นแนบ JWT ไปใน Request ถัดไป:

# Step 1: Exchange API key for JWT
curl -X POST https://api.ocriva.com/v1/openapi/auth/login \
  -H "Content-Type: application/json" \
  -d '{"token": "ocr_your_api_key"}'
 
# Step 2: Use the returned accessToken in requests
curl https://api.ocriva.com/v1/openapi/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response ของ Login จะมี accessToken, expiresIn (หน่วยวินาที) และ Metadata ของ Token (tokenInfo)

ประเภท Token

API key มีขอบเขตอยู่ที่ Organization หรือ Project เดียว

เมื่อใช้ Organization Token แล้วส่ง projectId ที่ไม่ได้อยู่ใน Organization จะได้รับ Response 401 Unauthorized เช่นเดียวกัน เมื่อใช้ Project Token แล้วส่ง projectId ที่ไม่ตรงกับ Project ของ Token ก็จะได้รับ 401 เช่นกัน

Rate Limiting

Request ถูกจำกัดที่ 60 ครั้งต่อนาที ต่อ API key หากเกินขีดจำกัดนี้ API จะส่ง Response 429 Too Many Requests พร้อม Header Retry-After ที่ระบุจำนวนวินาทีที่ต้องรอก่อน Retry

{
  "statusCode": 429,
  "message": "Too many requests. Please slow down.",
  "error": "Too Many Requests"
}

รูปแบบ Error

Error ทุกรายการใช้รูปแบบ Envelope เดียวกัน:

{
  "statusCode": 400,
  "message": "projectId is required for organization tokens",
  "error": "Bad Request"
}

Pagination

Endpoint ที่คืนรายการจะรับ Query Parameter page และ limit และตอบกลับด้วย Object pagination:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}