Instagram OAuth API

Instagram Business 계정을 연동하기 위한 OAuth API입니다. Facebook Graph API를 통해 Instagram Business Account에 접근합니다.

Base URL: /ai/instagram

인증 정보

항목	값
인증 필요	일부 필요
인증 방식	JWT Bearer Token

OAuth 연동 플로우

Instagram 연동은 프론트엔드 Callback 방식을 사용합니다.

1. OAuth URL 요청

프론트엔드에서 백엔드 API를 호출하여 Facebook OAuth URL을 받습니다.

GET /ai/instagram/oauth/url?memberId=user123

응답:

{
  "status": 200,
  "message": "OAuth URL 생성 완료",
  "data": "https://www.facebook.com/v18.0/dialog/oauth?client_id=xxx&redirect_uri=xxx&state=xxx&scope=xxx"
}

2. Facebook 인증 페이지로 리다이렉트

프론트엔드에서 받은 OAuth URL로 사용자를 리다이렉트합니다.

window.location.href = oauthUrl;

사용자는 Facebook 로그인 후 Instagram Business 계정 접근 권한을 허용합니다.

3. 프론트엔드 Callback 수신

Facebook이 사용자를 프론트엔드 callback URL로 리다이렉트합니다.

https://your-frontend.com/instagram/callback?code=AUTH_CODE&state=STATE_VALUE

파라미터	설명
`code`	Authorization code (토큰 교환용)
`state`	CSRF 방지용 state 값 (memberId 포함)

4. 백엔드에 code 전달

프론트엔드가 받은 code와 state를 백엔드 API로 전달합니다.

POST /ai/instagram/oauth/connect?code=AUTH_CODE&state=STATE_VALUE

응답:

{
  "status": 200,
  "message": "Instagram 계정이 연결되었습니다.",
  "data": [
    {
      "accountId": 1,
      "username": "my_instagram",
      "name": "My Instagram Account",
      "profilePictureUrl": "https://...",
      "followersCount": 10000,
      "connectionStatus": "CONNECTED"
    }
  ]
}

플로우 다이어그램

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   프론트    │     │   백엔드    │     │  Facebook   │     │  Instagram  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ 1. GET /oauth/url │                   │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │
       │   OAuth URL 반환  │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
       │ 2. 리다이렉트     │                   │                   │
       │───────────────────────────────────────>                   │
       │                   │                   │                   │
       │                   │    사용자 인증    │                   │
       │                   │    권한 허용      │                   │
       │                   │                   │                   │
       │ 3. Callback (code, state)             │                   │
       │<──────────────────────────────────────│                   │
       │                   │                   │                   │
       │ 4. POST /oauth/connect                │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │
       │                   │ 5. Token 교환     │                   │
       │                   │──────────────────>│                   │
       │                   │                   │                   │
       │                   │   Access Token    │                   │
       │                   │<──────────────────│                   │
       │                   │                   │                   │
       │                   │ 6. 프로필 조회    │                   │
       │                   │───────────────────────────────────────>
       │                   │                   │                   │
       │                   │   Instagram 정보  │                   │
       │                   │<──────────────────────────────────────│
       │                   │                   │                   │
       │  연결된 계정 반환 │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │

엔드포인트 목록

메서드	경로	설명	인증
`GET`	`/ai/instagram/oauth/url`	OAuth URL 조회	불필요
`POST`	`/ai/instagram/oauth/connect`	Instagram 계정 연결	불필요
`GET`	`/ai/instagram/accounts`	연결된 계정 목록 조회	불필요
`DELETE`	`/ai/instagram/accounts/{accountNo}`	계정 연결 해제	불필요
`POST`	`/ai/instagram/accounts/{accountNo}/sync`	계정 정보 동기화	불필요

Response 스키마

SocialAccountDto

필드명	타입	설명
`accountId`	`long`	계정 ID
`platform`	`int`	플랫폼 (1: Instagram)
`platformUserId`	`string`	Instagram Business Account ID
`username`	`string`	Instagram 사용자명 (@없이)
`name`	`string`	계정 이름
`profilePictureUrl`	`string`	프로필 이미지 URL
`biography`	`string`	소개글
`website`	`string`	웹사이트 URL
`followersCount`	`long`	팔로워 수
`followingCount`	`long`	팔로잉 수
`mediaCount`	`long`	게시물 수
`connectionStatus`	`SocialConnectionStatus`	연결 상태
`priceTier`	`string`	가격 티어 (N/S/A/B/C 등)
`price`	`int`	산정 가격