광고 배포 API

승인된 금융 광고를
매체 지면에 자동으로 게재하는 방법

매체는 광고 이미지를 매번 받아 넣지 않습니다. API를 지면에 한 번만 연결해 두면, 금융사가 승인한 최신 소재가 자동으로 들어오고 만료되면 자동으로 빠집니다.

개요

FINIT 광고 배포 API는 심의를 통과해 게재 승인된 소재만 JSON으로 내려주는 읽기 전용 엔드포인트입니다. 만료·미승인 소재는 서버가 걸러내므로, 매체는 받은 목록을 그대로 그리기만 하면 됩니다.

콘솔

금융사

심의필 소재를 콘솔에 등록·승인

API

FINIT

승인·유효한 소재만 API로 제공

GET /ads

매체 지면

GET 호출로 받아 그대로 렌더

개발 연동은 매체 쪽만 하면 됩니다. 금융사는 콘솔(웹 화면)에서 소재 등록·실적 업로드를 처리하므로 별도 개발이 필요 없습니다.

빠른 시작

제휴 신청 → 승인승인되면 콘솔에서 연동 키(finit_live_…)가 발급됩니다.
키를 서버 환경변수에 저장키는 브라우저에 노출하지 말고 백엔드에만 둡니다.
GET 호출 → 렌더아래 한 줄이면 심의필 소재 목록을 받습니다.

요청 — curl

curl -H "Authorization: Bearer finit_live_xxxx" \
     https://finit.work/api/v1/ads

인증

모든 요청에 발급받은 키를 Authorization 헤더로 전달합니다.

헤더Authorization: Bearer <연동 키>

키 형식finit_live_ + 랜덤 문자열

관리콘솔에서 발급 · 폐기 · 재발급

키는 서버에서만 사용하세요. 폐기하면 즉시 무효화됩니다. 유출이 의심되면 콘솔에서 재발급하세요.

광고 조회

GET/api/v1/ads

키로 식별된 매체의 지면에 게재 가능한(승인 · 유효기간 내) 소재 목록을 반환합니다. 별도 파라미터는 필요 없습니다.

200 OK — application/json

{
  "status": 200,
  "partner": "핀테크 A",
  "count": 1,
  "served_at": "2026-07-16T02:11:00Z",
  "data": [
    {
      "ad_id": "a3f2c9…",
      "slot": "메인 상단", "width": 468, "height": 60,
      "title": "내게 맞는 금융 상품",
      "image_url": "https://cdn.finit.work/…/banner.png",
      "link": "https://finit.work/c?ref=…&ad=a3f2c9",
      "review_number": "준법감시 2026-1234",
      "expiry": "2027-06-30"
    }
  ]
}

응답 필드

필드	설명
`ad_id`	소재 고유 ID. 리포트·중복 제거 기준 키.
`slot` · `width` · `height`	이 소재가 들어갈 구좌 이름과 규격(px).
`title`	소재 제목(문구).
`image_url`	배너 이미지 URL. `<img>`의 src로 사용.
`link`	클릭 시 이동할 광고주 랜딩 URL. 앵커(`<a href>`)에 그대로 연결하세요.
`review_number`	심의(준법감시) 번호. 표기 의무가 있으면 함께 노출.
`expiry`	심의 유효기간(참고). 만료분은 서버가 이미 제외합니다.

에러 코드

코드	의미 · 조치
401	인증 실패 — 키 없음/오류/폐기. 키를 확인하거나 재발급하세요.
403	제휴 상태가 `active`가 아님(정지·대기). 운영자에게 확인.
404	알 수 없는 자격 — 존재하지 않는 키/코드.
429	분당 한도(120) 초과. `retry_after_seconds` 후 재시도 + 캐싱 강화.

렌더링 · 갱신

렌더링 — data[]를 순회하며 image_url을 <img>로 그리고 link로 감싸면 끝입니다. 필요 시 review_number를 함께 표기하세요.

갱신 — 목록은 승인·만료로 수시로 바뀝니다. 백엔드에서 주기적으로(예: 5–10분) 재호출하거나 페이지 요청 시 캐시를 갱신해 최신 상태를 유지하세요.

만료 자동 처리

심의 유효기간이 지난 소재는 API 응답에서 자동으로 제외됩니다. 매체가 아무 조치를 하지 않아도, 다음 호출부터 만료 소재는 내려오지 않아 지면에서 저절로 사라집니다.

심의필

승인 등록

게재중

API로 배포

만료 임박

D-day 경고

자동 제외

응답에서 하차

레이트리밋 · 캐싱

Rate limit키당 120 요청 / 분

권장 캐싱서버에서 수 분 캐싱

CORS허용 (GET, OPTIONS)

응답이 자주 바뀌지 않으므로, 여러분 서버에서 짧게 캐싱하면 한도와 지연에 여유가 생깁니다.

보안 권장

연동 키는 백엔드(서버)에서만 사용하고, 브라우저 자바스크립트에 절대 노출하지 마세요.
지면에는 서버가 캐싱한 결과만 내려주는 구조를 권장합니다.
키 유출이 의심되면 콘솔에서 즉시 폐기·재발급하세요. 폐기는 실시간 반영됩니다.
이 API는 집계·소재 메타데이터만 다루며 개인정보를 포함하지 않습니다.

승인된 금융 광고를매체 지면에 자동으로 게재하는 방법

개요