Ablecity
2026.04.09 v2.7 Updated

Ablecity 만세력 API Reference

만세력 API와 사주 API를 앱·웹 서비스에 연동하기 위한 개발 문서입니다.
인증, 요청 파라미터, JSON 응답, 신살 옵션, 비동기 분석, 오류 코드와 테스트 키 신청 방법을 확인하세요.

200+

Global Partners

Dec 2025

Since Launch

0건

Critical Errors

Live

SSEHADA Engine

내부 운영·테스트키 발급·파트너 환경 기준으로 Ablecity API는 2025년 12월 출시 이후 API 레벨 무중단 운영을 이어가고 있습니다. 정식 SLA는 계약 범위에 따라 별도 정의하며, 문서에는 연동에 필요한 요청·응답 계약만 공개합니다.

만세력 & 신살 API v2 연동 기준

  • 현재 문서는 v2 전용 기준으로 안내합니다.
  • 모든 신규 테스트키와 정식키는 /api/v2/... 경로 기준으로 발급됩니다.
  • 비동기 분석 계열은 POST 요청 후 X-Callback-URL로 결과를 전달받습니다.
  • 궁합(2인)처럼 입력 구조가 다른 API는 별도 예제를 먼저 확인해 주세요.

Quick Start

5분 안에 첫 호출 성공하기

Ablecity 사주 API는 v2 전용 문서 기준으로 연동합니다. 먼저 API 키를 준비하고, 동기 GET 호출과 비동기 POST+Callback 호출의 차이를 확인하세요.

궁합 예제 바로가기

1. API 키 준비

모든 요청은 Authorization: Bearer <API_KEY> 헤더를 사용합니다.

키를 받은 뒤에는 API Dashboard에서 회원가입 후 사용량, 구독, API 조회를 확인할 수 있습니다.

2. 단일 조회는 GET

기본 만세력 조회는 호출 즉시 JSON 결과를 반환합니다.

3. 심화 분석은 POST + Callback

궁합, 작명, 재물운 등은 요청 접수 후 callback URL로 최종 결과를 전송합니다.

기본 만세력 조회 예시

curl -X GET \
  "https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male&city=서울특별시&calendar=solar&midnightType=0" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

1. Authentication

모든 API 요청에는 HTTP Header에 Bearer Token을 포함해야 합니다. API 키는 서버 측에서 관리하고, 클라이언트 앱에 직접 노출하지 않는 것을 기본 원칙으로 둡니다.

Authorization: Bearer <API_KEY>

API 키는 상단의 API 키 발급 신청 버튼을 통해 신청하실 수 있습니다.

Operations

Ablecity 만세력 API는 단순 계산 결과만 반환하는 구조가 아니라, 실제 서비스 연동에 필요한 인증, 사용량, 요금제, 모니터링 범위를 함께 고려합니다. 운영 기준은 트래픽 규모와 계약 범위에 맞춰 별도 검증합니다.

운영 항목 기본 확인 기준 Ablecity 문서/상담 기준
응답 구조 HTML 또는 단문 텍스트 혼재 REST JSON 응답 기준
사용량 관리 키 단위 집계 미흡 키별 요청량·월별 사용량 기준
도메인 필드 결과 문구 위주 사주표, 오행, 신살, 공망 등 구조화 필드
연동 방식 동기 호출만 지원 동기 GET + 비동기 POST/Callback 구분
운영 지원 일반 문의 대응 계약 범위에 따른 SLA 옵션 제공

2. 공통 응답 형식

모든 endpoint는 성공과 오류를 같은 top-level JSON envelope로 반환합니다. 클라이언트에서는 status, data, message를 기준으로 일관되게 처리하면 됩니다.

{
  "status": "success",
  "data": ...,
  "message": "..."
}

3. Endpoints

신규 테스트키와 정식키는 v2 endpoint 기준으로 발급됩니다. 단일 조회는 GET, 분석형 요청은 POST + callback 구조를 사용합니다.

3.1 GET /api/v2/saju/fortune

Current Standard

