Έκδοση Open Badges μέσω του REST API του Badges Ninja: Γρήγορη εκκίνηση

Τα περισσότερα προγράμματα πιστοποίησης δεν χρειάζονται ποτέ API. Αν διοργανώνετε ένα μάθημα με μερικές εκατοντάδες απόφοιτους τον χρόνο, ο πίνακας ελέγχου κάνει τα πάντα: σχεδιάζετε ένα ψηφιακό σήμα στον οπτικό σχεδιαστή, ανεβάζετε ένα CSV και κάθε αποδέκτης παίρνει μια σελίδα επαλήθευσης και ένα πιστοποιητικό PDF. Αν αυτή είναι η περίπτωσή σας, ξεκινήστε με το πώς να εκδώσετε Open Badges από CSV και επιστρέψτε αργότερα.

Το API δικαιολογεί τη θέση του όταν οι τίτλοι πρέπει να εκδίδονται από ένα άλλο σύστημα: η πλατφόρμα εκμάθησης σημειώνει ένα μάθημα ως ολοκληρωμένο, το εργαλείο εγγραφών κλείνει μια εκδήλωση, το σύστημα HR καταγράφει μια ολοκληρωμένη ενότητα συμμόρφωσης. Σε αυτές τις περιπτώσεις κανείς δεν θέλει να εξάγει ένα υπολογιστικό φύλλο στο τέλος κάθε εβδομάδας. Μία μόνο κλήση HTTP τη στιγμή της ολοκλήρωσης είναι απλούστερη, και ο αποδέκτης παίρνει το ψηφιακό σήμα του όσο το επίτευγμα είναι ακόμη φρέσκο.

Αυτός ο οδηγός γρήγορης εκκίνησης διασχίζει ολόκληρη τη διαδρομή με τέσσερις κλήσεις: παίρνετε ένα κλειδί, δημιουργείτε έναν εκδότη, δημιουργείτε ένα ψηφιακό σήμα, το απονέμετε. Έπειτα βλέπουμε πώς θα δώσετε τον σύνδεσμο επαλήθευσης στον αποδέκτη και πώς θα ελέγξετε το αποτέλεσμα. Κάθε μορφή αιτήματος παρακάτω προέρχεται από τους πραγματικούς handlers που είναι σε λειτουργία, οπότε μπορείτε να την επικολλήσετε και να την εκτελέσετε.

Τι χρειάζεστε πριν ξεκινήσετε

• Έναν δωρεάν λογαριασμό στο badges.ninja. Το πρόγραμμα Free αρκεί για αυτόν τον οδηγό: περιλαμβάνει 2 εκδότες, 5 ψηφιακά σήματα, 2 θέσεις και 1 κλειδί API.
• Ένα κλειδί API, που δημιουργείται από τον πίνακα ελέγχου.
• Ένα PNG ή JPG για την εικόνα του ψηφιακού σήματος, ή ένα σήμα που σχεδιάσατε στον οπτικό σχεδιαστή.

Η βασική διεύθυνση URL για όλα είναι https://api.badges.ninja.

Βήμα 1: Δημιουργήστε ένα κλειδί API

Συνδεθείτε, ανοίξτε το API Keys στην πλευρική γραμμή και πατήστε Create API Key. Δώστε του ένα όνομα που λέει πού θα ζει, όπως «Ενσωμάτωση LMS», ώστε να ξεχωρίζετε τα κλειδιά όταν τα αναδημιουργείτε αργότερα.

Το κλειδί εμφανίζεται ακριβώς μία φορά. Αντιγράψτε το αμέσως στον διαχειριστή μυστικών σας ή σε μια μεταβλητή περιβάλλοντος. Τα κλειδιά μοιάζουν με bws_ ακολουθούμενο από 32 δεκαεξαδικούς χαρακτήρες και τα στέλνετε σε μια κεφαλίδα X-Api-Key σε κάθε αίτημα. Η ανάκληση ενός κλειδιού από την ίδια οθόνη ισχύει άμεσα.

Μερικές συνήθειες που γλιτώνουν προβλήματα αργότερα:

• Ποτέ μην βάζετε το κλειδί σε κώδικα front-end ή σε δημόσιο αποθετήριο. Καλέστε το API από έναν διακομιστή, μια serverless συνάρτηση ή ένα εργαλείο αυτοματισμού.
• Χρησιμοποιήστε ένα κλειδί ανά ενσωμάτωση. Αν διαρρεύσει ένα, ανακαλείτε μία ενσωμάτωση αντί για όλες.
• Ο πίνακας ελέγχου δέχεται επίσης τη συνεδρία σας μετά τη σύνδεση (ένα Cognito JWT που αποστέλλεται ως Authorization: Bearer), αλλά για σενάρια και ενσωματώσεις το σωστό εργαλείο είναι το κλειδί API.

