Bạn có thể xây dựng gì
- Đọc chuyến, tuyến, điểm dừng, tài xế và phương tiện của mọi đơn vị đã kết nối ứng dụng của bạn (các scope
*:read). - Ghi chuyến: tạo, sửa, hủy và dời lịch, phân tài xế và phương tiện, ghi lại các điểm dừng (
trips:write, do quản trị viên của đơn vị duyệt). Không thể xóa chuyến qua API. - Đăng ký nhận sự kiện chuyến (
trip.created,trip.rescheduled,trip.cancelled,trip.started,trip.completed). Stracker gọi vào endpoint https của bạn bằng một yêu cầu có chữ ký, thử lại khi lỗi và lưu nhật ký gửi. Xem webhook.
Những điều cơ bản
| Mục | Giá trị |
|---|---|
| Base URL | https://api.stracker.vn |
| Phiên bản | /v1 trong mọi đường dẫn. Payload webhook mang một ngày apiVersion. |
| Định dạng | JSON. Các endpoint token nhận nội dung dạng form (application/x-www-form-urlencoded). |
| Xác thực | Bearer token OAuth 2.0: Authorization: Bearer <access_token>. Xem xác thực. |
| Lỗi | RFC 7807 application/problem+json với code ổn định; các endpoint token trả lỗi RFC 6749. Xem lỗi. |
| Khám phá | /.well-known/oauth-authorization-server và /.well-known/jwks.json trên base URL. |
Nhận quyền truy cập
- Gửi yêu cầu kết nối bằng biểu mẫu ở trang Nhà phát triển: công ty, điều bạn muốn xây dựng, các địa chỉ chuyển hướng và các scope cần có.
- Xác nhận email. Chúng tôi gửi một đường dẫn tới email công việc; yêu cầu chỉ tới đội ngũ Stracker sau khi bạn mở đường dẫn.
- Chúng tôi xem xét. Đội ngũ có thể gửi email hỏi thêm.
- Nhận thông tin đăng nhập. Khi được duyệt, bạn nhận một đường dẫn dùng một lần để lấy client ID. Mã 6 chữ số được gửi trong một email riêng. Khóa bí mật chỉ hiện một lần, hãy lưu ngay; nếu mất, hãy nhờ chúng tôi cấp khóa mới. Nếu muốn xác thực bằng cặp khóa thay vì khóa bí mật, bạn đăng ký khóa công khai ngay trên trang đó (xem private_key_jwt).
Hai loại ứng dụng
| Ứng dụng của đơn vị | Ứng dụng đối tác | |
|---|---|---|
| Ai xây dựng | Một đơn vị vận tải, cho tài khoản của chính mình. | Một công ty phần mềm, cho nhiều đơn vị vận tải. |
| Tạo ở đâu | Quản trị viên của đơn vị tạo trong Stracker, mục API keys. | Stracker tạo, sau bước xem xét ở trên. |
| Chạm tới dữ liệu nào | Chỉ tenant của đơn vị đó. | Chỉ tenant đã cài đặt ứng dụng, và chỉ các scope mà quản trị viên tenant đó chấp nhận. |
| Truy cập máy-máy (không có người dùng) | client_credentials. | client_credentials kèm tenant=<install_id>; cần scope tenant:connect. |
Cài ứng dụng đối tác vào một tenant
Quản trị viên của đơn vị cài ứng dụng của bạn từ đường dẫn cài đặt do bạn gửi. Bản thân đường dẫn không cài gì: quản trị viên đăng nhập, thấy ứng dụng, nhà phát hành và từng scope bằng lời thường, có thể bỏ chọn scope, rồi chọn Chấp nhận hoặc Từ chối.
state là bắt buộc; redirect_uri phải trùng một địa chỉ bạn đã đăng ký.https://app.stracker.vn/oauth/install
?client_id=YOUR_CLIENT_ID
&scope=trips%3Aread%20tenant%3Aconnect
&redirect_uri=https%3A%2F%2Fexample.com%2Fstracker%2Finstalled
&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN- Khi Chấp nhận, quản trị viên được chuyển về
redirect_uricủa bạn kèminstall_id,statevàiss:https://example.com/stracker/installed?install_id=sti_...&state=...&iss=https%3A%2F%2Fapi.stracker.vn. Hãy giữinstall_id: đó là giá trịtenanttrong yêu cầu token máy-máy của bạn. - Khi Từ chối, đường dẫn chuyển hướng mang
error=access_denied. - Quản trị viên có thể cấp ít scope hơn bạn xin, không bao giờ nhiều hơn những gì ứng dụng đã đăng ký. Bạn có thể gửi lại đường dẫn để xin thêm.
- Người dùng không phải quản trị viên thấy "Nhờ quản trị viên" và yêu cầu được gửi tới các quản trị viên của tenant.
Thử nghiệm mà không chạm dữ liệu thật
Lệnh gọi đầu tiên
- Xin access token bằng client ID và khóa bí mật.
- Gọi API bằng token. Token
client_credentialsmặc định sống 30 phút và không có refresh token: hết hạn thì xin token mới.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope="trips:read routes:read"{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "trips:read routes:read"
}curl -sS "https://api.stracker.vn/v1/trips?limit=5" \
-H "Authorization: Bearer $ACCESS_TOKEN"Đọc tiếp: xác thực cho các luồng khác, danh mục scope, tham chiếu API được sinh tự động, và webhook.