사용자의 생년월일·출생 시각(birth), 성별(gender), (선택) 태어난 도시(city), 자정 처리 방식, 사용 달력을 기반으로 만세력(사주팔자), 오행, 격국, 용신, 대운, 띠 궁합, 공망, 신살까지 v2 기준으로 계산합니다.

v2 사용 기준

  • 신규 테스트키/정식키는 모두 GET /api/v2/saju/fortune 기준으로 제공됩니다.
  • 현재 문서는 v2 기준으로만 요청 경로, 파라미터, 응답 예시를 안내합니다.
  • 응답은 status, message, data 구조를 그대로 유지하므로 기존 JSON 처리 패턴을 재사용하기 쉽습니다.

신살(SIS) 옵션 안내

  • 기본 만세력 조회는 신살(SIS)을 제외하고 반환합니다.
  • SIS(신살) 포함은 API 키 발급 신청 시 별도 신청/승인이 필요합니다. 승인된 API Key에는 sinsal, relations_ui, gongmang 등이 포함됩니다.
  • v2 문서에는 실제 서비스에서 활용하는 공개 필드만 안내합니다. 엔진 내부 디버그용 필드는 문서에서 제외했습니다.
curl -X GET \
          "https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male" \
          -H "Authorization: Bearer <API_KEY>" \
          -H "Accept: application/json"

* midnightType(0:야자/조자 분리)과 calendar(solar:양력)는 미입력 시 기본값으로 처리됩니다.

Query Parameters

Name Type Required Description
birth string Yes 태어난 시간. yyyy-MM-ddTHH:mm:ss 형식만 지원합니다. (날짜와 시간 사이 대문자 T)
gender string Yes 성별. 남자: male, 여자: female (그 외 값 오류)
city string Optional 태어난 도시 (LMT 보정용). 미입력 시 서울특별시 기준.
지원 도시는 아래 목록 참고.
midnightType integer Optional 0: 야자/조자 분리 (기본값)
1: 정자시 방식 (23:00~00:59를 모두 익일로 처리)
calendar string Optional solar(양력, 기본값), lunar(음력), leap(윤달)
📍 사주 API 지원 도시 목록 (city) 전체 보기

표기 예: city=서울특별시

서울특별시 부산광역시 대구광역시 인천광역시 광주광역시 대전광역시 울산광역시 세종특별자치시 수원시 고양시 용인시 성남시 부천시 안산시 화성시 남양주시 안양시 평택시 의정부시 파주시 시흥시 김포시 광명시 광주시(경기) 군포시 이천시 오산시 하남시 양주시 구리시 안성시 포천시 의왕시 여주시 동두천시 과천시 가평군 양평군 연천군 춘천시 원주시 강릉시 동해시 태백시 속초시 삼척시 홍천군 횡성군 영월군 평창군 정선군 철원군 화천군 양구군 인제군 고성군(강원) 양양군 청주시 충주시 제천시 보은군 옥천군 영동군 증평군 진천군 괴산군 음성군 단양군 천안시 공주시 보령시 아산시 서산시 논산시 계룡시 당진시 금산군 부여군 서천군 청양군 홍성군 예산군 태안군 전주시 군산시 익산시 정읍시 남원시 김제시 완주군 진안군 무주군 장수군 임실군 순창군 고창군 부안군 목포시 여수시 순천시 나주시 광양시 담양군 곡성군 구례군 고흥군 보성군 화순군 장흥군 강진군 해남군 영암군 무안군 함평군 영광군 장성군 완도군 진도군 신안군 포항시 경주시 김천시 안동시 구미시 영주시 영천시 상주시 문경시 경산시 의성군 청송군 영양군 영덕군 청도군 고령군 성주군 칠곡군 예천군 봉화군 울진군 울릉군 독도 창원시 진주시 통영시 사천시 김해시 밀양시 거제시 양산시 의령군 함안군 창녕군 고성군(경남) 남해군 하동군 산청군 함양군 거창군 합천군 제주시 서귀포시 기장군 달성군 군위군 울주군 강화군 옹진군

Response Example

