103 lines
3.0 KiB
Markdown
103 lines
3.0 KiB
Markdown
# Merchant AI HTTP API
|
|
|
|
PHP 8.2 JSON API service for merchant order statistics, offline order analysis, and merchant ranking.
|
|
|
|
## Environment
|
|
|
|
Copy `.env.example` to `.env`, then fill your real token:
|
|
|
|
```bash
|
|
MERCHANT_API_TOKEN=your-admin-api-token
|
|
MERCHANT_API_BASE_URI=https://tpoint.agrimedia.cn
|
|
MERCHANT_API_TIMEOUT=60
|
|
OFFLINE_ORDER_PAGE_LIMIT=100
|
|
APP_LOG_ENABLED=true
|
|
APP_LOG_DIR=var/logs
|
|
```
|
|
|
|
`MERCHANT_API_TOKEN` is required. `MERCHANT_API_BASE_URI` and `MERCHANT_API_TIMEOUT` are optional.
|
|
`OFFLINE_ORDER_PAGE_LIMIT` controls each upstream pagination request size.
|
|
`APP_LOG_ENABLED` controls request logging. `APP_LOG_DIR` controls the log directory.
|
|
|
|
Logs are written as JSON lines to `var/logs/app-YYYY-MM-DD.log` by default. Authorization tokens are masked automatically.
|
|
|
|
If the request contains `Authorization: Bearer <token>`, that token is used for the upstream merchant API request first. If the header is missing, `MERCHANT_API_TOKEN` from `.env` is used.
|
|
|
|
## Start Locally
|
|
|
|
```bash
|
|
php -S 127.0.0.1:8080 -t public
|
|
```
|
|
|
|
## Response Format
|
|
|
|
Success:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
Error:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "server_error",
|
|
"message": "error message"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
|
|
### `GET /health`
|
|
|
|
Returns service health status.
|
|
|
|
### `GET /tools`
|
|
|
|
Returns available API tools and input schemas.
|
|
|
|
### `POST /api/order-summary`
|
|
|
|
Returns order count, active merchant count, successful order count, and amount totals.
|
|
|
|
### `POST /api/offline-stats`
|
|
|
|
Returns status, payment type, order type, and amount distribution analysis.
|
|
|
|
### `POST /api/merchant-ranking`
|
|
|
|
Returns merchant ranking by `orderCount`, `successOrderCount`, `totalOrderAmount`, or `totalRealPay`.
|
|
|
|
## Common Parameters
|
|
|
|
- `timePreset`: preferred AI time intent. Supported values: `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_week`, `last_week`, `this_month`, `last_month`, `custom`. Defaults to `today`.
|
|
- `startDate`: custom start date, required when `timePreset=custom`, format `YYYY-MM-DD`.
|
|
- `endDate`: custom end date, required when `timePreset=custom`, format `YYYY-MM-DD`.
|
|
- `date`: legacy compatible date range, for example `2026/06/23-2026/06/23`; if provided, it is sent to the upstream order API as-is.
|
|
- `status`: order status; defaults to `-1` (all). Values: `0` = pending payment, `1` = completed, `2` = cancelled, `3` = pending verification/use, `4` = refunded.
|
|
- `keyword`: search keyword, sent to upstream API as `real_name`.
|
|
- `fieldKey`: upstream `field_key`; defaults to `all`.
|
|
- `payType`: upstream `pay_type`.
|
|
- `type`: upstream order `type`.
|
|
- `btcId`: upstream merchant category ID.
|
|
|
|
`/api/merchant-ranking` also supports:
|
|
|
|
- `sortBy`: `orderCount`, `successOrderCount`, `totalOrderAmount`, or `totalRealPay`; defaults to `totalRealPay`.
|
|
- `limit`: number of merchants to return; defaults to `10`, max `100`.
|
|
|
|
## POST Example
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8080/api/merchant-ranking \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"timePreset":"today","sortBy":"totalRealPay","limit":10}'
|
|
```
|