| name | kvote-datagokr-api |
| description | kvote의 data.go.kr OpenAPI 계정 연동(api login/list/apply)을 다루는 워크플로. data.go.kr 활용신청·인증키·만료일을 CLI에서 관리하거나, OpenAPI 호출(nec turnout 등)이 인증키를 요구하거나, "활용신청 자동화/신청목록/만료 확인/키 발급" 같은 요청이 나오면 반드시 사용. 로그인 세션을 브라우저에 살려두고 Chrome DevTools Protocol로 다시 붙는 방식(키체인·재로그인·SSO재현 없음)을 안다. |
kvote × data.go.kr OpenAPI 계정 연동
data.go.kr 의 OpenAPI 는 활용신청(자동승인) 으로 인증키를 받아야 호출할 수 있다.
이 신청은 CAPTCHA + 소셜 로그인 뒤에 있어 완전 자동화가 불가능하다. kvote 는 대신
브라우저 로그인을 한 번 받고, 그 세션을 살려둔 채 재사용한다.
0. 왜 이렇게 동작하는가 (CDP-attach)
설치형 단일 바이너리를 유지하면서 로그인 세션을 쓰려면 세 가지 함정을 피해야 한다:
- 키체인 프롬프트: Chrome 127+ 는 쿠키를 app-bound 암호화해 외부 복호화(kooky 류)를
막는다 → 외부에서 쿠키 DB 읽기는 사양길. 쓰지 마라.
- 세션 쿠키 소멸: data.go.kr 인증 쿠키(JSESSIONID 등)는 세션 스코프라 브라우저를
닫으면 사라진다 → "쿠키 저장 후 재실행"은 깨진다.
- SSO 핸드셰이크: 보호 페이지는
/sso/profile.do 자동제출 폼을 거친다 → http 로 직접
재현하면 취약하다.
해법: 브라우저를 데몬으로 살려두고 CDP(원격 디버깅 포트)로 다시 붙는다. Chrome 이
세션을 네이티브로 들고 SSO 도 알아서 처리하므로, 위 셋이 전부 사라진다. (chrome-cdp-skill /
agent-browser 와 같은 접근. 구현: internal/datagokr/.)
1. 워크플로
kvote api login
kvote api list -f table
kvote api list -f json | jq '.[] | {title, status, expiresAt}'
kvote api apply <publicDataPk> --purpose "선거 투표율 분석 연구" --category research
kvote api logout
세션이 만료되면 api list 가 ErrNotLoggedIn 안내를 낸다 → kvote api login 재실행.
2. 발급받은 키로 OpenAPI 호출
활용신청이 승인되면 data.go.kr 마이페이지에서 일반 인증키(64자 hex)를 받는다. 그 키로
키 기반 명령을 호출한다. 키는 비밀 — 환경변수로만 주고 로그·커밋 금지.
export KVOTE_DATAGOKR_KEY=<일반 인증키>
kvote nec turnout 20250603 --sgtype 1
3. 중립성 + 예의 (반드시 지킬 것)
- 신청은 on-demand 로만: 작업이 실제로 필요한 API 만 신청한다. "잠재적으로 쓸지도 모르는"
API 를 투기적으로 대량 신청하지 마라 — 활용목적 명시 취지 위반이고 계정이 플래그될 수 있다.
data.go.kr 은 신청 시 활용목적을 적게 돼 있다. 그 목적에 맞게만.
- 중립성: kvote 는 데이터 접근성만 높인다. 받은 데이터로 정상/비정상/조작을 단정하지
않는다(→ [[kvote-verify]] 와 동일 원칙). 키/세션은 수단일 뿐.
- rate limit·예의: 불필요한 반복 호출 금지. 세션 브라우저는 사용자의 실제 계정이다.
4. 스키마
kvote api list 항목(Application):
{title, status(승인/신청), org, category, account(개발/운영), appliedAt, expiresAt, uddi, detailPk}
— expiresAt(만료예정일)이 갱신 추적의 핵심 필드.
5. 트러블슈팅
- 로그인 창에서 로그인이 안 끝남:
api login 은 인증 페이지가 실제로 열릴 때까지 기다린다.
열린 창에서 로그인을 완료해야 감지된다(URL 이 포털로 복귀). 창이 다른 창 뒤에 있을 수 있다.
ErrNotLoggedIn: 세션 브라우저가 닫혔거나 만료 → kvote api login 재실행.- Chrome 못 찾음: Chrome/Chromium/Brave/Edge 중 하나가 설치돼 있어야 한다.
- 키 401: 활용신청 직후 키는 ~1시간 전파 지연이 있을 수 있다.