{
  "status": "success",
  "message": "요청이 완료되었습니다.",
  "data": {
    "year": {
      "branch_element": "earth",
      "branch_polarity": "yang",
      "branch_sipseong": "정인",
      "stem_polarity": "yang",
      "stem_sipseong": "정인",
      "hangul": "무진",
      "hanja": "戊辰",
      "stem_element": "earth"
    },
    "month": {
      "branch_element": "water",
      "branch_polarity": "yang",
      "branch_sipseong": "식신",
      "stem_polarity": "yang",
      "stem_sipseong": "정재",
      "hangul": "갑자",
      "hanja": "甲子",
      "stem_element": "wood"
    },
    "day": {
      "branch_element": "earth",
      "branch_polarity": "yin",
      "branch_sipseong": "편인",
      "stem_polarity": "yin",
      "stem_sipseong": "비견",
      "hangul": "신축",
      "hanja": "辛丑",
      "stem_element": "metal"
    },
    "hour": {
      "branch_element": "water",
      "branch_polarity": "yang",
      "branch_sipseong": "식신",
      "stem_polarity": "yang",
      "stem_sipseong": "정인",
      "hangul": "무자",
      "hanja": "戊子",
      "stem_element": "earth"
    },
    "fortune": 8,
    "hehua": {
      "effective": [],
      "failed": [],
      "applied_true": false,
      "applied_pseudo": false,
      "applied_any": false,
      "applied": false,
      "five_before_pct": {
        "earth": 32.8,
        "metal": 11,
        "fire": 0,
        "wood": 12.6,
        "water": 43.6
      },
      "five_after_pct": {
        "earth": 32.8,
        "metal": 11,
        "fire": 0,
        "wood": 12.6,
        "water": 43.6
      },
      "five_changed": false,
      "strength_before": "balanced",
      "strength_after": "balanced",
      "strength_changed": false,
      "yongshin_changed": false
    },
    "five_pct": {
      "earth": 32.8,
      "metal": 11,
      "fire": 0,
      "wood": 12.6,
      "water": 43.6
    },
    "five_star": {
      "earth": "★★★★☆",
      "metal": "★☆☆☆☆",
      "fire": "★☆☆☆☆",
      "wood": "★☆☆☆☆",
      "water": "★★★★★"
    },
    "five_kor": {
      "목(木)": 1.3,
      "금(金)": 1.13,
      "토(土)": 3.38,
      "화(火)": 0,
      "수(水)": 4.49
    },
    "twelve_growth": { "month": "長生", "hour": "長生", "year": "墓", "day": "養" },
    "twelve_growth_kor": { "month": "장생", "hour": "장생", "year": "묘", "day": "양" },
    "strength": "balanced",
    "geokguk": {
      "geok": "식신격",
      "geok_kor": "식신격",
      "geok_detail": null,
      "is_follower": false,
      "follower_candidate": false,
      "variant_signal": false
    },
    "yongshin": {
      "primary": "fire",
      "primary_kor": "화(火)",
      "secondary": "earth",
      "secondary_kor": "토(土)"
    },
    "branch_relations": {
      "harmonies": ["子-丑", "丑-子"],
      "breaks": ["辰-丑"],
      "clashes": [],
      "punishments": [],
      "harms": [],
      "wonjins": [],
      "half_three_harmonies": ["子-辰"]
    },
    "branch_relations_kor": {
      "harmonies": ["자-축", "축-자"],
      "breaks": ["진-축"],
      "clashes": [],
      "punishments": [],
      "harms": [],
      "wonjins": [],
      "half_three_harmonies": ["자-진"]
    },
    "relations_ui": {
      "summary": {
        "harmony_count": 2,
        "tension_count": 2,
        "special_count": 1,
        "top_alert": "공망"
      },
      "items": [
        {
          "key": "branch_harmony",
          "label": "지지육합",
          "group": "harmony",
          "tone": "good",
          "count": 2,
          "tokens": ["子-丑 (자-축)", "丑-子 (축-자)"]
        },
        {
          "key": "gongmang",
          "label": "공망",
          "group": "tension",
          "tone": "warn",
          "count": 2,
          "tokens": ["공망지 辰巳 (진사)", "원국 포함 辰 (진)"]
        }
      ],
      "gongmang": {
        "day_pillar": "辛丑",
        "xun_start": "甲午",
        "void_branches": ["辰", "巳"],
        "void_branches_kor": ["진", "사"],
        "present_branches": ["辰"],
        "present_branches_kor": ["진"]
      }
    },
    "big_luck": [
      { "age_range": "8–17", "year_range": "1996–2005", "pillar": "乙丑", "pillar_kor": "을축" },
      { "age_range": "18–27", "year_range": "2006–2015", "pillar": "丙寅", "pillar_kor": "병인" },
      { "age_range": "28–37", "year_range": "2016–2025", "pillar": "丁卯", "pillar_kor": "정묘" }
    ],
    "first_big_luck": "을축",
    "lucky": {
      "good_num": 2,
      "bad_num": 7,
      "good_dir": "서쪽",
      "bad_dir": "동쪽",
      "need_elem": "fire",
      "need_elem_kor": "화(火)"
    },
    "summary": {
      "pillars": "무진년 갑자월 신축일 무자시",
      "strength": "중화(中和)",
      "zodiac": "용띠"
    },
    "zodiac_compatibility": [
      {
        "score": 95,
        "grade": "best",
        "animal": "쥐",
        "branch": "子",
        "relation": "삼합(三合)",
        "desc": "서로 부족한 점을 채워주는 최상의 궁합입니다."
      },
      {
        "score": 20,
        "grade": "bad",
        "animal": "개",
        "branch": "戌",
        "relation": "충(沖)",
        "desc": "서로 부딪히는 기운으로, 갈등에 주의가 필요합니다."
      }
    ],
    "sinsal": [
      {
        "sis_code": "S005",
        "name_kr": "공망",
        "name_en": "The Void (Null State)",
        "chart_vector": {
          "creativity": 100,
          "material_luck": 79,
          "reality_grip": 74,
          "reversal_potential": 95,
          "spiritual_depth": 100
        },
        "attributes": {
          "affected_element": "재성 (Wealth)",
          "void_type": "진사공망 (Dragon/Snake Void)",
          "positions": ["year"],
          "manifest_label": "년주(태어난 해)",
          "resolved_by_combine": true
        },
        "final_verdict": {
          "grade": "S_ACTIVE",
          "keyword": "채워질 준비가 된 그릇",
          "description": "공망이 합 작용으로 해공된 상태입니다.",
          "advice": "협업과 관계 조정을 활용해 공백 리스크를 줄이는 편이 좋습니다."
        },
        "beginner_explanation": "공망이 합 작용으로 해공된 상태이며, 급격한 붕괴보다 완충 흐름이 우세합니다.",
        "is_present": true
      }
    ],
    "gongmang": {
      "sinsals": [
        {
          "name": "공망",
          "score": 6,
          "desc": "[수(水)]비움과 채움의 미학. 해당 궁위의 결핍.",
          "relatedChar": "辰",
          "positions": ["YEAR"],
          "is_present": true
        }
      ],
      "present_branches": ["辰"],
      "hanja": ["辰", "巳"],
      "hangul": ["진", "사"]
    }
  }
}

