Αναφορά API ψηφιακών σημάτων: δημιουργία, επαλήθευση και ανάκτηση

Διαχειριστείτε τα πρότυπα ψηφιακών σημάτων — τα διαπιστευτήρια που εκδίδετε στους παραλήπτες.

Για να εκδώσετε αυτό το ψηφιακό σήμα σε πολλούς παραλήπτες ταυτόχρονα μέσω μεταφόρτωσης CSV αντί για το API, δείτε Μαζικά διαπιστευτήρια.

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

Δημιουργία ψηφιακού σήματος

Δημιουργήστε ένα νέο ψηφιακό σήμα υπό έναν επαληθευμένο εκδότη.

POST /badges

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτική	Περιγραφή
name	string	Ναι	Τίτλος του ψηφιακού σήματος
description	string	Ναι	Τι αντιπροσωπεύει το ψηφιακό σήμα
criteria	string	Ναι	Τι έκανε ο παραλήπτης για να κερδίσει αυτό το ψηφιακό σήμα
image	string	Ναι	Εικόνα κωδικοποιημένη σε Base64 (PNG ή JPG)
issuerId	string	Ναι	Το ID του επαληθευμένου εκδότη
shareText	string	Όχι	Προεπιλεγμένο κείμενο κοινοποίησης στα κοινωνικά δίκτυα για αυτό το ψηφιακό σήμα. Υποστηρίζει τα placeholders , και . Αν παραλειφθεί, χρησιμοποιείται μια ενσωματωμένη προεπιλογή.
designJson	string	Όχι	Σειριοποιημένο έγγραφο του σχεδιαστή ψηφιακών σημάτων, το οποίο αποθηκεύεται ώστε το ψηφιακό σήμα να μπορεί να επεξεργαστεί ξανά στρώμα προς στρώμα αργότερα.

Παράδειγμα

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

Απάντηση

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

Σημειώσεις

• Ο εκδότης πρέπει να είναι επαληθευμένος πριν από τη δημιουργία ψηφιακών σημάτων.
• Η εικόνα αποθηκεύεται στο Amazon S3 και διανέμεται μέσω του παγκόσμιου CDN μας με αμετάβλητο URL βασισμένο στο περιεχόμενο.
• Μόλις υπάρξει μια κλάση ψηφιακού σήματος, εκδώστε την στους παραλήπτες με το API διαπιστευτηρίων.

---

Λίστα ψηφιακών σημάτων

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

GET /badges

Παράδειγμα

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

Απάντηση

[
  {
    "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://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Λήψη ψηφιακού σήματος

Ανακτήστε ένα μεμονωμένο ψηφιακό σήμα, συμπεριλαμβανομένου του κειμένου κοινοποίησης και του σειριοποιημένου εγγράφου του σχεδιαστή ψηφιακών σημάτων (designJson). Αυτό είναι το endpoint που χρησιμοποιεί το modal επεξεργασίας ψηφιακού σήματος για να επαναφέρει μεμονωμένα στρώματα· το endpoint λίστας παραλείπει το designJson ώστε οι απαντήσεις να παραμένουν ελαφριές.

GET /badges/{badgeId}

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτική	Περιγραφή
badgeId	string	Ναι	Το ID του ψηφιακού σήματος (παράμετρος διαδρομής)

Παράδειγμα

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

Απάντηση

{
  "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://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Το κείμενο κοινοποίησης περιλαμβάνεται πάντα. Η ελαφρύτερη παραλλαγή λίστας GET /badges?badgeId={id} επιστρέφει το ίδιο έγγραφο χωρίς το designJson και περιλαμβάνει το κείμενο κοινοποίησης μόνο όταν κληθεί με includeShareText=true.

---

Ενημέρωση ψηφιακού σήματος

Ενημερώστε ένα υπάρχον ψηφιακό σήμα. Αλλάζουν μόνο τα πεδία που παρέχετε.

PUT /badges/{badgeId}

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτική	Περιγραφή
badgeId	string	Ναι	Το ID του ψηφιακού σήματος (παράμετρος διαδρομής)
name	string	Όχι	Νέος τίτλος του ψηφιακού σήματος
description	string	Όχι	Νέα περιγραφή
criteria	string	Όχι	Νέα κριτήρια
image	string	Όχι	Νέα εικόνα κωδικοποιημένη σε Base64
designJson	string	Όχι	Νέο σειριοποιημένο έγγραφο του σχεδιαστή ψηφιακών σημάτων.

Παράδειγμα

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

Απάντηση

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

---

Ενημέρωση κειμένου κοινοποίησης

Ορίστε το προσαρμοσμένο κείμενο που εμφανίζεται όταν οι παραλήπτες κοινοποιούν αυτό το ψηφιακό σήμα στα κοινωνικά δίκτυα.

PUT /badges/{badgeId}/share-text

Παράμετροι

Παράμετρος	Τύπος	Υποχρεωτική	Περιγραφή
badgeId	string	Ναι	Το ID του ψηφιακού σήματος (παράμετρος διαδρομής)
text	string	Ναι	Κείμενο κοινοποίησης (δεν επιτρέπεται HTML)

Παράδειγμα

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

Απάντηση

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Διαγραφή ψηφιακού σήματος

Διαγράψτε ένα ψηφιακό σήμα. Το ψηφιακό σήμα δεν πρέπει να έχει διαπιστευτήρια.

DELETE /badges/{badgeId}

Παράδειγμα

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

Απάντηση

Επιστρέφει μια απλή συμβολοσειρά επιβεβαίωσης:

"badge has been deleted"

Σφάλματα

• 400 — το ψηφιακό σήμα έχει ακόμη εκδοθέντα διαπιστευτήρια: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — το ψηφιακό σήμα δεν βρέθηκε