Verificació pública

Aquests endpoints són públics i no requereixen autenticació. Permeten a qualsevol persona verificar credencials d'insígnies i obtenir dades JSON d'Open Badge v2.0.

Tots els endpoints són relatius a https://api.badges.ninja.

Obtenir un emissor

Obtén el JSON del perfil d'emissor (Issuer Profile) d'Open Badge v2.0 per a un emissor determinat.

GET /certify-badge/issuer/{guid}

Exemple

curl https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Resposta

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Issuer",
  "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "name": "Acme Academy",
  "url": "https://acme.example.com",
  "email": "badges@acme.example.com",
  "verification": {
    "type": "hosted",
    "allowedOrigins": "api.badges.ninja"
  }
}

---

Obtenir una insígnia

Obtén el JSON BadgeClass d'Open Badge v2.0 per a una insígnia determinada.

GET /certify-badge/badge/{guid}

Exemple

curl https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901

Resposta

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "BadgeClass",
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": {
    "narrative": "Completed the JavaScript Fundamentals course with a score of 80% or higher"
  },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-..."
}

---

Obtenir una credencial

Obtén el JSON Assertion d'Open Badge v2.0 per a una credencial determinada.

GET /certify-badge/award/{guid}

Exemple

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

Resposta

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
  "recipient": {
    "type": "email",
    "hashed": true,
    "identity": "sha256$..."
  },
  "badge": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "issuedOn": "2025-01-15T00:00:00.000Z",
  "verification": {
    "type": "hosted"
  },
  "revoked": false
}

Si la credencial s'ha revocat, l'assertion inclou "revoked": true i, quan s'ha indicat un motiu, una cadena "revocationReason":

{
  "revoked": true,
  "revocationReason": "Issued in error"
}

Aquesta és la visió de la revocació segons Open Badges 2.0. La mateixa revocació també s'expressa en el Verifiable Credential d'Open Badges 3.0 de la credencial — consulta Revocació (Bitstring Status List).

Notes

• El correu electrònic del destinatari es xifra amb un hash (SHA-256) per privadesa, seguint l'especificació d'Open Badge.
• Les respostes es guarden a la memòria cau durant 5 minuts (Cache-Control: public, max-age=300). Les credencials revocades utilitzen una memòria cau més curta de 30 segons (max-age=30) perquè la revocació es propagui ràpidament.

---

Obtenir el text per compartir d'una credencial

Obtén el text personalitzat per compartir de la insígnia d'una credencial.

GET /certify-badge/award/{guid}/share-text

Exemple

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

Resposta

{
  "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
}

Si no s'ha definit cap text personalitzat per compartir, es retorna un missatge per defecte.

---

Enviar el correu d'una credencial (públic)

Envia un correu de notificació d'una credencial des de l'endpoint públic. S'utilitza a la pàgina pública per compartir.

POST /certify-badge/award/{guid}/send-email

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
recipients	string	Sí	Llista d'adreces de correu separades per comes
message	string	No	Missatge personalitzat que s'inclou al correu

Exemple

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "recipients": "colleague@example.com",
      "message": "Check out this badge!"
    }
  }'

Resposta

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

Aquest és l'únic endpoint que embolcalla el resultat en un sobre { "statusCode", "info" }. Tots els altres endpoints retornen les dades directament.

---

Verificar un emissor

Verifica un emissor fent clic a l'enllaç de verificació enviat al correu de l'emissor. Normalment s'hi accedeix des de l'enllaç del correu de verificació, no es crida directament.

GET /certify-badge/verify-issuer/{guid}/{code}

Paràmetres

Paràmetre	Tipus	Descripció
guid	string	El GUID de l'emissor
code	string	El codi de verificació

Resposta

Retorna una pàgina HTML que confirma si la verificació ha anat bé o ha fallat. Aquest endpoint està pensat per obrir-se en un navegador.