처음 쓰는 개발자를 위한 읽는 순서

  1. data.summary부터 읽으면 사람이 바로 이해할 수 있는 핵심 요약을 먼저 보여줄 수 있습니다.
  2. data.year / month / day / hour는 사주 원국 4기둥입니다. 표나 카드 UI를 만들 때 가장 먼저 매핑하는 필드입니다.
  3. data.five_pctdata.five_star는 오행 밸런스를 시각화하기 가장 좋습니다. 차트, 막대그래프, 배지 UI에 바로 활용할 수 있습니다.
  4. data.yongshin, data.strength, data.geokguk은 해석형 서비스의 핵심 요약 변수입니다.
  5. data.big_luckdata.lucky는 대운 타임라인, 추천 방향/숫자 같은 부가 UI에 적합합니다.
  6. data.sinsal, data.relations_ui, data.gongmang는 신살 옵션 승인 시 활용하는 심화 데이터입니다.

주요 필드 설명

사주 기둥 (year, month, day, hour)

hangul, hanja, 천간/지지 오행, 음양, 십성 정보가 함께 들어갑니다. 사주표를 그릴 때 가장 기본이 되는 필드입니다.

운세 점수 (fortune)

전체 흐름을 빠르게 요약하는 숫자입니다. 목록형 카드나 간단한 요약 배지에 붙이기 좋습니다.

