수여 API

배지 수여(어서션) 생성 및 관리 — 특정 수령자에게 발급된 배지를 다룹니다.

모든 엔드포인트는 X-Api-Key 헤더를 통한 인증이 필요합니다. 인증 을 참고하세요.

수여 생성

수령자에게 배지를 발급합니다.

POST /awards

파라미터

파라미터	타입	필수	설명
badgeId	string	예	수여할 배지 ID
recipient	object	예	수령자 세부정보(아래 참조)
recipient.name	string	예	수령자 전체 이름(최소 5자)
recipient.email	string	예	수령자 이메일 주소
issuedOn	string	예	ISO 8601 형식의 발급일(예: 2025-01-15)
expires	string	아니요	ISO 8601 형식의 만료일
blockchain	string	아니요	온체인 검증용 블록체인. matchain 만 지원. Pro 요금제에서 사용 가능.

예시

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

응답

{
  "statusCode": 200,
  "info": {
    "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
  }
}

참고

• 월간 할당량에서 1건이 차감됩니다(Free: 100/월, Starter: 1,000/월, Pro: 10,000/월). 할당량은 결제 주기마다 재설정됩니다.
• blockchain 파라미터는 Pro 요금제에서만 사용할 수 있습니다.

---

수여 목록

선택적 필터링과 페이지네이션으로 수여를 가져옵니다.

GET /awards

쿼리 파라미터

파라미터	타입	필수	설명
filter	JSON string	아니요	필터 객체(아래 참조)
lastEvaluatedKey	string	아니요	이전 응답의 페이지네이션 토큰

필터 객체

filter 파라미터는 다음 필드를 가진 JSON 문자열을 받습니다.

필드	타입	설명
badgeId	string	배지 ID로 필터링.
search	string	수령자 이름 또는 이메일에서 검색할 부분 문자열(참조: searchField).
searchField	string	name(기본) 또는 email — 검색할 컬럼.

lastEvaluatedKey 기반 페이지네이션은 필터 유무와 관계없이 작동합니다. 페이지 크기는 50입니다.

예시 — 모든 수여 목록

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

예시 — 배지로 필터링

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

응답

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "recipient": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        },
        "issuedOn": "2025-01-15T00:00:00.000Z",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ],
    "lastEvaluatedKey": "eyJ..."
  }
}

응답에 lastEvaluatedKey 가 있으면 더 많은 결과가 있는 것입니다. 다음 요청의 쿼리 파라미터로 전달하면 다음 페이지를 가져올 수 있습니다.

---

수여 이메일 보내기

수령자에게 수여에 대한 이메일 알림을 보냅니다.

POST /awards/{awardId}/send

파라미터

파라미터	타입	필수	설명
awardId	string	예	수여 ID(경로 파라미터와 본문)
email	string	예	수령자 이메일 주소

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

응답

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

수여 공유

이메일로 여러 수령자에게 수여를 공유합니다.

POST /awards/{awardId}/share

파라미터

파라미터	타입	필수	설명
awardId	string	예	수여 ID(경로 파라미터와 본문)
recipients	string	예	쉼표로 구분한 이메일 목록
subject	string	예	이메일 제목
message	string	예	이메일 본문

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

응답

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

PDF 인증서 다운로드

수여를 위한 인쇄 가능한 A4 PDF 인증서를 생성합니다.

GET /awards/{awardGuid}/pdf

인증 불필요 — 이 엔드포인트는 공개되어 수령자가 자신의 인증서를 다운로드할 수 있습니다.

예시

curl -OJ https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

응답은 Content-Type: application/pdf 헤더의 바이너리 PDF입니다.

---

수여 이벤트 기록

참여 이벤트(조회, 공유, 다운로드, LinkedIn 추가)를 기록합니다. 공개 수여 페이지가 참여 통계를 채우는 데 사용합니다. 인증은 필요하지 않습니다.

POST /awards/{awardGuid}/event

파라미터

파라미터	타입	필수	설명
kind	string	예	view, share, download, linkedin_add 중 하나.
network	string	아니요	kind=share 일 때 소셜 네트워크: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP별 중복 억제: 같은 IP에서 같은 kind 는 24시간에 한 번 계산됩니다.

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"kind": "share", "network": "linkedin"}}'

---

수여 통계 가져오기

수여의 누적 참여 카운터를 가져옵니다.

GET /awards/{awardGuid}/stats

인증은 필요하지 않습니다.

응답

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}