Agency API
Agency Self-service API 에이전시 운영자의 내 정보, 브랜딩, 고객사, 크레딧 관리 API
에이전시 운영자가 자기 에이전시와 소속 고객사를 관리하는 API입니다.
모든 API는 ROLE_AGENCY 권한이 필요합니다. 응답은 bare JSON입니다.
GET /ai/agency/me Authorization : Bearer {access_token} { "agencyId" : "agency-a" , "name" : "Agency A" , "domain" : "agency.example.com" , "brand" : { "logoUrl" : "https://cdn.example.com/logo.png" , "faviconUrl" : "https://cdn.example.com/brand-favicon/1758412800000.png" }, "locale" : "ko" } PATCH /ai/agency/me/branding Authorization : Bearer {access_token} Content-Type : application/json { "logoUrl" : "https://cdn.example.com/logo.png" , "faviconUrl" : "https://cdn.example.com/brand-favicon/1758412800000.png" } { "logoUrl" : "https://cdn.example.com/logo.png" , "faviconUrl" : "https://cdn.example.com/brand-favicon/1758412800000.png" } 필드 타입 필수 설명 logoUrlString아니오 로고 URL. 생략하면 변경 없음. 파비콘이 미설정이거나 자동 생성 상태면 이 로고로 파비콘을 다시 만든다 faviconUrlString아니오 파비콘 URL(POST /ai/agency/branding/favicon 응답값). 생략하면 변경 없음, 빈 문자열이면 해제(아이콘 없음, 이후 자동 생성도 안 함)
PATCH /ai/agency/me/branding
POST /ai/agency/branding/logo Authorization : Bearer {access_token} Content-Type : multipart/form-data 필드 타입 필수 설명 fileFile예 업로드할 로고 파일
{ "logoUrl" : "https://cdn.example.com/logo.png" , "faviconUrl" : "https://cdn.example.com/brand-favicon/1758412800000.png" } POST /ai/agency/branding/logo
업로드한 이미지를 비율 유지·투명 정사각 180x180 PNG 로 변환해 올리고 URL을 돌려준다. 적용하려면 반환된 faviconUrl을 PATCH /ai/agency/me/branding으로 저장한다. 지원 형식은 PNG, JPG, GIF, WEBP, SVG(스크립트·외부 참조 제거 후 래스터화)이며 5MB, 2,500만 픽셀 이하만 받는다.
POST /ai/agency/branding/favicon Authorization : Bearer {access_token} Content-Type : multipart/form-data { "faviconUrl" : "https://cdn.example.com/brand-favicon/1758412800000.png" } 상태 로고를 저장하면 응답 faviconUrl 미설정 로고로 자동 생성 생성된 URL 직접 업로드 유지 업로드 URL 자동 생성 로고가 바뀌면 다시 생성 생성된 URL 해제 생성 안 함 null
POST /ai/agency/branding/favicon
GET /ai/agency/me/clients Authorization : Bearer {access_token} [ { "id" : "client@example.com" , "name" : "고객사 A" , "email" : "client@example.com" , "status" : "active" , "creditBalance" : 100000 , "createdAt" : "2026-07-08T10:30:00" , "notifyAdvertiser" : true , "notifyAgency" : false } ] 필드 타입 설명 notifyAdvertiserBoolean고객사(광고주)가 광고주 알림 이메일을 수신할지. 기본 true notifyAgencyBoolean에이전시가 이 고객사 캠페인 알림 사본(CC)을 수신할지. 기본 false
알림 토글 값(notifyAdvertiser/notifyAgency)이 이 응답에 포함됩니다. 프론트 토글 UI의 현재 상태 표시에 사용하세요. null이면 컬럼 미설정(기본값으로 동작).
POST /ai/agency/me/clients Authorization : Bearer {access_token} Content-Type : application/json { "name" : "고객사 A" , "email" : "client@example.com" , "password" : "password123" } 필드 타입 필수 설명 nameString예 고객사명 emailString예 고객사 이메일. 로그인 ID로 사용 passwordString아니오 초기 비밀번호. 생략 시 서버가 임의 비밀번호를 생성
{ "id" : "client@example.com" , "name" : "고객사 A" , "email" : "client@example.com" , "status" : "active" , "creditBalance" : 0 , "createdAt" : "2026-07-08T10:30:00" } POST /ai/agency/me/clients
PATCH /ai/agency/me/clients/{id} Authorization : Bearer {access_token} Content-Type : application/json 파라미터 타입 필수 설명 idString예 고객사 로그인 ID
전달한 필드만 변경되며, 생략하거나 null이면 기존 값을 유지합니다. 알림 토글만 바꿀 때는 notifyAdvertiser/notifyAgency만 담아 보내면 됩니다.
{ "notifyAdvertiser" : false , "notifyAgency" : true } 필드 타입 필수 설명 nameString아니오 고객사명 emailString아니오 고객사 이메일 statusString아니오 active 또는 inactivenotifyAdvertiserBoolean아니오 광고주 수신 on/off. 기본 true notifyAgencyBoolean아니오 에이전시 합류 수신 on/off. 기본 false
알림 라우팅 동작
notifyAdvertiser/notifyAgency는 이 고객사(AGENCY_CLIENT) 캠페인의 알림 발송 대상을 정합니다. 일반 광고주에게는 영향이 없습니다. notifyAgency=true이면 에이전시의 기본 담당자 에게 글로우비 브랜드로 사본(CC)이 발송됩니다.
notifyAdvertisernotifyAgency결과 truefalse광고주만 수신 (기본) truetrue광고주 + 에이전시 둘 다 수신 falsetrue에이전시만 수신 (광고주 차단) falsefalse아무도 수신 안 함
{ "id" : "client@example.com" , "name" : "고객사 A" , "email" : "client@example.com" , "status" : "active" , "creditBalance" : 0 , "createdAt" : "2026-07-08T10:30:00" , "notifyAdvertiser" : false , "notifyAgency" : true } PATCH /ai/agency/me/clients/{id}
POST /ai/agency/me/clients/{id}/credit Authorization : Bearer {access_token} Content-Type : application/json { "amount" : 100000 , "memo" : "초기 지급" } 필드 타입 필수 설명 amountInteger예 지급할 크레딧. 1 이상 memoString아니오 원장 메모
{ "id" : "client@example.com" , "creditBalance" : 100000 } POST /ai/agency/me/clients/{id}/credit
GET /ai/agency/me/clients/{id}/credit Authorization : Bearer {access_token} [ { "id" : "123" , "type" : "grant" , "amount" : 100000 , "balanceAfter" : 100000 , "memo" : "초기 지급" , "createdAt" : "2026-07-08T10:30:00" } ] 필드 설명 typegrant, use, adjust 중 하나
GET /ai/agency/me/clients/{id}/credit