Όλα τα παραδείγματα παρακάτω διαβάζουν το κλειδί από μια μεταβλητή περιβάλλοντος με όνομα BADGES_API_KEY.

Βήμα 2: Δημιουργήστε έναν εκδότη

Ο εκδότης είναι ο οργανισμός που στηρίζει το ψηφιακό σήμα. Εμφανίζεται σε κάθε σελίδα επαλήθευσης και μέσα στα δεδομένα Open Badge v2.0, γι’ αυτό χρησιμοποιήστε το όνομα που ο κόσμος γνωρίζει πραγματικά.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

Τα υποχρεωτικά πεδία είναι name (τουλάχιστον 3 χαρακτήρες), url (έγκυρη διεύθυνση http ή https) και email. Προαιρετικά πεδία είναι το logo (εικόνα κωδικοποιημένη σε base64) και το linkedinOrganizationId, που ενεργοποιεί το κουμπί Add to LinkedIn Profile στις δημόσιες σελίδες των πιστοποιήσεών σας.

Η απάντηση περιέχει το αναγνωριστικό του εκδότη:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Κρατήστε αυτή την τιμή ακριβώς όπως επιστράφηκε. Είναι η είσοδος για το επόμενο βήμα.

Επαλήθευση εκδότη

Τα ψηφιακά σήματα μπορούν να δημιουργηθούν μόνο υπό έναν επαληθευμένο εκδότη. Η επαλήθευση λειτουργεί ως εξής:

• Αν το email του εκδότη ταιριάζει με το email του λογαριασμού σας, ο εκδότης επαληθεύεται αυτόματα. Αυτός είναι ο ταχύτερος δρόμος για μια πρώτη δοκιμή.
• Αν το email είναι διαφορετικό, στέλνεται σε αυτή τη διεύθυνση ένα email επαλήθευσης με έναν κωδικό. Επιβεβαιώνετε τον κωδικό στον πίνακα ελέγχου (ή μέσω του API εκδοτών) πριν δημιουργήσετε ψηφιακά σήματα.

Έτσι, για αυτόν τον οδηγό, χρησιμοποιήστε το ίδιο email με το οποίο εγγραφήκατε.

Βήμα 3: Δημιουργήστε ένα ψηφιακό σήμα

Ένα ψηφιακό σήμα είναι το επαναχρησιμοποιήσιμο πρότυπο: όνομα, περιγραφή, κριτήρια και εικόνα. Κάθε απονομή που εκδίδετε αργότερα παραπέμπει σε αυτό.

Το αίτημα είναι απλό JSON. Η εικόνα μπαίνει ως συμβολοσειρά base64, οπότε δεν υπάρχει multipart μεταφόρτωση να παλέψετε. Ένα πρόθεμα data URL όπως data:image/png;base64, γίνεται δεκτό και αφαιρείται.

JavaScript (Node 18 ή νεότερο):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Και τα πέντε πεδία (name, description, criteria, image, issuerId) είναι υποχρεωτικά. Δύο προαιρετικά αξίζει να τα γνωρίζετε: το shareText, το προεπιλεγμένο κείμενο που βλέπουν οι αποδέκτες όταν μοιράζονται στα κοινωνικά δίκτυα (υποστηρίζει τα placeholders {{badge_name}}, {{issuer_name}} και {{award_url}}), και το designJson, που αποθηκεύει ένα έγγραφο του οπτικού σχεδιαστή ώστε το σήμα να μπορεί να επεξεργαστεί αργότερα στρώμα προς στρώμα.

Μια επιτυχία επιστρέφει HTTP 200 με { "badgeId": "<id>" }. Η εικόνα αποθηκεύεται μόνιμα και το ψηφιακό σήμα είναι πλέον ένα BadgeClass Open Badge v2.0 που μπορεί να ανακτήσει οποιοσδήποτε.

Πρέπει να δημιουργείτε ψηφιακά σήματα μέσω κώδικα;

Συνήθως όχι. Ο σχεδιασμός ενός σήματος είναι δημιουργική εργασία, και ο οπτικός σχεδιαστής (80+ πρότυπα, σχήματα, εικονίδια, 11 γραμματοσειρές και προσαρμοσμένες μεταφορτώσεις) είναι πολύ καλύτερο μέρος γι’ αυτό από ένα σενάριο. Ένα συνηθισμένο μοτίβο είναι να σχεδιάζετε κάθε σήμα μία φορά στον πίνακα ελέγχου και η ενσωμάτωσή σας να εκδίδει μόνο απονομές πάνω σε αυτό. Μπορείτε να δείτε τη λίστα των σημάτων σας με GET /badges και να αντιγράψετε το id αυτού που θέλετε.

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

