Awards API

Δημιουργία και διαχείριση απονομών εμβλημάτων (assertions) — εμβλήματα που εκδίδονται σε συγκεκριμένους παραλήπτες.

Όλα τα endpoints απαιτούν πιστοποίηση μέσω της κεφαλίδας X-Api-Key. Δείτε Πιστοποίηση.

Δημιουργία απονομής

Εκδίδει ένα έμβλημα σε έναν παραλήπτη.

POST /awards

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
badgeId	string	Ναι	Το ID του εμβλήματος προς απονομή
recipient	object	Ναι	Στοιχεία παραλήπτη (δείτε παρακάτω)
recipient.name	string	Ναι	Πλήρες όνομα παραλήπτη (τουλάχιστον 5 χαρακτήρες)
recipient.email	string	Ναι	Διεύθυνση email παραλήπτη
issuedOn	string	Ναι	Ημερομηνία έκδοσης σε μορφή ISO 8601 (π.χ. 2025-01-15)
expires	string	Όχι	Ημερομηνία λήξης σε μορφή ISO 8601
blockchain	string	Όχι	Blockchain για επαλήθευση on-chain. Μόνο το matchain υποστηρίζεται. Διαθέσιμο στο πλάνο Pro.

Παράδειγμα

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

Απάντηση

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

Σημειώσεις

• Μετράει ως μία απονομή έναντι του μηνιαίου ορίου σας (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Το όριο μηδενίζεται κάθε περίοδο χρέωσης.
• Η παράμετρος blockchain είναι διαθέσιμη μόνο στο πλάνο Pro.

---

Λίστα απονομών

Ανακτήστε απονομές με προαιρετικό φιλτράρισμα και σελιδοποίηση.

GET /awards

Παράμετροι ερωτήματος

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
filter	JSON string	Όχι	Αντικείμενο φίλτρου (δείτε παρακάτω)
lastEvaluatedKey	string	Όχι	Token σελιδοποίησης από προηγούμενη απάντηση

Αντικείμενο φίλτρου

Η παράμετρος filter δέχεται μια συμβολοσειρά JSON με αυτά τα πεδία:

Πεδίο	Τύπος	Περιγραφή
badgeId	string	Φίλτρο κατά ID εμβλήματος.
search	string	Υποσυμβολοσειρά για αναζήτηση είτε σε ονόματα παραληπτών είτε σε emails (δείτε searchField).
searchField	string	Είτε name (προεπιλογή) είτε email — ποια στήλη να αναζητηθεί.

Η σελιδοποίηση μέσω lastEvaluatedKey λειτουργεί με ή χωρίς φίλτρα. Το μέγεθος σελίδας είναι 50.

Παράδειγμα — Λίστα όλων των απονομών

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

Παράδειγμα — Φίλτρο κατά έμβλημα

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"

Απάντηση

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

Εάν το lastEvaluatedKey είναι παρόν στην απάντηση, υπάρχουν περισσότερα αποτελέσματα. Περάστε το ως παράμετρο ερωτήματος στο επόμενο αίτημα για να λάβετε την επόμενη σελίδα.

---

Αποστολή email απονομής

Στέλνει μια ειδοποίηση μέσω email σε έναν παραλήπτη σχετικά με την απονομή του.

POST /awards/{awardId}/send

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
awardId	string	Ναι	Το ID της απονομής (παράμετρος διαδρομής και body)
email	string	Ναι	Διεύθυνση email παραλήπτη

Παράδειγμα

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

Απάντηση

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

---

Κοινοποίηση απονομής

Μοιραστείτε μια απονομή με πολλαπλούς παραλήπτες μέσω email.

POST /awards/{awardId}/share

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
awardId	string	Ναι	Το ID της απονομής (παράμετρος διαδρομής και body)
recipients	string	Ναι	Λίστα διευθύνσεων email χωρισμένων με κόμμα
subject	string	Ναι	Γραμμή θέματος email
message	string	Ναι	Σώμα μηνύματος email

Παράδειγμα

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

Απάντηση

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

---

Λήψη πιστοποιητικού PDF

Δημιουργεί ένα έτοιμο για εκτύπωση πιστοποιητικό PDF A4 για μια απονομή.

GET /awards/{awardGuid}/pdf

Δεν απαιτείται πιστοποίηση — αυτό το endpoint είναι δημόσιο ώστε οι παραλήπτες να μπορούν να κατεβάσουν το δικό τους πιστοποιητικό.

Παράδειγμα

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

Η απάντηση είναι το δυαδικό PDF με κεφαλίδα Content-Type: application/pdf.

---

Παρακολούθηση συμβάντος απονομής

Καταγράφει ένα συμβάν αφοσίωσης (view, share, download, LinkedIn add). Χρησιμοποιείται από τη δημόσια σελίδα απονομής για τη συμπλήρωση στατιστικών αφοσίωσης. Δεν απαιτείται πιστοποίηση.

POST /awards/{awardGuid}/event

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
kind	string	Ναι	Ένα από view, share, download, linkedin_add.
network	string	Όχι	Όταν kind=share, το κοινωνικό δίκτυο: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Καταστολή διπλοτύπων ανά IP: το ίδιο kind από το ίδιο IP μετράει μία φορά ανά 24 ώρες.

Παράδειγμα

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

---

Λήψη στατιστικών απονομής

Ανακτά τους αθροιστικούς μετρητές αφοσίωσης για μια απονομή.

GET /awards/{awardGuid}/stats

Δεν απαιτείται πιστοποίηση.

Απάντηση

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