🔗 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

사용자의 생년월일·출생 시각(birth), 성별(gender), (선택) 태어난 도시(city)를 기반으로 만세력(사주팔자)과 오행·격국·용신·대운 및 행운 요소를 계산합니다.

요청 예시

curl -X GET \
  "https://api.ablecity.kr/api/v1/saju/fortune?birth=1990-01-01T01:00:00&gender=male&city=강릉시" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

Query Parameters

성공 응답 예시

HTTP/1.1 200 OK
{
  "status": "success",
  "message": "요청이 완료되었습니다.",
  "data": {
    "year": {
      "branch_sipseong": "정재",
      "stem_sipseong": "정인",
      "hangul": "무인",
      "hanja": "戊寅"
    },
    "month": {
      "branch_sipseong": "정재",
      "stem_sipseong": "정재",
      "hangul": "갑인",
      "hanja": "甲寅"
    },
    "day": {
      "branch_sipseong": "상관",
      "stem_sipseong": "비견",
      "hangul": "신해",
      "hanja": "辛亥"
    },
    "hour": {
      "branch_sipseong": "식신",
      "stem_sipseong": "정인",
      "hangul": "무자",
      "hanja": "戊子"
    },
    "fortune": 9,
    "five": {
      "earth": 2.59,
      "metal": 0.97,
      "fire": 0.66,
      "wood": 6.14,
      "water": 2.90
    },
    "five_pct": {
      "earth": 19.5,
      "metal": 7.3,
      "fire": 5.0,
      "wood": 46.3,
      "water": 21.9
    },
    "five_star": {
      "earth": "★★☆☆☆",
      "metal": "★☆☆☆☆",
      "fire": "★☆☆☆☆",
      "wood": "★★★★★",
      "water": "★★★☆☆"
    },
    "five_kor": {
      "금(金)": 0.97,
      "목(木)": 6.14,
      "토(土)": 2.59,
      "화(火)": 0.66,
      "수(水)": 2.90
    },
    "twelve_growth": {
      "year": "胎",
      "month": "胎",
      "day": "沐浴",
      "hour": "長生"
    },
    "twelve_growth_kor": {
      "year": "태",
      "month": "태",
      "day": "목욕",
      "hour": "장생"
    },
    "strength": "weak",
    "geokguk": {
      "geok_kor": "종재격",
      "geok": "從財格",
      "share": 50.0,
      "category_counts": {
        "인성": 2,
        "관성": 0,
        "비겁": 1,
        "식상": 2,
        "재성": 5
      },
      "is_follower": true
    },
    "yongshin": {
      "primary": "fire",
      "primary_kor": "화(火)",
      "secondary": "earth",
      "secondary_kor": "토(土)"
    },
    "branch_relations": {
      "harmonies": ["寅-亥", "寅-亥"],
      "breaks": [],
      "three_harmonies": [],
      "punishments": [],
      "harms": [],
      "clashes": []
    },
    "branch_relations_kor": {
      "harmonies": ["인-해", "인-해"],
      "breaks": [],
      "three_harmonies": [],
      "punishments": [],
      "harms": [],
      "clashes": []
    },
    "big_luck": [
      { "age_range": "9–18",  "year_range": "2007–2016", "pillar": "癸丑", "pillar_kor": "계축" },
      { "age_range": "19–28", "year_range": "2017–2026", "pillar": "壬子", "pillar_kor": "임자" },
      { "age_range": "29–38", "year_range": "2027–2036", "pillar": "辛亥", "pillar_kor": "신해" },
      { "age_range": "39–48", "year_range": "2037–2046", "pillar": "庚戌", "pillar_kor": "경술" }
    ],
    "lucky": {
      "good_num": 2,
      "bad_num": 7,
      "good_dir": "서쪽",
      "bad_dir": "동쪽",
      "need_elem_kor": "화(火)",
      "need_elem": "fire",
      "good_colors": ["bg-red-300", "bg-orange-300"],
      "bad_color": "bg-gray-300"
    }
  }
}

주요 필드 설명

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

4.1 공통 message 값

• 요청이 완료되었습니다. – 성공 처리.
• 서버 처리 중 오류가 발생했습니다. – 서버 내부 오류. 서버 로그 확인 필요.
• 서비스를 찾을 수 없습니다. – 지원하지 않는 서비스(URL)를 호출한 경우.

4.2 인증 / Rate Limit 관련 message

• 유효하지 않은 API Key입니다. – API Key가 삭제(비활성화)되었거나 만료되었거나, 요청 헤더에 존재하지 않을 때.
• 허용된 전체 분당 요청 횟수가 초과되었습니다. – API Key에 할당된 1분당 전체 요청 횟수를 초과.
• 허용된 전체 일일 요청 횟수가 초과되었습니다. – API Key에 할당된 일일 전체 요청 횟수를 초과.
• 해당 서비스에 허용된 분당 요청 횟수가 초과되었습니다. – 특정 서비스(예: 만세력 조회)에 할당된 분당 요청 횟수를 초과.
• 해당 서비스에 허용된 일일 요청 횟수가 초과되었습니다. – 특정 서비스에 할당된 일일 요청 횟수를 초과.
• 허용되지 않은 서비스입니다. – 요청한 서비스(URI)가 해당 API Key에 할당되지 않았거나, 비활성/만료 상태일 때.
• 서비스가 일시적으로 불안정합니다. 잠시 후 다시 시도해주세요. – Redis 등 내부 요청 횟수 관리 중 일시적인 오류가 발생했을 때.

4.3 사주 API(/api/v1/saju/fortune) 전용 message

• invalid birth date format – birth 형식 오류. yyyy-MM-dd HH:mm:ss 형식만 허용됩니다.
• gender must be 'male' or 'female' – gender 값이 male 또는 female이 아닐 때.
• invalid timezone – 태어난 지역 시간대 오류. 과거 버전에서 timezone 파라미터를 사용할 때 반환될 수 있으며, IANA tz 데이터베이스 (예: tz database) 기준으로 검증됩니다.

5. Rate Limiting

모든 엔드포인트는 기본적으로 API Key 기준 분당 60 건, 하루 50,000 건으로 제한됩니다. 서비스별 혹은 전체 한도를 초과하면 HTTP 429(RATE_LIMIT)와 함께 상기 Rate Limit 관련 message가 반환됩니다. 필요 시 고객센터를 통해 상향을 요청할 수 있습니다.

6. Support

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