HỆ SINH THÁI Tracera
TÀI LIỆU HƯỚNG DẪN TÍCH HỢP VÀ GIAO TIẾP API (API DOCUMENTATION)
Nền tảng Truy xuất Nguồn gốc Nông nghiệp Minh bạch và Bền vững
Phiên bản: 1.0.0
Lời nói đầu
Tài liệu này được biên soạn bởi đội ngũ phát triển Tracera Solution nhằm cung cấp hướng dẫn chi tiết về cách thức giao tiếp và tích hợp dữ liệu với hệ thống Tracera thông qua giao diện lập trình ứng dụng (RESTful API).
Mục tiêu của tài liệu là giúp các lập trình viên, kỹ sư hệ thống của đối tác (trang trại, hợp tác xã, doanh nghiệp chế biến và logistics) có thể dễ dàng đồng bộ dữ liệu nhật ký canh tác, lô hàng và mã QR truy xuất.
Các nội dung kỹ thuật trong tài liệu được cấu trúc bao gồm: Tổng quan về hệ thống, Cơ chế xác thực, Quy chuẩn trao đổi dữ liệu, và Chi tiết các tiêu chuẩn kỹ thuật số.
I. TỔNG QUAN HỆ THỐNG
1. Mục đích và Phạm vi
Hệ thống API của Tracera cho phép các ứng dụng bên thứ 3 (phần mềm ERP, ứng dụng quản lý nông trại, thiết bị IoT) kết nối trực tiếp để thực hiện các thao tác: tạo mới trang trại, cập nhật mùa vụ, ghi nhận nhật ký canh tác và tạo lô hàng xuất khẩu.
Hỗ trợ đồng bộ hóa dữ liệu theo thời gian thực (Real-time) vào sổ cái hệ thống trang trại tập trung, đảm bảo tính minh bạch từ nông trại đến phân phối.
2. Đối tượng sử dụng
Nhà phát triển phần mềm (Developers) thực hiện tích hợp hệ thống.
Các chủ trang trại (Owners) và Ban quản lý sử dụng giải pháp phần mềm nông nghiệp nội bộ muốn liên kết lên Tracera.
Kỹ sư IoT cài đặt thiết bị cảm biến môi trường tại nông trại.
3. Môi trường tích hợp
Môi trường Thử nghiệm (Sandbox): https://sandbox-api.viettrace.com/v1
Môi trường Thực tế (Production): https://api.viettrace.com/v1
Khuyến nghị tất cả các đối tác sử dụng môi trường Sandbox để kiểm thử toàn vẹn logic trước khi thực thi lệnh trên môi trường Production.
4. Giải thích thuật ngữ
4.1. Farm (Trang trại)
Đơn vị tổ chức quản lý đất đai và tài nguyên canh tác quy mô lớn nhất trong một tài khoản Tenant.
4.2. Crop (Mùa vụ)
Một chu kỳ canh tác cụ thể của một nhóm giống cây trồng trên một vùng diện tích (Zone/Plot) xác định.
4.3. Activity (Nhật ký canh tác)
Các công việc diễn ra hàng ngày (tạo luống, gieo hạt, bón phân, tưới nước, thu hoạch, đóng gói) được ghi nhận và liên kết số.
4.4. Traceability QR
Mã phản hồi nhanh (2D) đại diện cho một lô thành phẩm, cho phép tra cứu toàn bộ lịch sử vòng đời của nông sản.
5. Chữ viết tắt
| Chữ viết tắt | Giải thích |
|---|---|
| API | Giao diện lập trình ứng dụng (Application Programming Interface) |
| REST | Chuyển giao trạng thái đại diện (Representational State Transfer) |
| JWT | Chữ ký web JSON để xác thực (JSON Web Token) |
| QR | Mã phản hồi nhanh (Quick Response Code) |
| IoT | Internet vạn vật (Internet of Things) |
| JSON | Ngôn ngữ mô tả đối tượng dữ liệu (JavaScript Object Notation) |
| ERP | Hệ thống hoạch định tài nguyên doanh nghiệp (Enterprise Resource Planning) |
II. QUY ĐỊNH KỸ THUẬT VÀ BẢO MẬT
1. Cơ chế xác thực (Authentication)
Toàn bộ các Endpoints API của Tracera yêu cầu xác thực bằng phương thức Bearer Token (Sử dụng chuẩn JWT).
API Key hoặc Token có thể được khởi tạo tại mục Cài đặt Developer trong giao diện Dashboard của quyền Owner.
Cách truyền Header: `Authorization: Bearer <your_access_token>`
2. Định dạng dữ liệu trao đổi
2.1. Request & Response Payload
Hệ thống chuẩn hóa sử dụng duy nhất định dạng JSON với Header `Content-Type: application/json` cho mọi Request Body và Response Data.
2.2. Mã phản hồi (HTTP Status Codes)
• 200 OK: Xử lý thành công
• 400 Bad Request: Dữ liệu gửi lên sai định dạng hoặc thiếu trường bắt buộc
• 401 Unauthorized: Token không hợp lệ hoặc đã hết hạn
• 403 Forbidden: Không có quyền truy cập dữ liệu trang trại này
• 500 Internal Server Error: Có lỗi hệ thống Tracera
3. Giới hạn truy cập (Rate Limiting)
Để đảm bảo hiệu năng và sự ổn định của hệ thống chia sẻ, lưu lượng API bị giới hạn mặc định ở mức 100 requests/phút trên mỗi API Key.
Hệ thống sẽ trả về mã lỗi `429 Too Many Requests` khi các yêu cầu vượt quá hạn mức cho phép.