프론트 연동 가이드

크리에이터 신청 폼에 인스타그램 DM 인증 단계를 붙입니다. 서버가 링크와 안내 문구를 내려주므로, 프론트는 그대로 보여주기만 하면 됩니다.

붙는 자리

캠페인 신청 직후 별도 페이지입니다. 신청 폼 안이 아닙니다 — 인증은 인스타그램 앱을 다녀와야 끝나는 흐름이라, 작성 중인 폼 위에 얹으면 입력하던 내용을 잃을 위험이 있습니다.

신청을 막지 않습니다. 인증을 안 했다고 신청 자체를 차단하지는 않습니다. 안내하고 권하되, 건너뛸 수 있어야 합니다.

인증은 신청 단위입니다. 두 엔드포인트 모두 applicationId 가 필수이고, 캠페인마다 따로 인증합니다 — 같은 사람이 캠페인마다 다른 인스타 계정으로 신청하는 경우가 있어서입니다 (prod 기준 6.7%).

applicationId 는 TB_CAMPAIGN_APPLICATION.id 입니다. 본인의 신청이 아니면 서버가 거절합니다.

화면 그리는 순서

엔드포인트가 둘이고 쓰임이 다릅니다.

① 신청 폼 진입
   GET /ai/influence/dm-link/status?applicationId=7240
     enabled=false  → 인증 단계를 아예 감춘다
     verified=true  → "인증됨 @username" 만 보여주고 끝
     verified=false → ②로

② 인증하기 버튼 클릭
   POST /ai/influence/dm-link/token?applicationId=7240&locale=ko
     → verifyUrl(링크/QR) + verifyCode(6자리) + expiresAt 를 화면에 그린다

③ 크리에이터가 인스타에 다녀온 뒤
   GET /ai/influence/dm-link/status?applicationId=...  → verified 가 true 로 바뀌었는지 확인

/token 은 화면을 그릴 때마다 부르지 마세요. 부를 때마다 새 링크와 새 코드가 발급됩니다(이전 것도 유효시간 동안은 살아 있어 깨지지는 않지만, 크리에이터가 적어둔 코드와 화면의 코드가 달라 보입니다). 버튼을 누르는 시점에 한 번만 부르세요.

③ 은 visibilitychange 처럼 화면이 다시 보이는 시점에 한 번이면 충분합니다. 짧은 주기로 계속 폴링할 필요는 없습니다.

호출

POST /ai/influence/dm-link/token?applicationId=7240&locale=ko
Authorization: Bearer {크리에이터 accessToken}

{
  "status": 200,
  "message": "발급 완료",
  "data": {
    "verifyUrl": "https://ig.me/m/glow.b_kor?ref=0ZIoudELbI1znz7lWeMVT4eA58zmPOuZ",
    "verifyCode": "482913",
    "expiresAt": "2026-09-08T13:03:59.123"
  }
}

locale 을 반드시 넘겨주세요. 인증이 끝나면 서버가 크리에이터에게 결과를 DM 으로 회신하는데, 그때 어느 말로 답할지가 이 값으로 정해집니다. 웹훅에는 언어를 알 단서가 전혀 없어(핸들도 IGSID 도 알려주지 않습니다) 발급 시점에 받아 토큰에 실어둡니다. 안 넘기면 기본값(한국어)으로 답합니다.

locale 은 화면 로케일을 그대로 넘기면 됩니다. 일본어는 jp 와 ja 둘 다 받습니다. 지원 언어는 한국어·일본어·영어이고, 그 외는 영어로 처리됩니다.

표시 방법

모바일 — verifyUrl 을 그대로 링크로 겁니다. 인스타 앱이 설치돼 있으면 앱의 대화창이 열립니다.

PC — verifyUrl 을 QR 코드로 그립니다. 폰으로 찍으면 그대로 대화창이 열립니다.

URL 을 프론트에서 조립하지 마세요. 반드시 서버가 준 verifyUrl 을 그대로 씁니다. 과거에 신청 SNS 링크를 프론트가 조립하다 계정 아이디가 유실된 선례가 있습니다.

안내 문구

한 줄이면 됩니다 — 링크를 열면(또는 QR 을 찍으면) 인스타 대화창이 열리고, 그것으로 인증이 끝납니다.

인증 코드도 같이 보여주세요