오행 분포 (five_pct, five_star, five_kor)

퍼센트, 별점, 한글 키 버전을 함께 제공합니다. 차트나 설명문을 만들 때 원하는 형태로 바로 사용할 수 있습니다.

합화 분석 (hehua)

합화가 실제로 적용됐는지, 적용 전후 오행 비율과 강약이 바뀌었는지를 확인하는 영역입니다.

강약 / 격국 / 용신

strength, geokguk, yongshin은 해석형 콘텐츠를 만들 때 가장 많이 참조하는 핵심 변수입니다.

지지 관계 (branch_relations, relations_ui)

합·충·형·해·파 같은 관계를 원본 배열과 UI 친화 요약 두 가지 방식으로 제공합니다.

대운 / 행운 정보

big_luck, first_big_luck, lucky는 타임라인, 추천 방향, 숫자 UI를 구성할 때 유용합니다.

신살 / 공망 / 띠 궁합

sinsal, gongmang, zodiac_compatibility는 해석 콘텐츠와 관계형 기능을 확장할 때 바로 활용할 수 있습니다.

v2 주요 필드 상세

Field Type Description
year / month / day / hour Object 각 기둥의 간지, 오행, 음양, 십성 정보입니다. 사주 원국 UI의 기본 데이터입니다.
fortune Number 현재 만세력 종합 점수입니다. 정렬, 추천, 간단한 등급 표시용으로 쓰기 좋습니다.
hehua Object effective, failed, applied*, five_before_pct, five_after_pct 등으로 합화 적용 결과를 보여줍니다.
five_pct / five_star / five_kor Object 오행 비율, 별점, 한글 표기 버전입니다. 숫자 UI와 설명 텍스트를 함께 만들기 좋습니다.
twelve_growth / twelve_growth_kor Object 십이운성 정보입니다. 한자/한글 버전이 모두 제공돼 표기 방식 선택이 쉽습니다.
strength String 일간 강약을 요약한 값입니다. 예: balanced, weak, strong.
geokguk Object geok, geok_kor, geok_detail, follower_candidate 등 격국 요약을 담습니다.
yongshin Object 보완이 필요한 핵심 오행입니다. 추천 컬러, 방향, 콘텐츠 추천 로직과 연결하기 쉽습니다.
branch_relations / branch_relations_kor Object 합·충·형·해·파·원진 등 관계를 원본 표기와 한글 표기로 함께 반환합니다.
relations_ui Object 관계 신호를 화면에 바로 쓰기 쉬운 형태로 정리한 객체입니다. (SIS 옵션)
big_luck / first_big_luck Array / String 10년 단위 대운 흐름과 첫 대운 정보를 제공합니다. 타임라인 카드 구성에 적합합니다.
lucky Object 행운 숫자, 방향, 보완 오행 등 부가 추천 정보를 제공합니다.
summary Object 사람에게 바로 보여주기 좋은 요약 필드입니다. 카드 상단 제목용으로 가장 먼저 쓰기 좋습니다.
zodiac_compatibility Array<Object> 본인 띠 기준 12지신 궁합 데이터입니다. 띠궁합 콘텐츠와 관계형 운세 콘텐츠에 활용할 수 있습니다.
sinsal Array<Object> sis_code, chart_vector, attributes, final_verdict, beginner_explanation를 포함한 신살 상세 데이터입니다. (SIS 옵션)
gongmang Object 공망지 한자/한글 목록과 관련 신살 요약을 제공합니다. 공망 특화 UI에 바로 사용할 수 있습니다. (SIS 옵션)
지원하는 신살 전체 목록 (56종) Enum Reference

