공시한입 Docs

Appearance

GET /api/v1/disclosures/recent ​

의도 ​

최근 공시 목록 조회. 대시보드 피드에 사용.

인증 ​

없음 (공개)

입력 ​

  • Query: limit (optional, default 10, max 50)

응답 ​

200 OK ​

json
[
  {
    "rcept_no": "20260413800802",
    "corp_name": "삼성전자",
    "corp_code": "00126380",
    "report_name": "분기보고서",
    "rcept_dt": "20260413",
    "submitter": "삼성전자",
    "summary": "분기 매출 X 원, YoY +Y%"
  }
]
  • summary: AI 분석 한줄요약. analysis_cache 와 LEFT JOIN — 분석 미완성/없으면 omit.

curl 예제 ​

bash
curl -s "https://api.dartbrief.com/api/v1/disclosures/recent?limit=20" | jq
curl -s "http://localhost:8000/api/v1/disclosures/recent" | jq

비즈니스 메모 ​

  • HTTP Cache TTL 30초

GET /api/v1/disclosures/ ​

의도 ​

공시 메타 단건 조회 (corp_name, report_name 등 disclosures 테이블 필드). 원문 텍스트 미포함.

인증 ​

없음 (공개)

curl 예제 ​

bash
curl -s "https://api.dartbrief.com/api/v1/disclosures/20260413800802" | jq

비즈니스 메모 ​

  • HTTP Cache TTL 5분

GET /api/v1/disclosures ​

의도 ​

기업별 공시 목록 또는 날짜 범위 조회.

인증 ​

없음 (공개)

입력 ​

둘 중 하나 필수:

  • Query: corpCode — 기업 코드 (예: 00126380)
  • Query: beginDate + endDate — YYYYMMDD 형식

기업별 조회만 적용:

  • Query: limit (optional, default 50, max 200) — 다공시 종목 페이로드 폭주 방지

curl 예제 ​

bash
# 기업별 (기본 50건)
curl -s "https://api.dartbrief.com/api/v1/disclosures?corpCode=00126380" | jq

# 기업별 + 상한
curl -s "https://api.dartbrief.com/api/v1/disclosures?corpCode=00126380&limit=200" | jq

# 날짜 범위
curl -s "https://api.dartbrief.com/api/v1/disclosures?beginDate=20260401&endDate=20260430" | jq

비즈니스 메모 ​

  • HTTP Cache TTL 1분

GET /api/v1/companies/ ​

의도 ​

기업 기본 정보 조회.

인증 ​

없음 (공개)

curl 예제 ​

bash
curl -s "https://api.dartbrief.com/api/v1/companies/00126380" | jq

비즈니스 메모 ​

  • HTTP Cache TTL 10분

웹 전용 엔드포인트 (/api/v1/web/*) ​

📋 status: 설계 (PR2 에서 구현). 웹은 비로그인 · summary-only · 종목 필터 · 앱 유도 성격이라 모바일 엔드포인트(/recent, /dashboard/disclosures)와 분리. 핸들러는 internal/web, disclosure repository 재사용. 인증은 기존 웹 패턴(reg.Anonymous + Worker secret X-Worker-Secret).

화면 맥락: screen-dashboard.md

GET /api/v1/web/disclosures ​

의도 ​

웹 대시보드 공시 목록. summary 있는 공시만 (analysis_cache.status='COMPLETED' AND summary <> '' INNER JOIN). corpCode 지정 시 해당 종목만 필터.

정렬은 ORDER BY rcept_dt DESC, rcept_no DESC — rcept_dt 는 일(YYYYMMDD) 단위라 동률이 많으므로 rcept_no 2차 키로 결정적 고정 (페이징 없이 20건 고정 노출 → 비결정 정렬 시 칩/캐시 일관성 깨짐).

입력 ​

  • Query: limit (optional, default 20, max 20) — 웹은 페이징 없음, 상한 고정
  • Query: corpCode (optional) — 지정 시 해당 종목만

응답 ​

/api/v1/disclosures/recent 와 동일 스키마 (summary 항상 존재 — omit 안 됨, summary-only 라서).

json
[
  {
    "rcept_no": "20260413800802",
    "corp_name": "삼성전자",
    "corp_code": "00126380",
    "report_name": "분기보고서",
    "rcept_dt": "20260413",
    "submitter": "삼성전자",
    "summary": "분기 매출 X 원, YoY +Y%"
  }
]

curl 예제 ​

bash
curl -s "https://api.dartbrief.com/api/v1/web/disclosures?limit=20" | jq
curl -s "https://api.dartbrief.com/api/v1/web/disclosures?limit=20&corpCode=00126380" | jq

GET /api/v1/web/active-stocks ​

의도 ​

웹 프리셋 칩 — 최근 N일간 summary 있는 공시가 발생한 종목 (중복 제거, 최근 공시순). 하드코딩 추천 8개를 대체. 칩 클릭 → /?corp={corp_code} 필터.

입력 ​

  • Query: days (optional, default 7, min 1, max 30) — 조회 기간 (오늘 포함 최근 N일. days=7 → 오늘-6일 ~ 오늘). 범위 밖 입력은 clamp (≤0 → 1, >30 → 30) — days=0/음수로 기간 의미 깨지거나 과대값으로 DB 부하 유발 방지
  • Query: limit (optional, default 8, max 20) — 프리셋 칩 개수 상한 (공시 많은 기간 SSR 페이로드 폭주 방지)

응답 ​

json
[
  { "corp_code": "00126380", "corp_name": "삼성전자", "stock_code": "005930" }
]

쿼리 개요 — corp_code 단일 키 dedup (동일 종목의 corp_name/stock_code 이력이 달라도 1개 칩만). DISTINCT ON (corp_code) 로 종목별 최신 공시 1건만 남긴 뒤 최근순 정렬 + limit:

sql
SELECT corp_code, corp_name, stock_code
FROM (
  SELECT DISTINCT ON (d.corp_code)
         d.corp_code, d.corp_name, d.stock_code, d.rcept_dt, d.rcept_no
  FROM disclosures d
  INNER JOIN analysis_cache a
    ON a.rcept_no = d.rcept_no AND a.status = 'COMPLETED' AND a.summary <> ''
  WHERE d.rcept_dt >= TO_CHAR(CURRENT_DATE - (($1 - 1) || ' days')::interval, 'YYYYMMDD')  -- 오늘 포함 N일
  ORDER BY d.corp_code, d.rcept_dt DESC, d.rcept_no DESC   -- corp_code 별 최신 1건 (rcept_no tie-breaker)
) t
ORDER BY t.rcept_dt DESC, t.rcept_no DESC   -- 동률 시 결정적 정렬 (칩 구성 고정)
LIMIT $2;  -- limit (default 8, max 20)

인덱스 idx_disclosures_rcept_dt 활용, 마이그레이션 불필요.

curl 예제 ​

bash
curl -s "https://api.dartbrief.com/api/v1/web/active-stocks?days=7" | jq