REST API

Khả dụng

Tài nguyên, header và cấu trúc request/response của API v1.

API v1 theo hướng tài nguyên: mỗi đối tượng có trường object, danh sách có object=list. Mọi phản hồi kèm header poro-request-id và poro-version.

Header chuẩn

Header	Bắt buộc	Ý nghĩa
X-Poro-Key	Có	Khoá API của tổ chức. Mỗi khoá thuộc đúng một tổ chức.
Idempotency-Key	Với lệnh ghi	Gọi lại cùng khoá trả về đúng kết quả cũ, không tạo bản ghi mới.
Content-Type	Với POST	application/json

Tài nguyên khả dụng

Method	Đường dẫn	Mô tả
GET	/v1/inventory	Danh sách pool tồn kho
POST	/v1/inventory/reserve	Giữ chỗ tồn kho (soft-lock)
POST	/v1/inventory/release	Trả lại phần giữ chỗ
POST	/v1/inventory/commit	Chốt giữ chỗ thành trừ kho thật
POST	/v1/orders	Tạo đơn hàng
POST	/v1/orders/cancel	Huỷ đơn hàng
GET	/v1/catalog/items	Danh mục hàng hoá đã đồng bộ
GET	/v1/events	Sổ sự kiện nền tảng
GET · POST	/v1/streams	Liệt kê và tạo stream
POST	/v1/streams/start · /v1/streams/stop	Khởi động / dừng stream
GET · POST	/v1/webhook-endpoints	Xem và đăng ký điểm nhận webhook
GET	/v1/usage	Mức sử dụng 30 ngày và hạn mức tài nguyên

Ví dụ

POST /api/public/v1/inventory/reserve
Host: creator.poroai.life
X-Poro-Key: poro_<prefix>_<secret>
Idempotency-Key: order-8891
Content-Type: application/json

{ "pool_id": "…", "quantity": 2, "ttl_seconds": 600 }

{
  "object": "reservation",
  "id": "…",
  "status": "held",
  "quantity": 2,
  "expires_at": "2026-09-08T10:40:00Z"
}

Endpoint cũ /api/public/v1/gateway vẫn hoạt động cho tích hợp hiện có, nhưng tích hợp mới nên dùng tài nguyên REST ở trên.

OpenAPI

Đặc tả OpenAPI 3.1 luôn cập nhật tại /api/public/v1/openapi.json — dùng để sinh client hoặc nhập vào Postman.