auv-locker-sdk/README.md

AUV 智能取餐柜 Java SDK

Java SDK for AUV Smart Locker API. Maven + JDK 8 + Apache HttpClient 4.5 + Jackson.

Quick Start

AuvClient client = AuvClient.builder()
    .appId("66666")
    .secretKey("mySecret")
    .build();

// 存取业务 API
CreateOrderResponse resp = client.storage().createOrder(request);

// 辅助功能 API
DeviceStatusResponse status = client.aux().queryDeviceStatus(request);

client.close();

Project Structure

auv-locker-sdk/
├── src/main/java/com/auv/locker/
│   ├── AuvClient.java              # Unified entry point
│   ├── config/
│   │   ├── AuvConfig.java          # Configuration (appId, secretKey, timeouts)
│   │   └── GatewayType.java        # Gateway enum (STORAGE / AUX)
│   ├── http/
│   │   ├── AuvHttpClient.java      # Apache HttpClient wrapper
│   │   └── HmacMD5Util.java        # HmacMD5 signature utility
│   ├── model/
│   │   ├── common/                 # AuvRequest, AuvResponse
│   │   ├── storage/                # Storage API request/response models (11 pairs)
│   │   └── aux/                    # Aux API request/response models
│   └── service/
│       ├── StorageApiService.java  # Storage API interface (11 endpoints)
│       ├── StorageApiServiceImpl.java
│       ├── AuxApiService.java      # Aux API interface (4 endpoints)
│       └── AuxApiServiceImpl.java
└── src/test/java/com/auv/locker/
    ├── HmacMD5UtilTest.java        # Signature tests
    └── AuvClientTest.java          # Builder & config tests

API Overview

Storage API (11 endpoints)

method	Description
createOrder	Create storage order
addCell	Add cell to existing order
cancelOrder	Cancel storage order
createPreOrder	Create pre-order
changePreorderToFormal	Convert pre-order to formal
takeByOrder	Take by order ID
takeByCode	Take by pickup code
reOpenDoor	Re-open door (within 60s of order)
getDeviceInfo	Get device info
getCellList	Get cell list
getOrderList	Query orders (paginated)

Aux API (4 endpoints)

method	Description
device.cell.op	Single cell operation
device.cells.ops	Batch cell operations (Android only)
device.status.query	Query device status & cell details
device.list.query	Paginated device list

Gateway URLs

API	HTTP	HTTPS
Storage	http://plat.58auv.com/OpenApi	https://plat.58auv.com/OpenApi
Aux	http://openapi.58auv.com/gateway.do	https://openapi.58auv.com/gateway.do

Success Codes

• Storage API: code == 10000
• Aux API: code == 1 && success == true

Error Codes

Code	Description
10000 / 1	Success
10010	Missing parameters
10011	bizData parameter error
10012	Device not exists / offline
10013	Order already exists
10014	No available cell
10015	Invalid order
10016	Unsupported operation
10020	Signature error
10021	Duplicate pickup code, use takeByOrder
10027	Please complete previous order first
10029	Non-existent cell
10030	Same request in progress
30002	Cell allocation failed

Signature Algorithm (HmacMD5)

1. Collect all request parameters (except digest)
2. Sort keys by ASCII order, join with & as key=value pairs
3. Compute HmacMD5 with secretKey
4. URL-encode bizData before sending

Notifications (Callbacks)

notifyType	Source	Description
orderCompleted	Storage API	Order completed
orderCancel	Storage API	Order cancelled
cell_status_sync	Aux API	Cell status change
device_status_sync	Aux API	Device online/offline