API Badges

Gérez les modèles de badge — les certifications que vous attribuez aux destinataires.

Tous les endpoints nécessitent une authentification via l'en-tête X-Api-Key. Voir Authentification.

Créer un badge

Crée un nouveau badge sous un émetteur vérifié.

POST /badges

Paramètres

Paramètre	Type	Obligatoire	Description
name	string	Oui	Titre du badge
description	string	Oui	Ce que représente le badge
criteria	string	Oui	Ce que le destinataire a fait pour l'obtenir
image	string	Oui	Image encodée en Base64 (PNG ou JPG)
issuerId	string	Oui	ID de l'émetteur vérifié

Exemple

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Réponse

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
  }
}

Notes

• L'émetteur doit être vérifié avant de créer des badges.
• L'image est envoyée sur IPFS pour un stockage permanent.

---

Lister les badges

Récupère tous les badges que vous avez créés.

GET /badges

Exemple

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

Réponse

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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..." },
        "image": "https://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Mettre à jour un badge

Met à jour un badge existant. Seuls les champs fournis sont modifiés.

PUT /badges/{badgeId}

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	ID du badge (paramètre de chemin)
name	string	Non	Nouveau titre
description	string	Non	Nouvelle description
criteria	string	Non	Nouveaux critères
image	string	Non	Nouvelle image encodée en Base64

Exemple

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Réponse

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "updated": true
  }
}

---

Mettre à jour le texte de partage

Définit le texte personnalisé affiché lorsque les destinataires partagent ce badge sur les réseaux sociaux.

PUT /badges/{badgeId}/share-text

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	ID du badge (paramètre de chemin)
text	string	Oui	Texte de partage (pas de HTML)

Exemple

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Réponse

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

---

Supprimer un badge

Supprime un badge. Le badge ne doit pas avoir d'attributions.

DELETE /badges/{badgeId}

Exemple

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse

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

Erreurs

• 400 — le badge a des attributions et ne peut pas être supprimé
• 404 — badge introuvable