Credentials API

Gumawa at pamahalaan ang mga kredensyal (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 Kredensyal

Mag-isyu ng badge sa tatanggap.

POST /awards

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
badgeId	string	Oo	Ang badge ID na i-isyu
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

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 kredensyal laban sa inyong buwanang quota (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Nagre-reset ang quota bawat billing period.

---

Ilista ang mga Kredensyal

Kunin ang mga kredensyal 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 Kredensyal

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 Email ng Kredensyal

Magpadala ng email notification sa tatanggap tungkol sa kanilang kredensyal.

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 Kredensyal

Ibahagi ang kredensyal 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 kredensyal.

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 Event ng Kredensyal

Itala ang isang engagement event (view, share, download, LinkedIn add). Ginagamit ng public na page ng kredensyal 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 Stats ng Kredensyal

Kunin ang cumulative engagement counters para sa kredensyal.

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