API Documentation

# iFans API Integration Guide

Below is the iFans API specification. Please write the integration code based on it.

- Base URL: `https://social.ifans.one/social/api`
- Authentication: every request must include the `key` parameter (API key). All responses are JSON; amounts are in New Taiwan Dollars (TWD).
- Method: use GET query strings in general; when creating an order with `comment_msg` (custom comments), use POST (application/x-www-form-urlencoded).
- On error the API returns: {"error_code":"code","error_msg":"message"}

## Endpoints

### 1. Account Balance — `GET https://social.ifans.one/social/api/balance/?key=YOUR_API_KEY`
Success response: `{"balance": "1000.50", "currency": "TWD"}`

### 2. Service List — `GET https://social.ifans.one/social/api/services/?key=YOUR_API_KEY`
Success response: `[{"service": 635, "name": "...", "rate": "0.8", "min": 25, "max": 5000, "multiple": null, "description": "..."}]`
- `service`: Service ID (used when placing orders)
- `name`: Service name
- `rate`: rate is the standard member price per 1 unit (TWD); the actual charge is the charge value in the order response.
- `min` / `max`: Quantity limits
- `multiple`: Multiple constraint (null = no limit)

### 3. Create Order — `GET|POST https://social.ifans.one/social/api/order/`
Parameters:
- `key` (required): API Key
- `service_id` (required): Service ID
- `url` (required): Target URL (URL encode required)
- `amount` (required): Quantity
- `gender` (optional): Gender: male or female. Leave empty for any gender（Only for facebook_tw_rating5 service）
- `autolike_maxpost` (optional): Auto-like - number of posts（Min 5 posts, only for facebook_tw_autolike_custom）
- `autolike_maxcount` (optional): Auto-like - likes per post（Min 25, max 600, only for facebook_tw_autolike_custom）
- `delay` (optional): Delay in minutes (required by some services)
- `comment_msg` (optional, POST): Custom comment content, one per line（Send textarea content directly. The system will parse automatically. Line count must match the amount (blank lines excluded)）
Success response: `{"order_id": 12345, "charge": 40}`
- charge is the amount of credits deducted; when a discount applies, original_price and discount are also returned.
GET: `https://social.ifans.one/social/api/order/?key=YOUR_API_KEY&service_id=635&amount=100&url=https%3A%2F%2Fwww.instagram.com%2Fp%2FXXXX%2F`
POST (comment_msg): `curl -X POST "https://social.ifans.one/social/api/order/" -d "key=YOUR_API_KEY" -d "service_id=SERVICE_ID" -d "amount=2" --data-urlencode "url=https://..." --data-urlencode $'comment_msg=Comment 1\nComment 2'`

### 4. Order Status — `GET https://social.ifans.one/social/api/status/?key=YOUR_API_KEY&id=ORDER_ID`
Response fields:
- `total_price`: Total payment amount
- `amount`: Quantity
- `price`: Service unit price
- `status`: Order status (see below)
- `start_count`: Count before execution
- `count`: Current execution count (or auto-like detected posts)
- `finish_count`: Count after completion
- `screenshot`: Screenshot URL
- `msg`: Order notes
- `expiretime`: Auto-like / post expiry time
- `maxpost` / `maxcount`: Auto-like posts / likes per post (auto-like only)

Order status values (status):
- `pending`: Pending
- `processing`: Processing
- `in progress`: In Progress
- `completed`: Completed
- `partial`: Partially completed (the undelivered part has been refunded)
- `refunded`: Refunded
- `canceled`: Canceled
- `stop`: Paused
- `danger`: Exception

### 5. Batch Order Query — `GET https://social.ifans.one/social/api/orders/?key=YOUR_API_KEY&ids=ID1,ID2,ID3`
Response is an object mapping order IDs to order data. Fields are the same as single order query；Maximum 100 orders per request, separated by commas
Success response: `{"12345": {"status": "completed", "start_count": "100", "count": "50"}, "12346": {"status": "processing"}}`

## Error codes
- `999`: Invalid API KEY
- `998`: Account suspended
- `987`: Unknown action (wrong action name in the URL)
- `500`: Cannot connect to remote server, please try again!
- `600`: Missing required parameters
- `700`: Unknown error, check error_msg for details
- `100`: Invalid service name
- `101`: Exceeds maximum quantity
- `102`: Below minimum quantity
- `103`: Insufficient credits
- `104`: Invalid URL format
- `105`: Invalid URL length
- `106`: Duplicate order - same service/URL already in progress
- `107`: Cannot connect to remote server, please try again!
- `111`: Client-server quantity mismatch (usually when using comment_msg)
- `711`: Minimum 5 posts required (autolike_maxpost)
- `712`: Minimum 25 likes per post required (autolike_maxcount)
- `713`: Maximum 600 likes per post (autolike_maxcount)

## Integration tips
- Call /services/ first to get service, min, max and multiple, and validate quantity range and multiples in your code before ordering.
- URL-encode the url parameter.
- After ordering, poll /status/ no more often than every 5 minutes; for multiple orders use /orders/ (up to 100 IDs, comma-separated).
- Keep the API key on your server only — never put it in front-end code or public repositories.