API des attestations

Créez et gérez des attestations (assertions) — des badges émis à des bénéficiaires précis.

Tous les points de terminaison exigent une authentification via l'en-tête X-Api-Key. Voir Authentification.

Créer une attestation

Émettre un badge à un bénéficiaire.

Besoin d'émettre à des centaines ou des milliers de bénéficiaires d'un coup plutôt qu'un appel d'API par personne ? Utilisez la fonctionnalité d'interface Attestations en masse, qui accepte l'import d'un fichier CSV.

POST /awards

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	L'ID du badge à émettre
recipient	object	Oui	Détails du bénéficiaire (voir ci-dessous)
recipient.name	string	Oui	Nom complet du bénéficiaire (5 caractères minimum)
recipient.email	string	Oui	Adresse e-mail du bénéficiaire
issuedOn	string	Oui	Date d'émission au format ISO 8601 (p. ex. 2025-01-15)
expires	string	Non	Date d'expiration au format ISO 8601

Exemple

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

Réponse

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

Remarques

• Compte pour une attestation dans votre réserve annuelle d'attestations (Free : 1,200/an, Starter : 12,000/an, Pro : 120,000/an). La réserve est une allocation annuelle flexible — dépensez-la quand vous le souhaitez au fil de l'année, y compris par vagues — et elle se réinitialise à la date anniversaire de l'inscription de votre compte. La facturation reste mensuelle ; seul le quota d'attestations est annuel. Voir Offres et facturation pour plus de détails.

---

Lister les attestations

Récupérez les attestations avec filtrage et pagination facultatifs.

GET /awards

Paramètres de requête

Paramètre	Type	Obligatoire	Description
filter	JSON string	Non	Objet de filtre (voir ci-dessous)
lastEvaluatedKey	string	Non	Jeton de pagination d'une réponse précédente

Objet de filtre

Le paramètre filter accepte une chaîne JSON avec ces champs :

Champ	Type	Description
badgeId	string	Filtrer par ID de badge.
search	string	Sous-chaîne à rechercher dans les noms ou les e-mails des bénéficiaires (voir searchField).
searchField	string	Soit name (par défaut), soit email — la colonne à rechercher.

La pagination via lastEvaluatedKey fonctionne avec ou sans filtres. La taille de page est de 50.

Exemple — lister toutes les attestations

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

Exemple — filtrer par 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"

Réponse

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

Si lastEvaluatedKey est présent dans la réponse, il reste des résultats. Transmettez-le comme paramètre de requête dans la requête suivante pour obtenir la page suivante.

---

Envoyer l'e-mail de l'attestation

Envoyez au bénéficiaire une notification par e-mail concernant son attestation.

POST /awards/{awardId}/send

Paramètres

Paramètre	Type	Obligatoire	Description
awardId	string	Oui	L'ID de l'attestation (paramètre de chemin et corps)
email	string	Oui	Adresse e-mail du bénéficiaire

Exemple

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

Réponse

Renvoie une simple chaîne de confirmation :

"email sent"

---

Partager une attestation

Partagez une attestation par e-mail avec plusieurs destinataires.

POST /awards/{awardId}/share

Paramètres

Paramètre	Type	Obligatoire	Description
awardId	string	Oui	L'ID de l'attestation (paramètre de chemin et corps)
recipients	string	Oui	Liste d'adresses e-mail séparées par des virgules
subject	string	Oui	Objet de l'e-mail
message	string	Oui	Corps du message de l'e-mail

Exemple

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

Réponse

Renvoie une simple chaîne de confirmation :

"email sent"

---

Révoquer une attestation

Révoquez une attestation que vous avez émise. L'assertion Open Badges v2.0 hébergée est marquée revoked: true (avec un motif facultatif) afin que tout vérificateur voie que le badge n'est plus valide. L'enregistrement de l'attestation est conservé à des fins d'audit, et aucun crédit n'est remboursé.

La révocation se propage aussi au Verifiable Credential Open Badges 3.0 de l'attestation : le bit de l'attestation est basculé dans la W3C Bitstring Status List référencée par le credentialStatus du VC, de sorte que les portefeuilles VC la détectent également. Voir Révocation (Bitstring Status List).

POST /awards/{awardId}/revoke

Paramètres

Paramètre	Type	Obligatoire	Description
awardId	string	Oui	L'ID de l'attestation (paramètre de chemin)
reason	string	Non	Motif de la révocation. Tronqué à 500 caractères.
notify	boolean	Non	Si true, informe par e-mail le bénéficiaire que son attestation a été révoquée. false par défaut.

Exemple

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

Réponse

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

Révoquer une attestation déjà révoquée est idempotent — la même réponse est renvoyée, sans renvoyer de notification.

Révoquer en masse

Pour révoquer de nombreuses attestations à la fois, utilisez le point de terminaison de masse durable avec action: "revoke" plutôt que d'appeler ce point de terminaison pour chaque attestation :

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

Il renvoie { "jobId", "total" } ; la tâche révoque chaque ID côté serveur (en ignorant ceux déjà révoqués) et peut être reprise. Les ID déjà révoqués et inexistants sont signalés comme ignorés.

---

Supprimer une attestation

Supprimez définitivement une attestation que vous avez émise. Contrairement à la révocation, cela supprime entièrement l'enregistrement et la page publique de l'attestation renverra 404. À utiliser pour de véritables erreurs (p. ex. émise à la mauvaise personne) ; privilégiez la révocation pour les attestations réelles afin que l'assertion reste vérifiable comme révoquée. Aucun crédit n'est remboursé.

DELETE /awards/{awardId}

Paramètres

Paramètre	Type	Obligatoire	Description
awardId	string	Oui	L'ID de l'attestation (paramètre de chemin)

Exemple

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

Réponse

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

---

Télécharger le certificat PDF

Générez un certificat PDF A4 prêt à imprimer pour une attestation.

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

Aucune authentification requise — ce point de terminaison est public afin que les bénéficiaires puissent télécharger leur propre certificat.

Exemple

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

La réponse est le PDF binaire avec un en-tête Content-Type: application/pdf.

---

Suivre un événement d'attestation

Enregistrez un événement d'engagement. Utilisé par la page publique de l'attestation pour alimenter les statistiques d'engagement. Aucune authentification requise.

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

Paramètres

Ce point de terminaison lit directement son corps (sans enveloppe parameters).

Paramètre	Type	Obligatoire	Description
event	string	Oui	L'une des valeurs view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Non	Lorsque event=share, le réseau social : linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Suppression des doublons par IP : le même événement provenant de la même IP n'est compté qu'une fois par période de 24 heures.

Exemple

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

Réponse

{
  "ok": true
}

---

Obtenir les statistiques d'une attestation

Récupérez les compteurs d'engagement cumulés d'une attestation.

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

Aucune authentification requise.

Réponse

Les compteurs sont renvoyés par type d'événement brut. totals contient le total par événement ; networks détaille la répartition par réseau pour les événements qui portent un network (actuellement share). Les événements sans activité enregistrée sont simplement absents.

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