Βήμα 4: Απονείμετε το ψηφιακό σήμα

Αυτή είναι η κλήση που η ενσωμάτωσή σας θα κάνει χιλιάδες φορές. Στείλτε το σήμα, τον αποδέκτη και την ημερομηνία.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Οι κανόνες στους οποίους μπερδεύονται οι περισσότεροι:

• Το recipient είναι ένα εμφωλευμένο αντικείμενο με name και email. Επίπεδα πεδία όπως το recipientEmail απορρίπτονται.
• Το recipient.name πρέπει να έχει τουλάχιστον 5 χαρακτήρες.
• Το issuedOn είναι υποχρεωτικό. Στείλτε χιλιοστά του δευτερολέπτου epoch ή συμβολοσειρά ημερομηνίας ISO όπως 2026-09-28.
• Το expires είναι προαιρετικό και δέχεται τις ίδιες μορφές.

Μια επιτυχία είναι HTTP 200 με σώμα που περιέχει το awardId. Το email του αποδέκτη αποθηκεύεται ως κατακερματισμός SHA-256 στα δεδομένα Open Badge, οπότε το δημόσιο JSON δεν το αποκαλύπτει ποτέ.

Βήμα 5: Βρείτε τη σελίδα επαλήθευσης και το JSON του Open Badge

Η απάντηση της απονομής σας δίνει ένα αναγνωριστικό, όχι έτοιμο σύνδεσμο. Το αναγνωριστικό καταλήγει σε ένα GUID και οι δημόσιες σελίδες χτίζονται από αυτό το GUID:

• Σελίδα επαλήθευσης για ανθρώπους: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Αν το awardId σας επιστρέφεται ως πλήρες URL, χρησιμοποιήστε το τελευταίο τμήμα της διαδρομής ως GUID.

Και τα δύο είναι δημόσια. Οποιοσδήποτε έχει τον σύνδεσμο μπορεί να επαληθεύσει την πιστοποίηση χωρίς να δημιουργήσει λογαριασμό, και αυτό είναι το νόημα: ένας εργοδότης ή υπεύθυνος εισαγωγής πρέπει να μπορεί να ελέγξει ένα ψηφιακό σήμα σε δέκα δευτερόλεπτα.

Ανακτήστε το JSON για να δείτε αυτό που βλέπει ο κόσμος:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Παίρνετε ένα Assertion Open Badge v2.0: το σήμα στο οποίο παραπέμπει, την κατακερματισμένη ταυτότητα του αποδέκτη, την ημερομηνία έκδοσης και ένα μπλοκ επαλήθευσης που δείχνει πίσω στο φιλοξενούμενο assertion. Επειδή είναι τυπικά δεδομένα Open Badges, οποιοδήποτε εργαλείο καταλαβαίνει τη μορφή μπορεί να τα διαβάσει. Αυτή η φορητότητα είναι ο λόγος να προτιμήσετε τα Open Badges από ένα ιδιοκτησιακό PDF· το Open Badges vs πιστοποιητικά PDF εμβαθύνει στον συμβιβασμό.

Πώς λαμβάνουν οι αποδέκτες την πιστοποίηση

Η δημιουργία μιας απονομής είναι ξεχωριστή από την ενημέρωση του αποδέκτη. Οι αποδέκτες μπορούν να ανοίξουν τις πιστοποιήσεις τους μέσω της πύλης αποδεκτών στο badges.ninja/me, που χρησιμοποιεί σύνδεση με magic link χωρίς κωδικό πρόσβασης, και μπορούν να δημοσιεύσουν ένα δημόσιο προφίλ στο badges.ninja/u/<handle>. Από τη σελίδα επαλήθευσης μπορούν να προσθέσουν το σήμα στο LinkedIn, να κατεβάσουν το πιστοποιητικό PDF ή να μοιραστούν τον σύνδεσμο.

Για τις πρώτες δοκιμές, στείλτε στον εαυτό σας μια απονομή με τη δική σας διεύθυνση email και περάστε από την εμπειρία του αποδέκτη. Είναι ο ταχύτερος τρόπος να προσέξετε πράγματα όπως μια περιγραφή σήματος που ακούγεται άκομψα.

Διαχείριση σφαλμάτων που δεν πονάει

Το API χρησιμοποιεί συνηθισμένους κωδικούς κατάστασης HTTP. Αυτοί που θα συναντήσετε:

Δύο πρακτικές συμβουλές. Πρώτον, αντιμετωπίστε το 400 ως πρόβλημα δεδομένων και καταγράψτε το σώμα της απάντησης, αφού κατονομάζει το πεδίο που απέτυχε. Δεύτερον, κάντε την ενσωμάτωσή σας ιδεοδύναμη από τη δική σας πλευρά: αποθηκεύστε το awardId δίπλα στην εγγραφή ολοκλήρωσης στη δική σας βάση δεδομένων και ελέγξτε το πριν καλέσετε ξανά το API. Έτσι ένα webhook που επαναλαμβάνεται ή μια εργασία που τρέχει ξανά δεν θα εκδώσει ποτέ στο ίδιο άτομο δύο πιστοποιήσεις.

Συνδυάζοντάς τα σε μια πραγματική ενσωμάτωση

Μια τυπική υλοποίηση μοιάζει έτσι:

1. Σχεδιάστε ψηφιακά σήματα στον πίνακα ελέγχου, ένα ανά μάθημα ή ορόσημο, και σημειώστε το ID κάθε σήματος.
2. Αποθηκεύστε στο σύστημά σας μια αντιστοίχιση από μάθημα σε ID σήματος.
3. Όταν ένας εκπαιδευόμενος ολοκληρώνει ένα μάθημα, ο διακομιστής σας καλεί το POST /awards με το όνομα, το email και την ημερομηνία ολοκλήρωσης.
4. Αποθηκεύστε το επιστρεφόμενο awardId στην εγγραφή ολοκλήρωσης.
5. Εμφανίστε τον σύνδεσμο επαλήθευσης μέσα στο δικό σας προϊόν, ώστε ο εκπαιδευόμενος να τον βλέπει χωρίς να φύγει.

Αν προτιμάτε να μη γράψετε κώδικα, η ίδια κλήση λειτουργεί από οποιοδήποτε εργαλείο αυτοματισμού που μπορεί να στείλει αίτημα HTTP με σώμα JSON και προσαρμοσμένη κεφαλίδα. Στρέψτε το στο https://api.badges.ninja/awards και αντιστοιχίστε τα πεδία της φόρμας ή του υπολογιστικού φύλλου σας στα badgeId, recipient.name, recipient.email και issuedOn.

Προγράμματα και όρια που αξίζει να γνωρίζετε

Το API είναι διαθέσιμο σε κάθε πρόγραμμα· δεν πληρώνετε επιπλέον για να το ξεκλειδώσετε. Το πρόγραμμα Free ($0) καλύπτει 2 εκδότες, 5 ψηφιακά σήματα, 2 θέσεις, 1 κλειδί API και 1.200 πιστοποιήσεις τον χρόνο. Το Starter κοστίζει $9 τον μήνα και το Pro $29 τον μήνα, με υψηλότερα όρια. Δείτε τη σελίδα τιμολόγησης για τους τρέχοντες αριθμούς πριν υπολογίσετε το μέγεθος μιας εφαρμογής. Αν συγκρίνετε τι χρεώνουν άλλες πλατφόρμες για πρόσβαση στο API, το Credly alternative παραθέτει τα κόστη δίπλα-δίπλα.

Πού να πάτε στη συνέχεια

• Η πλήρης αναφορά των endpoint βρίσκεται στην τεκμηρίωση του API, διαθέσιμη σε 40 γλώσσες.
• Για λεπτομέρειες ταυτοποίησης και χειρισμού κλειδιών, δείτε τον οδηγό ταυτοποίησης.
• Για αναλυτικούς κωδικούς σφαλμάτων, δείτε την αναφορά σφαλμάτων.
• Όταν ξεπεράσετε τη μία κλήση κάθε φορά, χρησιμοποιήστε τις μαζικές απονομές στον πίνακα ελέγχου: ανεβάστε ένα CSV και θέστε σε παύση ή συνεχίστε την εκτέλεση αν χρειαστεί.

Η πρώτη επιτυχημένη απονομή είναι το δύσκολο κομμάτι. Μετά, το υπόλοιπο είναι να συνδέσετε την ίδια κλήση στα σημεία όπου καταγράφονται ήδη τα επιτεύγματα.

Έτοιμοι να εκδώσετε την πρώτη σας επαληθεύσιμη πιστοποίηση; Ξεκινήστε δωρεάν στο badges.ninja — οπτικός σχεδιαστής, δημόσια σελίδα επαλήθευσης, πιστοποιητικό PDF, έξοδος Open Badge v2.0. Δεν απαιτείται πιστωτική κάρτα.