Udmærkelses-API

Opret og administrér mærkeudmærkelser (assertions) — mærker udstedt til specifikke modtagere.

Alle endpoints kræver godkendelse via X-Api-Key-headeren. Se Godkendelse.

Opret udmærkelse

Udsted et mærke til en modtager.

POST /awards

Parametre

Parameter	Type	Påkrævet	Beskrivelse
badgeId	string	Ja	Mærke-ID, der skal uddeles
recipient	object	Ja	Modtagerdetaljer (se nedenfor)
recipient.name	string	Ja	Modtagerens fulde navn (mindst 5 tegn)
recipient.email	string	Ja	Modtagerens e-mailadresse
issuedOn	string	Ja	Udstedelsesdato i ISO 8601-format (f.eks. 2025-01-15)
expires	string	Nej	Udløbsdato i ISO 8601-format
blockchain	string	Nej	Blockchain til on-chain-verificering. Kun matchain understøttes. Tilgængelig i Pro-planen.

Eksempel

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

Svar

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

Bemærkninger

• Tæller som én udmærkelse mod din månedskvote (Free: 100/md, Starter: 1.000/md, Pro: 10.000/md). Kvoten nulstilles hver faktureringsperiode.
• Parameteren blockchain er kun tilgængelig i Pro-planen.

---

Liste udmærkelser

Hent udmærkelser med valgfri filtrering og paginering.

GET /awards

Forespørgselsparametre

Parameter	Type	Påkrævet	Beskrivelse
filter	JSON-streng	Nej	Filterobjekt (se nedenfor)
lastEvaluatedKey	string	Nej	Pagineringstoken fra et tidligere svar

Filterobjekt

Parameteren filter accepterer en JSON-streng med disse felter:

Felt	Type	Beskrivelse
badgeId	string	Filtrér efter mærke-ID.
search	string	Delstreng, der skal slås op i enten modtagernavne eller e-mails (se searchField).
searchField	string	Enten name (standard) eller email — hvilken kolonne der skal søges.

Paginering via lastEvaluatedKey fungerer med eller uden filtre. Sidestørrelsen er 50.

Eksempel — Liste alle udmærkelser

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

Eksempel — Filtrér efter mærke

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"

Svar

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

Hvis lastEvaluatedKey findes i svaret, er der flere resultater. Send den som en forespørgselsparameter i næste forespørgsel for at få næste side.

---

Send udmærkelses-e-mail

Send en e-mailnotifikation til en modtager om deres udmærkelse.

POST /awards/{awardId}/send

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Udmærkelses-ID (stiparameter og body)
email	string	Ja	Modtagerens e-mailadresse

Eksempel

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

Svar

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

---

Del udmærkelse

Del en udmærkelse med flere modtagere via e-mail.

POST /awards/{awardId}/share

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Udmærkelses-ID (stiparameter og body)
recipients	string	Ja	Kommaadskilt liste med e-mailadresser
subject	string	Ja	E-mailens emne
message	string	Ja	E-mailens beskedtekst

Eksempel

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

Svar

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

---

Download PDF-certifikat

Generér et trykklart A4-PDF-certifikat for en udmærkelse.

GET /awards/{awardGuid}/pdf

Ingen godkendelse påkrævet — dette endpoint er offentligt, så modtagere kan downloade deres eget certifikat.

Eksempel

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

Svaret er den binære PDF med en Content-Type: application/pdf-header.

---

Spor udmærkelseshændelse

Registrér en engagementshændelse (visning, deling, download, LinkedIn-tilføjelse). Bruges af den offentlige udmærkelsesside til at udfylde engagementsstatistik. Ingen godkendelse påkrævet.

POST /awards/{awardGuid}/event

Parametre

Parameter	Type	Påkrævet	Beskrivelse
kind	string	Ja	En af view, share, download, linkedin_add.
network	string	Nej	Når kind=share, det sociale netværk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Duplikat-undertrykkelse pr. IP: samme kind fra samme IP tælles én gang pr. 24 timer.

Eksempel

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

---

Hent udmærkelsesstatistik

Hent kumulative engagementstællere for en udmærkelse.

GET /awards/{awardGuid}/stats

Ingen godkendelse påkrævet.

Svar

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