nomadamas__k-skill/docs/features/g2b-order-plan-search.md

나라장터 발주계획 검색 (g2b-order-plan-search)

g2b-order-plan-search는 공공데이터포털의 조달청_나라장터 발주계획현황서비스(15129462, OrderPlanSttusService)를 k-skill-proxy 경유로 호출해 물품·공사·용역·외자 발주계획 목록을 조회한다.

제공 기능

• 발주계획 목록 검색: 물품, 공사, 용역, 외자
• 조건 검색: 발주년월 범위, 게시일시 범위, 발주기관명/코드, 사업명 키워드, 조달방식, 기관소재지, 세부품명번호, 업무유형, 공종
• 반환: 발주기관, 사업명, 발주월, 계약방법, 금액, 담당부서/담당자/전화번호, 입찰공고번호목록 등 upstream 원문 필드

정책 경계

• data.go.kr 무료 API이지만 API key가 필요하므로 k-skill-proxy를 사용한다.
• 사용자 로컬에 DATA_GO_KR_API_KEY를 요구하지 않는다.
• 나라장터 로그인, 인증서, 입찰 참가, 제출, 결제, 낙찰/계약 처리는 자동화하지 않는다.
• 발주계획은 사전계획이며 실제 사전규격공개/입찰공고/계약과 1:1로 보장되지 않는다.

사용 예시

npx -y @nomadamas/k-skill@0 exec g2b-order-plan-search scripts/g2b_order_plan.py -- \
  --kind service \
  --keyword 청소 \
  --order-from 2025-01 \
  --order-to 2025-03 \
  --posted-from 2025-01-01 \
  --posted-to 2025-01-31 \
  --limit 10

npx -y @nomadamas/k-skill@0 exec g2b-order-plan-search scripts/g2b_order_plan.py -- \
  --kind goods \
  --institution 조달청 \
  --region 대전 \
  --order-from 2025-01 \
  --order-to 2025-01

kind 매핑

입력	upstream endpoint
goods, 물품	getOrderPlanSttusListThngPPSSrch
construction, 공사	getOrderPlanSttusListCnstwkPPSSrch
service, 용역	getOrderPlanSttusListServcPPSSrch
foreign, 외자	getOrderPlanSttusListFrgcptPPSSrch
all, 전체	위 4개 endpoint를 순차 조회 후 병합

출력 필드

• query: 정규화된 검색 조건과 upstream operation
• total_count, page, page_size
• items[]: upstream 원문 발주계획 row
• source.data_go_kr_dataset: 15129462
• source.upstream: 호출 upstream URL

실패 모드

• 503 upstream_not_configured: 프록시에 DATA_GO_KR_API_KEY 없음
• 502 upstream_forbidden: 프록시 키가 15129462에 활용신청되지 않음
• 400 bad_request: kind/date/month/page/limit 입력 오류
• total_count: 0: 조건에 맞는 발주계획 없음
• upstream resultCode 03: 데이터 없음

공식 출처

• 공공데이터포털: https://www.data.go.kr/data/15129462/openapi.do
• upstream: https://apis.data.go.kr/1230000/ao/OrderPlanSttusService
• 수동 대조: 나라장터 https://www.g2b.go.kr
• 프록시 route: GET /v1/g2b/order-plans