API 연동 가이드

개요

커넥티드 콘텐츠로 호출할 API를 만들거나 점검하는 개발팀을 위한 내용입니다. 마케터에게는 API 주소, 요청 방식, 인증 방식, 응답 예시(JSON)를 전달해주세요.

구분	조건
스킴 · 포트	`http` 또는 `https`, 표준 포트(80, 443)만 호출합니다
사설망	사내망 · 내부 IP는 호출할 수 없습니다. 외부에서 접근 가능한 주소여야 합니다
주소	변수 치환 후 2048자 이하. `user:pass@` 형태로 인증 정보를 넣을 수 없습니다 (인증 정보 등록 사용)
리다이렉트	3xx를 따라가지 않습니다. 최종 주소를 지정해주세요
성공 판정	2xx만 성공입니다. 4xx · 5xx는 본문이 있어도 실패로 처리합니다
응답 시간 · 크기	2초 이내, 1MB 이하
응답 형식	JSON 객체를 권장합니다. 일반 텍스트도 쓸 수 있습니다
JSON 응답 헤더	· JSON으로 쓰려면 `Content-Type: application/json`을 반드시 붙여주세요 · 헤더가 없거나 `text/plain`이면 본문이 JSON이어도 텍스트로 처리합니다 · JSON으로 선언했는데 본문이 JSON이 아니면 실패로 처리합니다

플레어레인은 고정 IP에서 호출합니다. 방화벽으로 접근을 제한한다면 담당 매니저에게 발신 IP를 받아 허용 목록에 추가해주세요. 모든 호출에는 아래 헤더가 붙습니다.

헤더	값
`User-Agent`	`FlareLane-ConnectedContent/1.0`
`X-flarelane-connected-content-request-id`	요청마다 다른 고유 ID
`X-flarelane-connected-content-request-timestamp`	요청 시각 (ISO 8601)

호출 수는 수신자 수와 같지 않습니다. 지시문마다 호출되고, 재처리 시 다시 호출될 수 있으며, 캐시로 줄어들 수도 있습니다.
대량 발송에 쓸 API라면 수신자 수보다 많은 요청도 감당할 수 있어야 합니다. 429 응답이 반복되면 장애 차단 원인이 됩니다.
쿠폰 발급처럼 호출마다 결과가 생기는 API는, 같은 요청이 다시 와도 결과가 중복되지 않게 만들어주세요. 예: 이미 발급한 쿠폰을 그대로 돌려주기

호출이 실패하면 메시지에는 빈칸만 남습니다. 서버 로그에서 플레어레인 요청(User-Agent, 요청 ID 헤더로 구분)의 응답 코드를 확인하세요.

응답 코드	확인할 것
400	body 형식이 API가 기대하는 형식과 맞는지. JSON이라면 권장 작성법을 따랐는지
401	인증 정보 값(ID · PW · 헤더값)이 맞는지
403	발신 IP를 허용했는지, `User-Agent`를 막고 있지 않은지, 토큰에 해당 API 권한이 있는지
404	주소와 경로에 넣은 변수 값이 맞는지
405	`:method`가 API가 받는 방식과 같은지
429	처리 한도를 넘었는지. 반복되면 장애 차단 원인이 됩니다
5xx	서버 오류입니다. 502 · 503 · 504가 반복되면 장애 차단 원인이 됩니다