Credentials 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

Παράδειγμα

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). Το όριο μηδενίζεται κάθε περίοδο χρέωσης.

---

Λίστα διαπιστευτηρίων

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

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