KArtSell.Aegis/docs/GITEA_API_REFERENCE.md

Gitea API & External Data Sources

Gitea Actions Secrets

External API keys are stored in Gitea Actions Secrets (not in .env or code).

Location: https://gitea.taxbaik.com/kjh2064/KArtSell.Aegis/settings/actions/secrets

Available secrets:

• KRX_OPENAPI — Korea Exchange OpenAPI (stock prices, indices, market data)
• OPENDART_API — OpenDart financial disclosure & quarterly reporting
• KIS_APP_KEY / KIS_APP_SECRET — Korea Investment & Securities trading API

Usage in CI/CD (.gitea/workflows/*.yml):

env:
  KRX_OPENAPI: ${{ secrets.KRX_OPENAPI }}
  OPENDART_API: ${{ secrets.OPENDART_API }}
  KIS_APP_KEY: ${{ secrets.KIS_APP_KEY }}
  KIS_APP_SECRET: ${{ secrets.KIS_APP_SECRET }}

For local development: Ask team lead for local sandbox keys or use mock fixtures in tests.

---

External Data APIs

KRX OpenAPI (Korea Exchange)

Official Guide: https://openapi.krx.co.kr/contents/OPP/INFO/service/OPPINFO004.cmd

Available Services:

Service	Link	Endpoint	Method	Auth
지수 (Indices)	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES001_S1.cmd	/svc/apis/idx/krx_dd_trd	POST	AUTH_KEY header
주식 (Stocks)	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES002_S1.cmd	/svc/apis/sco/...	POST	AUTH_KEY header
증권상품	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES003_S1.cmd	/svc/apis/sec/...	POST	AUTH_KEY header
채권	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES004_S1.cmd	/svc/apis/bon/...	POST	AUTH_KEY header
파생상품	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES005_S1.cmd	/svc/apis/drv/...	POST	AUTH_KEY header
일반상품	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES006_S1.cmd	/svc/apis/gen/...	POST	AUTH_KEY header
ESG	https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES007_S1.cmd	/svc/apis/esg/...	POST	AUTH_KEY header

Current Implementation:

• ✅ Indices API: /svc/apis/idx/krx_dd_trd (POST + JSON body {"basDd":"YYYYMMDD"})
• 📍 Location: src/KArtSell.Modules.ModelOperations/ShadowRun/Services/KrxDataService.cs
• 📍 Automatic Fallback: API failure → stub data (realistic values for testing)

OpenDart API (Financial Disclosure)

Official Guide: https://opendart.fss.or.kr/guide/main.do

Available API Groups:

Group	Link	Endpoint	Method	Auth	Purpose
공시정보	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001	/api/list.json	GET	crtfc_key	Disclosure search
정기보고서 주요정보	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS002	/api/...	GET	crtfc_key	Annual report highlights
정기보고서 재무정보	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003	/api/...	GET	crtfc_key	Quarterly financial data
지분공시 종합정보	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS004	/api/...	GET	crtfc_key	Equity disclosure
주요사항보고서	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS005	/api/...	GET	crtfc_key	Material event reports
증권신고서	https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS006	/api/...	GET	crtfc_key	Security registration

Current Implementation:

• ✅ Disclosure Info: /api/list.json?crtfc_key=KEY&corp_code=CODE (GET)
• 📍 Location: src/KArtSell.Host/Observability/OpenDartService.cs
• 📍 Note: Current endpoint returns disclosure listings, not quarterly financial data
• 📍 For financial data: Use DS003 group (정기보고서 재무정보)

---

Gitea API Automation (Optional)

Environment Setup

# Enable Gitea API automation (optional)
$env:GITEA_TOKEN_TAXBAIK = "your-gitea-api-token"  # Windows PowerShell
export GITEA_TOKEN_TAXBAIK="your-gitea-api-token"  # macOS/Linux

Common Tasks

1. Verify PR Build Status

# After successful build/test, comment on PR:
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -H "Content-Type: application/json" \
  -d '{"body":"✅ Build: PASS\n✅ Tests: 41/41 PASS\n✅ Security: Clean"}' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{PR_NUMBER}/comments

2. Auto-Label PRs by Module

# Label PR with affected modules
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -d '["architecture","performance","observability"]' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{PR_NUMBER}/labels

3. Link to Tech Debt Registry

# Reference debt in commit message (e.g., in CI job):
git commit -m "fix: CA1822 static method hints - TECH-001

Resolves technical debt from NoWarn bypass.
Part of quarterly paydown target (20% per quarter).

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>"

4. Gitea Actions Integration (.gitea/workflows/ci.yml)

- name: Post PR verification results
  if: always()
  run: |
    BODY="## Verification Results
    - Build: ${{ job.status }}
    - Tests: 41/41 ✅
    - Debt Paydown: TECH-001 resolved
    
    [See full logs](https://gitea.taxbaik.com/kjh2064/KArtSell.Aegis/actions)"
    
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{\"body\":\"$BODY\"}" \
      https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/${{ github.event.pull_request.number }}/comments