Ablecity 사주 API는 국내 최다 수준인 56종의 신살을 정밀 분석합니다.
응답 데이터는 SIS(신살) 정식 버전에서 sis_code(S001~S056)·name_kr·name_en를 반환합니다.
아래 목록의 No.sis_code는 1:1로 매핑됩니다. (예: No. 1 ↔ S001) * 상세 산출 로직(공식)은 에이블시티의 핵심 IP로, API 응답을 통해서만 결과를 제공합니다.

No. 구분 한글명 (Name) 영문 키 (Key)
1흉살격각살gyeok-gak-sal
2흉살겁살geop-sal
3흉살고란살go-ran-sal
4흉살고신살go-sin-sal
5기타공망gong-mang
6흉살과숙살gwa-suk-sal
7길신괴강귀인goe-gang-gwi-in
8흉살괴강살goe-gang-sal
9흉살귀문관살gwi-mun-gwan-sal
10길신금여geum-yeo
11길신록신귀인rok-sin-gwi-in
12흉살망신살mang-sin-sal
13길신문곡귀인mun-gok-gwi-in
14길신문창귀인mun-chang-gwi-in
15길신반안살ban-an-sal
16흉살백호살baek-ho-sal
17길신복성귀인bok-seong-gwi-in
18길신삼기sam-gi
19흉살조객살jo-gaek-sal
20흉살상문살sang-mun-sal
21흉살양인살yang-in-sal
22흉살역마살yeok-ma-sal
23흉살도화살(연살,함지살)do-hwa-sal
24흉살원진살won-jin-sal
25길신월덕귀인wol-deok-gwi-in
26흉살월살wol-sal
27흉살육해살yuk-hae-sal
28길신장성살jang-seong-sal
29흉살재살jae-sal
30흉살지복살ji-bok-sal
31길신지살ji-sal
32길신천계귀인cheon-gye-gwi-in
33길신천관성cheon-gwan-seong
34길신천덕귀인cheon-deok-gwi-in
35흉살천라지망cheon-ra-ji-mang
36길신천문성cheon-mun-seong
37길신천복성cheon-bok-seong
38길신천수성cheon-su-seong
39길신천을귀인cheon-eul-gwi-in
40길신천의성cheon-ui-seong
41길신천주귀인cheon-ju-gwi-in
42흉살충살chung-sal
43길신태극귀인tae-geuk-gwi-in
44길신학당귀인hak-dang-gwi-in
45기타현침살hyeon-chim-sal
46흉살형살hyeong-sal
47길신홍염살hong-yeom-sal
48기타화개hwa-gae
49길신천덕합cheon-deok-hap
50길신월덕합wol-deok-hap
51길신협록hyeop-rok
52길신암록am-rok
53흉살파살pa-sal
54흉살천살cheon-sal
55흉살탕화살tang-hwa-sal
56흉살효신살hyo-sin-sal
(총 56종 리스트)

3.2 v2 Add-ons 및 심화 분석

기본 만세력 외에 오늘의 운세, 올해 운세, 정통사주, 궁합, 작명, 관상, 손금 등 다양한 v2 Add-on API를 제공합니다.
fortune/request-analysis/로 시작하는 엔드포인트는 모두 POST + Callback 방식이며, 나머지는 GET 방식입니다.

  • GET 동기 처리: /fortune, /daily, /zodiac-luck, /luck-flow는 호출 즉시 결과를 반환합니다.
  • POST 비동기 처리: /fortune/request-analysis/... 계열은 연산 후 X-Callback-URL로 결과를 전송합니다.
  • CHECK 궁합(2인), 작명, 이미지 기반 분석은 입력 구조가 다르므로 각 예시의 payload 키 이름을 그대로 사용하세요.

서비스 엔드포인트 목록

Method Endpoint Path (Full URL) Description
GET /api/v2/saju/fortune/daily 오늘의 운세
GET /api/v2/saju/fortune/zodiac-luck 오늘의 띠별 운세
GET /api/v2/saju/fortune/luck-flow 대운 / 연운 / 월운
POST /api/v2/saju/fortune/request-analysis/this-year-luck 올해 운세
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/telling 정통사주
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/match 궁합(2인)
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/week-luck 주간 운세
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/love-luck 올해 애정운
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/rich-luck 올해 재물운
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/naming 작명(추천 + 풀이)
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/face 관상(얼굴 이미지)
(Callback 필수)
POST /api/v2/saju/fortune/request-analysis/palmistry 손금(손 이미지)
(Callback 필수)

