일괄 자격 증명

일괄 자격 증명을 사용하면 CSV 파일을 업로드해 수백 또는 수천 명의 수령자에게 한 번에 배지를 발급할 수 있어요. 프로세스는 4단계이며 진행률 추적, 일시 정지/재개, 오류 처리가 기본으로 제공돼요.

개요

일괄 자격 증명 프로세스는 다음 4단계로 진행돼요.

1. 구성 — 배지와 옵션 선택
2. 업로드 — CSV 파일 준비 및 업로드
3. 처리 — 자격 증명이 생성되는 진행 상황 모니터링
4. 결과 — 결과 검토 및 보고서 다운로드

1단계: 구성

1. 사이드바에서 일괄 자격 증명 페이지를 열어요 (자격 증명 페이지와는 별도의 경로예요).
2. 배지 선택기로 발급할 배지를 선택해요.
3. 필요하면 다음을 설정해요.
   • 발급일 — 모든 자격 증명에 사용할 날짜 (기본값은 오늘)
   • 만료일 — 모든 자격 증명에 적용할 선택적 만료일
   • 이메일 전송 — 자격 증명이 생성된 후 각 수령자에게 자동으로 이메일을 보낼지 여부
4. 다음을 클릭해요.

2단계: CSV 업로드

CSV 형식

CSV 파일에는 헤더 행과 함께 name 열과 email 열이 있어야 해요. 헤더 이름은 대소문자를 구분하지 않으며, recipient_name / recipient_email을 name / email의 별칭으로 사용할 수 있어요.

name,email
Jane Smith,jane@example.com
John Doe,john@example.com
Maria Garcia,maria@example.com

템플릿 다운로드

Download Template을 클릭하면 올바른 헤더가 들어 있는 빈 CSV 파일을 받을 수 있어요. 수령자 정보를 채운 뒤 업로드하세요.

업로드

1. Upload CSV를 클릭하거나 파일을 끌어다 놓아요.
2. 처리를 시작하기 전에 파일이 검증돼요.

검증 규칙

각 행은 파일이 파싱되는 즉시 검증돼요.

• 이름은 5자 이상이어야 해요
• 이메일은 유효한 이메일 주소여야 해요
• 빈 행은 건너뛰어요

미리 보기 표에는 모든 행이 녹색 체크 표시 또는 빨간색 사유와 함께 나열돼요. 잘못된 행이 있어도 진행을 막지 않아요. 해당 행은 건너뛰기만 되고, 카운터에 처리될 유효한 수령자 수가 표시돼요 (예: "18 valid recipients, 2 invalid (will be skipped)"). 유효한 행이 하나 이상 있으면 진행할 수 있으니, 먼저 수정해서 다시 업로드할 필요는 없어요.

3. 다음을 클릭해 처리를 시작해요.

3단계: 처리

처리가 시작되면 진행률 표시줄과 실시간 카운터가 나타나요.

• 진행률 표시줄 — 처리된 행의 비율
• Created — 생성된 자격 증명 수
• Failed — 실패한 행 수
• Remaining — 대기열에 남은 행 수

배치가 실행되는 동안 표시줄 아래에 실시간 Created, Failed, Pending 표가 채워져요.

일시 정지 및 재개

• Pause를 클릭하면 처리를 일시적으로 멈춰요. 일시 정지 중에는 새 자격 증명이 생성되지 않아요.
• Resume을 클릭하면 멈춘 지점부터 이어서 진행해요.

취소

• Cancel을 클릭하면 처리를 완전히 중단해요. 이미 생성된 자격 증명은 그대로 유지돼요.

오류 처리

백엔드가 거부하는 잘못된 값처럼 특정 행에 한정된 이유로 행이 실패하면:

• 해당 행에 오류가 기록돼요
• 처리는 자동으로 다음 행으로 계속돼요
• 실패한 행은 결과 단계에 모아지며, 오류 텍스트가 화면의 실패 표에 표시돼요

속도 제한에 걸린 행은 짧은 백오프 후 자동으로 재시도돼요. 크레딧 또는 할당량 오류는 달라요. 다음 행으로 넘어가는 대신 배치가 일시 정지되어 파일의 나머지를 소모하지 않도록 해 줘요. 빨간색 "Insufficient credits" 알림이 나타나면 크레딧을 충전하거나 업그레이드한 다음 Resume을 클릭해 멈춘 지점부터 계속하세요.

페이지 새로 고침 복구

처리 중에 실수로 브라우저를 닫거나 페이지를 새로 고쳐도, 돌아오면 일괄 자격 증명 세션이 복구돼요. 진행 상황은 멈춘 지점부터 이어져요.

4단계: 결과

처리가 완료되면(또는 취소되면) 결과 화면에 요약 카드 4개가 표시돼요.

• Total — 배치에 포함된 수령자 수
• Created — 생성된 자격 증명 수
• Failed — 실패한 행 수
• Skipped — 처리되지 않은 수령자 (예: 취소 후 남은 행)

카드 아래에는 새 자격 증명마다 보기 링크가 있는 Created 표와, 오류 텍스트와 함께 실패 내역을 나열한 Failed 표가 있어요.

보고서 다운로드

• Download Results CSV — 배치의 모든 행이며, 열은 row, name, email, status, award_url이에요 (생성된 행에는 자격 증명 URL이 채워져요).
• Download Failures CSV — 실패한 행만 포함하며, 열은 name, email, error예요.

실패 재시도

일부 행이 실패했다면 Retry Failures를 클릭하세요. 실패한 수령자만 대상으로 새로 처리하므로 CSV를 다시 업로드할 필요가 없어요. 일시 정지된 배치 후에 크레딧을 충전하는 것처럼 일시적인 문제를 해결한 뒤에 유용해요.