Bevis-API

Opret og administrér beviser (assertions) — badges udstedt til specifikke modtagere.

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

Opret bevis

Udsted en badge til en modtager.

Har du brug for at udstede til hundredvis eller tusindvis af modtagere på én gang i stedet for ét API-kald pr. person? Brug UI-funktionen Masseudstedelse af beviser, som accepterer en CSV-upload.

POST /awards

Parametre

Parameter	Type	Påkrævet	Beskrivelse
badgeId	string	Ja	ID på den badge, der skal udstedes
recipient	object	Ja	Oplysninger om modtageren (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

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

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

Noter

• Tæller som ét bevis i din årlige bevispulje (Free: 1.200/år, Starter: 12.000/år, Pro: 120.000/år). Puljen er en fleksibel årlig ramme — brug den, når du vil i løbet af året, også i bursts — og nulstilles på årsdagen for din kontos registrering. Faktureringen forbliver månedlig; kun beviskvoten er årlig. Se Planer og fakturering for detaljer.

---

Vis beviser

Hent beviser 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 badge-ID.
search	string	Delstreng, der slås op i enten modtagernavne eller e-mailadresser (se searchField).
searchField	string	Enten name (standard) eller email — hvilken kolonne der søges i.

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

Eksempel — vis alle beviser

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

Eksempel — filtrér efter 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"

Svar

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "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 er til stede i svaret, er der flere resultater. Send den som forespørgselsparameter i den næste forespørgsel for at hente næste side.

---

Send bevis-e-mail

Send en e-mailnotifikation til en modtager om vedkommendes bevis.

POST /awards/{awardId}/send

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Bevis-ID'et (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

Returnerer en ren bekræftelsesstreng:

"email sent"

---

Del bevis

Del et bevis med flere modtagere via e-mail.

POST /awards/{awardId}/share

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Bevis-ID'et (stiparameter og body)
recipients	string	Ja	Kommasepareret liste over e-mailadresser
subject	string	Ja	E-mailens emnelinje
message	string	Ja	E-mailens brødtekst

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

Returnerer en ren bekræftelsesstreng:

"email sent"

---

Tilbagekald bevis

Tilbagekald et bevis, du har udstedt. Den hostede Open Badges v2.0-assertion markeres med revoked: true (med en valgfri begrundelse), så enhver verifikator kan se, at badgen ikke længere er gyldig. Bevisposten bevares til revisionsformål, og der refunderes ingen kredit.

Tilbagekaldelsen forplanter sig også til bevisets Open Badges 3.0 Verifiable Credential: bevisets bit vendes i W3C Bitstring Status List, som VC'ens credentialStatus henviser til, så VC-wallets også opdager det. Se Tilbagekaldelse (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Bevis-ID'et (stiparameter)
reason	string	Nej	Begrundelse for tilbagekaldelsen. Afkortes til 500 tegn.
notify	boolean	Nej	Når true, sender den en e-mail til modtageren om, at vedkommendes bevis er tilbagekaldt. Standard er false.

Eksempel

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Svar

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Tilbagekaldelse af et allerede tilbagekaldt bevis er idempotent — det returnerer det samme svar uden at sende en ny notifikation.

Tilbagekald i bulk

For at tilbagekalde mange beviser på én gang skal du bruge det varige bulk-endepunkt med action: "revoke" i stedet for at kalde dette endepunkt pr. bevis:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Det returnerer { "jobId", "total" }; jobbet tilbagekalder hvert ID på serversiden (og springer allerede tilbagekaldte over) og kan genoptages. Allerede tilbagekaldte og ikke-eksisterende ID'er rapporteres som sprunget over.

---

Slet bevis

Slet et bevis, du har udstedt, permanent. I modsætning til tilbagekaldelse fjerner dette posten helt, og den offentlige bevisside returnerer 404. Brug det til reelle fejl (f.eks. udstedt til den forkerte person); foretræk tilbagekaldelse for rigtige beviser, så assertionen forbliver verificerbar som tilbagekaldt. Der refunderes ingen kredit.

DELETE /awards/{awardId}

Parametre

Parameter	Type	Påkrævet	Beskrivelse
awardId	string	Ja	Bevis-ID'et (stiparameter)

Eksempel

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Svar

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Download PDF-certifikat

Generér et printklart A4-PDF-certifikat for et bevis.

GET /certify-badge/award/{awardGuid}/pdf

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

Eksempel

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

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

---

Spor bevishændelse

Registrér en engagementshændelse. Bruges af den offentlige bevisside til at udfylde engagementsstatistik. Ingen godkendelse påkrævet.

POST /certify-badge/award/{awardGuid}/event

Parametre

Dette endepunkt læser sin body direkte (uden parameters-wrapper).

Parameter	Type	Påkrævet	Beskrivelse
event	string	Ja	Én af view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nej	Ved event=share det sociale netværk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Undertrykkelse af dubletter pr. IP: den samme hændelse fra den samme IP tælles én gang pr. 24 timer.

Eksempel

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

Svar

{
  "ok": true
}

---

Hent bevisstatistik

Hent kumulative engagementstællere for et bevis.

GET /certify-badge/award/{awardGuid}/stats

Ingen godkendelse påkrævet.

Svar

Tællere returneres nøglet efter den rå hændelsestype. totals indeholder det samlede antal pr. hændelse; networks viser fordelingen pr. netværk for hændelser, der har et network (i øjeblikket share). Hændelser uden registreret aktivitet udelades simpelthen.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}