POST + Callback Recipe

궁합(2인) API 호출 예시

궁합 API는 한 명의 생년월일만 보내는 기본 조회와 다릅니다. male, female 두 객체를 JSON body에 넣고, 분석 결과를 받을 callback URL을 헤더로 전달해야 합니다.

/request-analysis/match

1. Callback URL 준비

분석 결과를 받을 서버 endpoint를 먼저 만들어 둡니다.

2. 궁합 요청 전송

male, female 객체와 X-Callback-URL 헤더를 함께 보냅니다.

3. 결과 수신

요청 성공 응답은 접수 확인이며, 최종 분석 결과는 callback으로 받습니다.

완성형 cURL 예시
curl -X POST \
  "https://api.ablecity.kr/api/v2/saju/fortune/request-analysis/match" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Callback-URL: https://your-server.com/webhook/saju-match" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "male": {
      "birth": "1999-04-10T00:30:00",
      "gender": "male",
      "midnightType": 0,
      "city": "서울특별시",
      "calendar": "solar"
    },
    "female": {
      "birth": "1998-03-10T00:10:00",
      "gender": "female",
      "midnightType": 0,
      "city": "태안군",
      "calendar": "solar"
    }
  }'
payload 필드
필드 필수 설명
male Yes 남성 사용자 또는 첫 번째 대상자의 생년월일 정보 객체입니다.
female Yes 여성 사용자 또는 두 번째 대상자의 생년월일 정보 객체입니다.
birth Yes YYYY-MM-DDTHH:mm:ss 형식의 생년월일과 출생 시각입니다.
gender Yes male 또는 female 값을 사용합니다.
midnightType Yes 자시 처리 방식입니다. 일반 연동은 0 기준으로 시작합니다.
city Yes 출생지입니다. 예: 서울특별시, 태안군.
calendar Yes 양력은 solar 값을 사용합니다.
요청 성공 시 즉시 응답 예시
{
  "status": "success",
  "message": "분석 요청이 접수되었습니다.",
  "data": {
    "request_id": "match_20260409_000001",
    "service": "match",
    "callback_status": "queued",
    "callback_url": "https://your-server.com/webhook/saju-match"
  }
}
Node.js callback 수신 예시
app.post("/webhook/saju-match", express.json(), (req, res) => {
  console.log("궁합 분석 결과:", req.body);
  res.status(200).json({ ok: true });
});
callback 결과 구조 예시
{
  "request_id": "match_20260409_000001",
  "service": "match",
  "status": "success",
  "data": {
    "summary": "두 사람의 관계 성향과 보완 지점을 요약합니다.",
    "score": 82,
    "sections": [
      {
        "title": "성향 궁합",
        "content": "서로의 기질과 관계 흐름을 설명합니다."
      },
      {
        "title": "주의할 점",
        "content": "갈등이 생기기 쉬운 지점과 대화 방식을 안내합니다."
      }
    ]
  }
}

자주 실패하는 부분

  • X-Callback-URL 헤더에서 콜론(:)을 빼면 안 됩니다.
  • male, female 키 이름을 임의로 바꾸면 안 됩니다.
  • Content-Type: application/json 없이 JSON body를 보내면 서버가 body를 읽지 못할 수 있습니다.
  • callback URL은 외부에서 접근 가능한 HTTPS endpoint를 권장합니다.

Request Example (POST / Callback, v2)

* /api/v2/saju/fortune/request-analysis/... 계열은 모두 X-Callback-URL 헤더가 필수입니다.

curl -X POST \
    "https://api.ablecity.kr/api/v2/saju/fortune/request-analysis/rich-luck" \
    -H "Authorization: Bearer <API_KEY>" \
    -H "X-Callback-URL: https://your-server.com/webhook/result" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "birth": "1990-01-01T00:00:00",
      "gender": "male",
      "city": "서울특별시",
      "calendar": "solar",
      "midnightType": 0
    }'

