진단용: 현재 인증된 호출자 email과 연결된 자격증명 유무를 확인한다.

OAuth 토큰에서 email이 제대로 추출되는지 점검용. email 추출이 안 되면 claim_keys를 보고 추출 규칙을 조정한다.

내가 접근 가능한 광고주 계정 전체 목록.

/ad-accounts(개인 접근, SA+GFA) 와 child-ad-accounts(대행 위임 로스터)를 customerId로 합쳐(dedupe) 반환한다. 각 항목:

• account_id = 검색광고 customerId (다른 조회 툴에 그대로 사용)

• platforms = ['SA'|'GFA'...] (검색광고/디스플레이. GFA만 있으면 검색광고 데이터는 빈 결과)

• roles = ['MASTER'|'OWNER'...] (오너/마스터가 아닌 권한도 포함)

• sources = ['ad-accounts'|'child-ad-accounts'] (어느 소스에서 나왔는지) 여기 나오는 모든 account_id는 이 자격증명으로 조회 가능하다.

내가 접근 가능한 계정들의 현황 요약(계정별 캠페인 수 + 기간 성과 합계).

접근 불가/오류 계정은 error 필드로 표시된다.

계정의 캠페인 목록을 조회한다 (GET /ncc/campaigns).

동기 /stats 성과 조회. 윈도우 ≤ 92일, 레벨 혼합 불가, 최근/소량용.

반환 행에는 원본 필드(salesAmt 등)와 함께 명확한 별칭(cost 등)을 함께 붙인다.

연관 키워드와 월간 검색량·경쟁도를 조회한다 (GET /keywordstool).

저검색량 값('< 10')은 {value, approx, raw} 형태로 정규화한다.

단일 캠페인 상세 (GET /ncc/campaigns/{id}).

캠페인의 광고그룹 목록 (GET /ncc/adgroups?nccCampaignId=).

단일 광고그룹 상세 (GET /ncc/adgroups/{id}).

광고그룹의 키워드 목록 (GET /ncc/keywords?nccAdgroupId=).

광고그룹의 광고(소재) 목록 (GET /ncc/ads?nccAdgroupId=).

비즈니스 채널 목록 (GET /ncc/channels).

계정의 모든 캠페인 성과를 이름과 함께 반환한다.

캠페인 열거 → /stats 조회 → nccCampaignId로 이름 join. 대시보드성 요약용.

한 광고그룹의 키워드별 성과를 키워드 텍스트와 함께 반환한다.

키워드 입찰가를 추정한다 (POST /estimate/{type}/keyword).

average-position-bid=목표 평균순위 도달 입찰가, exposure-minimum-bid=최소 노출가.

입찰가별 예상 노출/클릭/비용을 추정한다 (POST /estimate/performance/keyword).

네이버 스키마: 키워드 1개 + 입찰가 리스트를 top-level로 전송. 응답의 estimate는 각 입찰가에 대응하는 {bid, impressions, clicks, cost} 배열이다.

기간 성과 리포트 (명명형). 92일 초과 기간은 자동 청킹.

레벨별 엔티티를 열거해 /stats로 조회하고 이름을 붙여 반환한다. 합계 모드는 가산 지표(노출/클릭/비용/전환)를 합산 후 비율(CTR/CPC/전환율/ROAS)을 재계산한다. 대량(전 계정 키워드·장기 히스토리)은 저수준 StatReports 툴 사용을 권장. metrics/annotate로 응답 필드를 좁히면 전송·직렬화 비용을 줄일 수 있다(선택).

대량 StatReport 잡을 생성하고 완료까지 대기한다 (비동기, 1잡=1일).

반환의 downloadUrl을 download_stat_report로 받아 TSV를 얻는다. status가 NONE이면 해당 일자 데이터 없음.

StatReport TSV를 다운로드해 원본 행을 반환한다 (서명 필요).

⚠️ 컬럼 레이아웃은 reportTp별로 다르며 여기서 해석하지 않는다(위치 파싱 오매핑 방지). 각 reportTp의 컬럼 정의는 네이버 StatReport 스펙을 참조해 매핑하라. 명명형 지표가 필요하면 get_performance_report를 사용.