verifyCode 는 6자리 숫자입니다. 링크와 한 쌍으로 발급되며 둘 중 아무거나 쓰면 됩니다.

링크만으로 끝나는 것이 정상 경로이고, 코드는 그게 안 될 때를 위한 것입니다 — 인스타그램에서 우리 계정을 직접 찾아 들어온 경우처럼 링크를 거치지 않은 흐름에서는 누가 보냈는지 알 수 없어 인증이 끝나지 않습니다. 그때 대화창에 코드를 보내면 해결됩니다.

화면에는 이 정도로 적으면 됩니다.

인스타 대화창이 안 열리거나 인증이 안 되면, 대화창에 482913 이라고 보내주세요.

복사 버튼을 붙여주면 좋습니다. 공백이나 하이픈이 섞여도 서버가 걷어내고 읽습니다.

신청서에 적은 계정으로만 인증됩니다. 다른 인스타 계정으로 링크를 열거나 코드를 보내면 거절되고, 크리에이터는 어느 계정으로 해야 하는지 DM 으로 안내받습니다. 이때 링크와 코드는 살아 있으므로 맞는 계정에서 그대로 다시 시도하면 됩니다 — 재발급이 필요 없습니다.

신청서 핸들은 크리에이터가 스스로 고칠 수 없습니다. 잘못 적었다면 어드민이 고쳐야 합니다.

만료와 재발급

링크와 코드는 1시간, 한 번만 쓸 수 있습니다. 신청 폼을 오래 열어두는 경우가 있으므로 인증 버튼을 누르는 시점에 발급하세요. 미리 받아두고 나중에 쓰면 만료됩니다.

만료된 링크로 들어오면 크리에이터는 "링크가 만료되었습니다. 신청 화면에서 링크를 다시 받아주세요"라는 DM 을 받습니다. 그때 다시 발급받으면 됩니다.

크리에이터가 받게 되는 DM

프론트가 보낼 필요는 없고, 서버가 자동으로 회신합니다. 안내 문구를 쓸 때 참고하세요.

상황	회신
인증 완료	인증이 완료되었습니다 + 추후 캠페인 공지가 DM으로 갈 수 있다는 안내
신청서와 다른 계정	신청서에 적은 계정(@handle)으로 다시 인증해달라는 안내
「알림 허용」 수신	확인했다는 응답 (인증돼 있으면 따로 설정할 것이 없다는 안내)
누구인지 모름	링크를 한 번 더 열어달라는 안내
토큰 만료	신청 화면에서 링크를 다시 받아달라는 안내
이미 다른 회원에게 붙은 계정	고객센터 문의 안내

오류 응답

상황	처리
기능 플래그 꺼짐	인증 단계를 아예 노출하지 마세요
크리에이터 정보 없음	로그인 상태를 확인하세요

influenceId 는 서버가 로그인 정보에서 꺼냅니다. 프론트가 넘기지 않습니다 — 넘기게 하면 남의 신청에 자기 계정을 붙일 수 있습니다.

완료 여부 확인

인증은 인스타그램 앱에서 일어나 화면으로 돌아오지 않습니다. 그래서 프론트는 상태 조회로 결과를 물어봐야 합니다.

GET /ai/influence/dm-link/status?applicationId=7240
Authorization: Bearer {크리에이터 accessToken}

{ "enabled": true, "verified": true, "notifyOptIn": true, "username": "glowb.tester3" }

`verified`	화면
`false`	인증하기 버튼 + 링크/QR
`true`	완료 — 인증된 계정(`username`)을 보여주면 된다

수신 동의를 따로 받지 않습니다. 여기서 나가는 것은 이미 캠페인에 참여 중인 크리에이터에게 보내는 일정 공지이지 광고가 아니라서, 인증이 곧 발송 준비 완료입니다. notifyOptIn 은 나중에 "그만 받겠다"는 사람을 빼기 위한 수신 거부 기록이라 프론트가 분기에 쓸 값이 아닙니다.

호출 시점은 신청 폼 진입 시 1회, 그리고 크리에이터가 인스타에서 돌아왔을 때 한 번 더면 충분합니다(visibilitychange 등). 짧은 주기로 계속 폴링할 필요는 없습니다.

enabled 가 false 면 인증 단계를 아예 감추세요. 기능 플래그가 꺼진 상태입니다.

프론트 연동 가이드

On this page