준비 중 문서

점성술 API 문서 준비 중

점성술 API는 아직 정식 공개 전 문서입니다. 현재는 URL 구조와 응답 스키마 검토를 위해 준비 중이며, 검색 색인은 차단된 상태로 유지합니다.

준비 문서 보기

4. Error Codes

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

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 전용 message

  • ℹ️ invalid birth date format
    birth 형식 오류. yyyy-MM-dd HH:mm:ss 형식만 허용됩니다.
  • ℹ️ gender must be 'male' or 'female'
    gender 값이 male 또는 female이 아닐 때.
  • ℹ️ invalid timezone
    태어난 지역 시간대 오류. IANA tz 데이터베이스 기준으로 검증됩니다.

5. Rate Limit

안정적인 서비스 제공을 위해 API 호출 빈도를 제한하고 있습니다. 모든 엔드포인트는 발급받은 API Key를 기준으로 아래의 기본 한도가 적용됩니다.

Per Minute 분당 한도
60 requests
Per Day 일일 한도
50,000 requests

⚠️ 한도 초과 시 처리 (Throttling)

서비스별 혹은 전체 한도를 초과하면 HTTP Status 429 (Too Many Requests)와 함께 Rate Limit 관련 message가 반환됩니다.

비즈니스 규모에 따라 더 높은 한도가 필요하신 경우, 고객센터([email protected])를 통해 상향을 요청할 수 있습니다.

6. FAQ (자주 묻는 질문)

Ablecity 사주 API는 어떤 버전으로 연동하나요?

현재 문서는 v2 전용 기준으로 안내합니다. 모든 신규 테스트키와 정식키는 /api/v2/... 경로 기준으로 연동합니다.

궁합 API는 왜 기본 만세력 조회보다 어렵나요?

궁합 API는 한 명이 아니라 두 사람의 정보를 함께 보내야 하므로 male, female 두 객체가 필요합니다. 또한 분석 결과가 즉시 반환되지 않고 X-Callback-URL로 전달되므로 callback endpoint를 먼저 준비해야 합니다.

X-Callback-URL에는 어떤 값을 넣어야 하나요?

분석 결과를 받을 서버 endpoint URL을 넣습니다. 예를 들어 https://your-server.com/webhook/saju-match처럼 외부에서 접근 가능한 HTTPS URL을 권장합니다. 헤더 문법은 X-Callback-URL: https://...처럼 콜론을 포함해야 합니다.

fortune/request-analysis/로 시작하는 엔드포인트는 왜 POST와 callback URL이 필요한가요?

정통사주, 올해 운세, 궁합, 작명처럼 생성 시간이 더 필요한 분석형 API는 비동기로 처리합니다. 그래서 요청은 POST로 보내고, 결과는 X-Callback-URL로 전달받는 구조입니다.

만세력 API 사용료는 어떻게 되나요?

테스트는 100건까지 무료이며, 이후에는 구독 형태에 따라(건당 10원~100원)가 적용됩니다.

사주 API는 어떤 프로그래밍 언어에서 사용할 수 있나요?

표준 RESTful JSON 응답을 제공하므로 Python, JavaScript(Node.js), Java, PHP, Go 등 HTTP 클라이언트를 지원하는 모든 언어 및 플랫폼에서 호출할 수 있습니다.

API Dashboard는 언제 사용하나요?

API 키를 받은 고객이 API Dashboard에서 회원가입한 뒤 사용량, 구독 상태, API 조회를 확인할 수 있습니다. 키 발급 전에는 먼저 API 키 발급 신청을 진행해 주세요.

무료 체험용 API 키는 어떻게 받나요?

👉 API 키 발급 신청서(구글폼)를 통해 접수해 주시면, 관리자가 검토 후 1~2일 이내에 이메일로 키를 발송해 드립니다.

7. Support

도움이 필요하신가요?

API 연동 전 문의는 이메일로 보내 주세요. API 키를 받은 고객은 Dashboard에서 회원가입 후 사용량, 구독, API 조회를 확인할 수 있습니다.