Next.js에서 카카오 알림톡 보내기 (Solapi 연동 가이드)

# Solapi 알림톡 설정
SOLAPI_API_KEY=NCSXXXXXXXXXXXXXXXX
SOLAPI_API_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SOLAPI_SENDER_PHONE=01012345678
SOLAPI_PF_ID=KA01PF_XXXXXXXXXXXX

# 알림톡 템플릿 코드
SOLAPI_TEMPLATE_WELCOME=KA01TP_XXXX
SOLAPI_TEMPLATE_PAYMENT_COMPLETE=KA01TP_XXXX
SOLAPI_TEMPLATE_NOTIFICATION=KA01TP_XXXX

import crypto from "crypto";

const SOLAPI_API_URL = "https://api.solapi.com/messages/v4/send";

/** 승인된 알림톡 템플릿 코드 */
export const TEMPLATES = {
  WELCOME: process.env.SOLAPI_TEMPLATE_WELCOME ?? "",
  PAYMENT_COMPLETE:
    process.env.SOLAPI_TEMPLATE_PAYMENT_COMPLETE ?? "",
  NOTIFICATION:
    process.env.SOLAPI_TEMPLATE_NOTIFICATION ?? "",
} as const;

interface AlimtalkResult {
  success: boolean;
  messageId?: string;
  error?: string;
}

function getAuthHeader(): string {
  const apiKey = process.env.SOLAPI_API_KEY;
  const apiSecret = process.env.SOLAPI_API_SECRET;

  if (!apiKey || !apiSecret) {
    throw new Error(
      "솔라피 API 키가 설정되지 않았습니다."
    );
  }

  const date = new Date().toISOString();
  const salt = crypto.randomBytes(32).toString("hex");
  const signature = crypto
    .createHmac("sha256", apiSecret)
    .update(date + salt)
    .digest("hex");

  return `HMAC-SHA256 apiKey=${apiKey}, date=${date}, salt=${salt}, signature=${signature}`;
}

/** 알림톡 발송 */
export async function sendAlimtalk(params: {
  to: string;
  templateId: string;
  variables: Record<string, string>;
}): Promise<AlimtalkResult> {
  try {
    const response = await fetch(SOLAPI_API_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: getAuthHeader(),
      },
      body: JSON.stringify({
        message: {
          to: params.to.replace(/-/g, ""),
          from: process.env.SOLAPI_SENDER_PHONE,
          kakaoOptions: {
            pfId: process.env.SOLAPI_PF_ID,
            templateId: params.templateId,
            variables: params.variables,
          },
        },
      }),
    });

    const data = await response.json();

    if (response.ok) {
      return {
        success: true,
        messageId: data.groupId,
      };
    }

    return {
      success: false,
      error:
        data.errorMessage
        ?? data.message
        ?? "발송 실패",
    };
  } catch (err) {
    const message =
      err instanceof Error
        ? err.message
        : "알 수 없는 오류";
    return { success: false, error: message };
  }
}

import { NextRequest, NextResponse } from "next/server";
import {
  sendAlimtalk,
  TEMPLATES,
} from "@/lib/alimtalk/solapi";

export async function POST(req: NextRequest) {
  const { to, type, variables } = await req.json();

  // 입력 검증
  if (!to || !type) {
    return NextResponse.json(
      { error: "to와 type이 필요합니다." },
      { status: 400 }
    );
  }

  // 템플릿 코드 매핑
  const templateId =
    TEMPLATES[type as keyof typeof TEMPLATES];

  if (!templateId) {
    return NextResponse.json(
      { error: "유효하지 않은 템플릿 타입입니다." },
      { status: 400 }
    );
  }

  const result = await sendAlimtalk({
    to,
    templateId,
    variables: variables ?? {},
  });

  if (!result.success) {
    return NextResponse.json(
      { error: result.error },
      { status: 500 }
    );
  }

  return NextResponse.json({
    success: true,
    messageId: result.messageId,
  });
}

// 결제 완료 후 알림톡 발송 예시
const response = await fetch("/api/alimtalk", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    to: "010-1234-5678",
    type: "PAYMENT_COMPLETE",
    variables: {
      "#{고객명}": "홍길동",
      "#{상품명}": "Pro 플랜 월간 구독",
      "#{결제금액}": "29,000원",
    },
  }),
});

// 회원가입 환영 템플릿
안녕하세요, #{고객명}님! 🎉
#{서비스명}에 가입해주셔서 감사합니다.

지금 바로 시작해보세요:
#{서비스URL}

// 결제 완료 템플릿
#{고객명}님, 결제가 완료되었습니다.

상품명: #{상품명}
결제금액: #{결제금액}
결제일: #{결제일}

영수증 확인: #{영수증URL}

// 구독 갱신 알림 템플릿
#{고객명}님, 구독이 곧 갱신됩니다.

플랜: #{플랜명}
갱신일: #{갱신일}
결제금액: #{결제금액}

구독 관리: #{관리URL}

// SMS 대체 발송이 포함된 확장 버전
const response = await fetch(SOLAPI_API_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: getAuthHeader(),
  },
  body: JSON.stringify({
    message: {
      to: phone,
      from: process.env.SOLAPI_SENDER_PHONE,
      kakaoOptions: {
        pfId: process.env.SOLAPI_PF_ID,
        templateId: templateId,
        variables: variables,
      },
    },
    // 알림톡 실패 시 SMS로 대체 발송
    agent: {
      appId: "ShipFast KR",
    },
  }),
});

src/
├── lib/
│   └── alimtalk/
│       └── solapi.ts          # Solapi 클라이언트 + 인증 + 발송
├── app/
│   └── api/
│       └── alimtalk/
│           └── route.ts       # 알림톡 발송 API Route
└── .env.local                 # API 키 + 템플릿 코드 (git 커밋 금지)