Awards API

Gumawa at pamahalaan ang mga badge award (assertions) — mga badge na inisyu sa mga partikular na tatanggap.

Lahat ng endpoint ay nangangailangan ng authentication sa pamamagitan ng X-Api-Key header. Tingnan ang Authentication.

Gumawa ng Award

Mag-isyu ng badge sa tatanggap.

POST /awards

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
badgeId	string	Oo	Ang badge ID na ibibigay
recipient	object	Oo	Detalye ng tatanggap (tingnan sa ibaba)
recipient.name	string	Oo	Buong pangalan ng tatanggap (minimum 5 character)
recipient.email	string	Oo	Email address ng tatanggap
issuedOn	string	Oo	Petsa ng pag-isyu sa ISO 8601 format (hal. 2025-01-15)
expires	string	Hindi	Petsa ng pag-expire sa ISO 8601 format
blockchain	string	Hindi	Blockchain para sa on-chain verification. matchain lang ang sinusuportahan. Available sa Pro plan.

Halimbawa

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"
    }
  }'

Response

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

Mga Tala

• Binibilang bilang isang award laban sa inyong buwanang quota (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Nagre-reset ang quota bawat billing period.
• Available lang ang blockchain parameter sa Pro plan.

---

Ilista ang mga Award

Kunin ang mga award na may opsyonal na pag-filter at pagination.

GET /awards

Query Parameters

Parameter	Uri	Kailangan	Paglalarawan
filter	JSON string	Hindi	Filter object (tingnan sa ibaba)
lastEvaluatedKey	string	Hindi	Pagination token mula sa nakaraang response

Filter Object

Tinatanggap ng filter parameter ang JSON string na may mga field na ito:

Field	Uri	Paglalarawan
badgeId	string	I-filter ayon sa badge ID.
search	string	Substring na hahanapin sa alinman sa pangalan o email ng tatanggap (tingnan ang searchField).
searchField	string	Alinman sa name (default) o email — kung anong column ang hahanapin.

Gumagana ang pagination sa pamamagitan ng lastEvaluatedKey na may o walang filter. Ang laki ng pahina ay 50.

Halimbawa — Ilista ang Lahat ng Award

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

Halimbawa — I-filter ayon sa Badge

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"

Response

{
  "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..."
  }
}

Kung naroroon ang lastEvaluatedKey sa response, may higit pang resulta. Ipasa ito bilang query parameter sa susunod na request para makuha ang susunod na pahina.

---

Magpadala ng Award Email

Magpadala ng email notification sa tatanggap tungkol sa kanilang award.

POST /awards/{awardId}/send

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
awardId	string	Oo	Ang award ID (path parameter at body)
email	string	Oo	Email address ng tatanggap

Halimbawa

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"
    }
  }'

Response

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

---

Ibahagi ang Award

Ibahagi ang award sa maraming tatanggap sa pamamagitan ng email.

POST /awards/{awardId}/share

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
awardId	string	Oo	Ang award ID (path parameter at body)
recipients	string	Oo	Listahan ng email address na hinati ng kuwit
subject	string	Oo	Subject line ng email
message	string	Oo	Message body ng email

Halimbawa

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."
    }
  }'

Response

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

---

I-download ang PDF Certificate

Mag-generate ng print-ready A4 PDF certificate para sa award.

GET /awards/{awardGuid}/pdf

Walang authentication na kailangan — ang endpoint na ito ay public para magagawa ng mga tatanggap na i-download ang kanilang sariling certificate.

Halimbawa

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

Ang response ay binary PDF na may Content-Type: application/pdf header.

---

I-track ang Award Event

Itala ang isang engagement event (view, share, download, LinkedIn add). Ginagamit ng public award page para punan ang engagement stats. Walang authentication na kailangan.

POST /awards/{awardGuid}/event

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
kind	string	Oo	Isa sa view, share, download, linkedin_add.
network	string	Hindi	Kapag kind=share, ang social network: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Per-IP duplicate suppression: ang parehong uri mula sa parehong IP ay binibilang minsan kada 24 na oras.

Halimbawa

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"}}'

---

Kunin ang Award Stats

Kunin ang cumulative engagement counters para sa award.

GET /awards/{awardGuid}/stats

Walang authentication na kailangan.

Response

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