Ablecity API Reference – 사주·매칭·돌봄 API 문서

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"

> Response:
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
  }'

> Response:
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>"

> Response:
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>"

> Response:
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"
    }
  }'

> Response:
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>"

> Response:
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
  }'

> Response:
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>"

> Response:
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"
  }'

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

4. Error Codes

Error Codes Error Codes

HTTP Status	Code	Description
400	INVALID_REQUEST	잘못된 요청입니다.
401	UNAUTHORIZED	인증 실패 또는 토큰 만료.
404	NOT_FOUND	리소스를 찾을 수 없습니다.
429	RATE_LIMIT	요청 한도 초과입니다.
500	SERVER_ERROR	서버 내부 오류.

5. Rate Limiting

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

6. Support

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