연동 구조

브라우저는 연동 서버를 호출하고, 연동 서버만 써티 API 키를 사용합니다. 아래 파일명은 Node.js·Next.js 예시이며 같은 원칙을 다른 서버 언어에도 적용할 수 있습니다.

1 · 플랫폼 화면홈페이지·LMS·앱

연동 서버의 API만 호출합니다. 써티 API 키는 알지 못합니다.

2 · 연동 서버기존 서비스의 서버

권한을 확인하고 환경 변수의 키로 써티 API를 호출합니다.

3 · 써티 API써티

프로그램·배지·발급 작업·발급된 배지 데이터를 반환합니다.

내부 DB · 선택 사항

필요하면 플랫폼 사용자·프로그램 ID와 써티 리소스 ID의 연결 정보를 저장합니다.

백그라운드 작업

발급 요청, 상태 재확인, 대량 처리는 큐나 스케줄러에서 처리합니다.

비밀 저장소

CERTI_API_KEY는 서버 환경 변수나 클라우드 Secret Manager에 보관합니다.

만들 파일역할호출 위치
.envAPI 키 저장서버 런타임만
lib/certi.js인증·오류 처리 공통 함수서버 API와 작업 큐
app/api/…/route.js화면에 필요한 데이터만 가공브라우저·LMS
jobs/…발급 요청·상태 확인·대량 처리큐·스케줄러
lib/certi.js · Node.js 예시
// lib/certi.js — 서버에서만 사용합니다.
const BASE_URL = "https://api.certi.world/public/v2";

export async function certi(path, options = {}) {
  const response = await fetch(`https://api.certi.world/public/v2${path}`, {
    ...options,
    headers: {
      "X-API-KEY": process.env.CERTI_API_KEY,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const result = await response.json();
  if (!response.ok) {
    throw new Error(`${result.error?.code ?? response.status}: ${result.error?.message ?? "Certi API request failed"}`);
  }
  return result.data;
}