🔗 Ablecity API Reference

1. Authentication

모든 API 요청에는 HTTP Header에 Bearer Token을 포함해야 합니다.

Authorization: Bearer <API_KEY>

발급된 API 키는 고객센터를 통해 신청하실 수 있습니다.

2. 공통 응답 형식

{
  "status": "success",   // or "error"
  "data": ... ,          // 결과 데이터
  "message": "..."       // 설명 메시지
}

3. Endpoints

3.1 GET /api/v1/saju/fortune

사용자의 생년월일, 성별, 시간대를 기반으로 정밀한 사주 운세 결과를 조회합니다.

curl -X GET \
  "https://api.ablecity.kr/v1/saju/fortune?birth=1990-01-01&gender=male&timezone=Asia/Seoul" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "zodiac": "양",
    "lunarBirth": "1989-12-20",
    "fortune": {
      "overall": "오늘은 도전이 필요한 날입니다.",
      "career": "새로운 프로젝트에서 주목받을 기회가 있습니다.",
      "love": "솔로라면 만남 운이 좋고, 커플은 소통을 강화하세요.",
      "health": "가벼운 운동으로 컨디션을 유지하세요."
    },
    "luckyNumbers": [5, 12, 29],
    "compatibleSigns": ["용", "원숭이"],
    "generatedAt": "2025-05-10T10:00:00+09:00"
  }
}

3.2 POST /api/v1/matching

소개팅·결혼중개 매칭 요청을 생성하며, 사용자의 선호도와 위치 기반 필터링을 지원합니다.

curl -X POST https://api.ablecity.kr/v1/matching \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "USER123",
    "preferences": {
      "ageRange": [25, 35],
      "interests": ["travel", "music"],
      "location": { "lat": 37.5665, "lng": 126.9780, "radiusKm": 30 }
    },
    "maxResults": 10
  }'

HTTP/1.1 201 Created
{
  "status": "success",
  "data": {
    "requestId": "REQ-67890",
    "status": "processing",
    "submittedAt": "2025-05-10T11:00:00+09:00"
  }
}

3.3 GET /api/v1/matching/{requestId}/results

매칭 진행 상황과 결과 리스트를 페이징 옵션과 함께 조회합니다.

curl -X GET \
  "https://api.ablecity.kr/v1/matching/REQ-67890/results?limit=5&offset=0" \
  -H "Authorization: Bearer <API_KEY>"

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "requestId": "REQ-67890",
    "status": "completed",
    "results": [
      {
        "matchId": "MCH-001",
        "name": "홍길동",
        "age": 29,
        "distanceKm": 3.5,
        "commonInterests": ["travel", "cooking"],
        "matchScore": 0.92,
        "profileImage": "https://ablecity.kr/images/users/hong.jpg"
      },
      {
        "matchId": "MCH-002",
        "name": "김미영",
        "age": 32,
        "distanceKm": 5.8,
        "commonInterests": ["music", "art"],
        "matchScore": 0.88,
        "profileImage": "https://ablecity.kr/images/users/kim.jpg"
      }
    ],
    "totalResults": 8
  }
}

3.4 GET /api/v1/tutoring/availability

과외·돌봄 서비스 제공자의 예약 가능 시간대를 조회합니다.

curl -X GET \
  "https://api.ablecity.kr/v1/tutoring/availability?date=2025-06-15&serviceType=care" \
  -H "Authorization: Bearer <API_KEY>"

HTTP/1.1 200 OK
{
  "status": "success",
  "data": [
    {
      "slotId": "SLT-001",
      "start": "2025-06-15T09:00:00+09:00",
      "end":   "2025-06-15T10:00:00+09:00",
      "price": 35000
    },
    {
      "slotId": "SLT-002",
      "start": "2025-06-15T14:00:00+09:00",
      "end":   "2025-06-15T15:30:00+09:00",
      "price": 50000
    }
  ]
}

3.5 POST /api/v1/tutoring/book

선택한 시간대로 과외·돌봄 서비스를 예약하고 결제 정보를 반환합니다.

curl -X POST https://api.ablecity.kr/v1/tutoring/book \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId":       "USER123",
    "slotId":       "SLT-001",
    "paymentMethod":"card",
    "cardInfo": {
      "cardNumber": "4111111111111111",
      "expiry":     "12/25",
      "cvc":        "123"
    }
  }'

HTTP/1.1 201 Created
{
  "status": "success",
  "data": {
    "bookingId":       "BOOK-34567",
    "status":          "confirmed",
    "paidAmount":      35000,
    "confirmationUrl": "https://ablecity.kr/booking/BOOK-34567"
  }
}

3.6 GET /api/v1/otc/listings

거래 가능한 OTC 리스팅을 조회하며, 자산 유형, 최소 수량 필터를 지원합니다.

curl -X GET \
  "https://api.ablecity.kr/v1/otc/listings?assetType=BTC&minQuantity=0.5" \
  -H "Authorization: Bearer <API_KEY>"

HTTP/1.1 200 OK
{
  "status": "success",
  "data": [
    {
      "listingId":    "LST-1001",
      "assetType":    "BTC",
      "quantity":     1.2,
      "pricePerUnit": 50000000,
      "totalPrice":   60000000,
      "sellerId":     "TraderA",
      "escrowStatus": "pending"
    }
  ]
}

3.7 POST /api/v1/otc/order

선택한 리스팅으로 OTC 거래 주문을 생성하고 에스크로 주소를 반환합니다.

curl -X POST https://api.ablecity.kr/v1/otc/order \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "listingId": "LST-1001",
    "buyerId":   "USER456",
    "quantity":  0.8
  }'

HTTP/1.1 201 Created
{
  "status": "success",
  "data": {
    "orderId":       "ORD-2002",
    "escrowAddress": "0xabcd1234ef567890...",
    "expiresAt":     "2025-05-10T12:00:00+09:00"
  }
}

3.8 GET /api/v1/rental/assets

렌탈 가능한 자산 목록을 조회하며, 카테고리 및 위치 필터를 지원합니다.

curl -X GET \
  "https://api.ablecity.kr/v1/rental/assets?category=camera&lat=37.5665&lng=126.9780&radiusKm=10" \
  -H "Authorization: Bearer <API_KEY>"

HTTP/1.1 200 OK
{
  "status": "success",
  "data": [
    {
      "assetId":           "ASSET-3001",
      "name":              "Canon EOS R5",
      "category":          "camera",
      "location": { "lat": 37.5665, "lng": 126.9780 },
      "hourlyRate":        15000,
      "availabilityCount": 3
    }
  ]
}

3.9 POST /api/v1/rental/reserve

선택한 자산을 예약하고 예약 정보를 반환합니다.

curl -X POST https://api.ablecity.kr/v1/rental/reserve \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId":    "USER123",
    "assetId":   "ASSET-3001",
    "startTime": "2025-06-20T09:00:00+09:00",
    "endTime":   "2025-06-20T17:00:00+09:00"
  }'

HTTP/1.1 201 Created
{
  "status": "success",
  "data": {
    "reservationId":   "RES-4003",
    "totalCost":       120000,
    "confirmationUrl": "https://ablecity.kr/reservations/RES-4003"
  }
}

4. Error Codes

5. Rate Limiting

모든 엔드포인트는 분당 60개의 요청으로 제한됩니다. 초과 시 429 오류를 반환합니다.

6. Support

추가 도움말은 [email protected] 로 문의해 주세요.