KoreaAI Hub — API 사용 가이드

작성: 2026-02-28 자비스 프로젝트: projects/koreaai-hub/

1. 뉴스레터 구독 API

POST `/api/subscribe`

구독자 등록 + Brevo 리스트 추가.

Request:

{
  "email": "user@example.com"
}

Response (성공):

{ "success": true, "message": "구독이 완료되었습니다." }

Response (중복):

{ "success": false, "error": "이미 구독 중인 이메일입니다." }

환경변수:

BREVO_API_KEY: Brevo API 키
BREVO_LIST_ID: Brevo 구독자 리스트 ID
TURSO_DB_URL, TURSO_DB_TOKEN: DB 연결

2. 뉴스레터 발송 API

POST `/api/newsletter/send?id={issue_id}`

newsletter_issues 테이블에서 조회 → Brevo bulk 발송.

Headers:

x-api-key: {INTERNAL_API_KEY}

Query Params:

id (optional): 특정 뉴스레터 ID (미입력 시 최신 draft 발송)

Response (성공):

{
  "success": true,
  "issueId": 1,
  "subject": "[창간호] AI로 하루 2시간 되찾는 소상공인...",
  "sent": 42
}

Response (실패 케이스):

{ "error": "No draft newsletter found" }
{ "error": "No subscribers found" }
{ "error": "Already sent" }

DB 뉴스레터 등록:

INSERT INTO newsletter_issues (subject, html_content, status)
VALUES ('제목', '<p>HTML 본문</p>', 'draft');

3. 수신거부 API

GET `/api/unsubscribe?email={email}&token={token}`

HMAC-SHA256 토큰 검증 후 구독 취소.

동작 순서:

HMAC-SHA256(UNSUBSCRIBE_SECRET, email) 검증
DB status = 'unsubscribed' 업데이트
Brevo 리스트에서 제거
한국어 HTML 응답 페이지 반환

이메일에서 수신거부 링크 생성 방법:

import { createHmac } from 'crypto';
const token = createHmac('sha256', process.env.UNSUBSCRIBE_SECRET!)
  .update(email)
  .digest('hex');
const unsubscribeUrl = `https://koreaaihub.kr/api/unsubscribe?email=${email}&token=${token}`;

환경변수:

UNSUBSCRIBE_SECRET: HMAC 서명 키 (임의 문자열 설정)

4. Vercel 환경변수 현황

변수명	상태	설명
`BREVO_API_KEY`	✅ 설정됨	Brevo API 키
`BREVO_LIST_ID`	✅ 설정됨	구독자 리스트 ID
`TURSO_DB_URL`	✅ 설정됨	Turso DB URL
`TURSO_DB_TOKEN`	✅ 설정됨	Turso 인증 토큰
`INTERNAL_API_KEY`	⚠️ 미설정	뉴스레터 발송 API 인증
`UNSUBSCRIBE_SECRET`	⚠️ 미설정	수신거부 HMAC 키

CEO 단일 액션: Vercel Protection 해제 → 전체 사이트 즉시 라이브

5. 뉴스레터 발송 절차

newsletter_issues 테이블에 draft 등록 (SQL 또는 Admin 페이지)
구독자 모집 (koreaaihub.kr 뉴스레터 폼)
CEO Vercel Protection 해제 후 사이트 라이브
POST /api/newsletter/send?id={id} 호출 (x-api-key 헤더)
발송 완료 확인 (status → 'sent')