API Attributions

Créez et gérez des attributions de badges (assertions) — badges délivrés à des destinataires spécifiques.

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

Créer une attribution

Délivre un badge à un destinataire.

POST /awards

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	ID du badge à attribuer
recipient	object	Oui	Détails du destinataire (voir ci-dessous)
recipient.name	string	Oui	Nom complet du destinataire (minimum 5 caractères)
recipient.email	string	Oui	Adresse e-mail du destinataire
issuedOn	string	Oui	Date d'émission au format ISO 8601 (par ex. 2025-01-15)
expires	string	Non	Date d'expiration au format ISO 8601
blockchain	string	Non	Blockchain pour la vérification on-chain. Seul matchain est pris en charge. Disponible avec le forfait Pro.

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

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

Notes

• Compte pour une attribution dans votre quota mensuel (Free : 100/mois, Starter : 1 000/mois, Pro : 10 000/mois). Le quota est réinitialisé à chaque période de facturation.
• Le paramètre blockchain n'est disponible que sur le forfait Pro.

---

Lister les attributions

Récupère les attributions avec filtrage et pagination optionnels.

GET /awards

Paramètres de query

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	Filtre par ID de badge.
search	string	Sous-chaîne à rechercher dans les noms ou e-mails des destinataires (voir searchField).
searchField	string	Soit name (par défaut) soit email — la colonne dans laquelle chercher.

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

Exemple — lister toutes les attributions

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

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

Si lastEvaluatedKey est présent dans la réponse, il existe d'autres résultats. Passez-le en query parameter dans la requête suivante pour obtenir la page suivante.

---

Envoyer l'e-mail d'attribution

Envoie une notification par e-mail au destinataire pour son attribution.

POST /awards/{awardId}/send

Paramètres

Paramètre	Type	Obligatoire	Description
awardId	string	Oui	ID de l'attribution (paramètre de chemin et corps)
email	string	Oui	Adresse e-mail du destinataire

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

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

---

Partager une attribution

Partage une attribution avec plusieurs destinataires par e-mail.

POST /awards/{awardId}/share

Paramètres

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

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

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

---

Télécharger le certificat PDF

Génère un certificat PDF A4 prêt à imprimer pour une attribution.

GET /awards/{awardGuid}/pdf

Aucune authentification requise — cet endpoint est public pour que les destinataires puissent télécharger leur propre certificat.

Exemple

curl -OJ https://api.badges.ninja/awards/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'attribution

Enregistre un événement d'engagement (vue, partage, téléchargement, ajout LinkedIn). Utilisé par la page publique d'attribution pour alimenter les statistiques d'engagement. Aucune authentification requise.

POST /awards/{awardGuid}/event

Paramètres

Paramètre	Type	Obligatoire	Description
kind	string	Oui	Une des valeurs view, share, download, linkedin_add.
network	string	Non	Quand kind=share, le réseau social : linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Suppression des doublons par IP : le même kind depuis la même IP n'est compté qu'une fois par 24 heures.

Exemple

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

---

Obtenir les stats d'une attribution

Récupère les compteurs d'engagement cumulés pour une attribution.

GET /awards/{awardGuid}/stats

Aucune authentification requise.

Réponse

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