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

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

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

Δημιουργία διαπιστευτηρίου

Εκδώστε ένα ψηφιακό σήμα σε έναν παραλήπτη.

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

POST /awards

Παράμετροι

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

Παράδειγμα

bash

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

Απάντηση

json

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

Σημειώσεις

Μετράει ως ένα διαπιστευτήριο από την ετήσια δεξαμενή διαπιστευτηρίων σας (Free: 1,200/έτος, Starter: 12,000/έτος, Pro: 120,000/έτος). Η δεξαμενή είναι μια ευέλικτη ετήσια ποσόστωση — την αξιοποιείτε όποτε θέλετε μέσα στο έτος, ακόμη και σε εκρήξεις — και επαναφέρεται στην επέτειο εγγραφής του λογαριασμού σας. Η χρέωση παραμένει μηνιαία· μόνο η ποσόστωση διαπιστευτηρίων είναι ετήσια. Δείτε τα Πλάνα και χρέωση για λεπτομέρειες.

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

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

GET /awards

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

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

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

Η παράμετρος filter δέχεται ένα JSON string με τα εξής πεδία:

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

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

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

bash

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

Παράδειγμα — Φιλτράρισμα ανά σήμα

bash

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"

Απάντηση

json

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "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	Ναι	Το αναγνωριστικό του διαπιστευτηρίου (παράμετρος διαδρομής και σώματος)
`email`	string	Ναι	Διεύθυνση email του παραλήπτη

Παράδειγμα

bash

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

Απάντηση

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

json

"email sent"

Κοινοποίηση διαπιστευτηρίου

Κοινοποιήστε ένα διαπιστευτήριο σε πολλούς παραλήπτες μέσω email.

POST /awards/{awardId}/share

Παράμετροι

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

Παράδειγμα

bash

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

Απάντηση

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

json

"email sent"

Ανάκληση διαπιστευτηρίου

Ανακαλέστε ένα διαπιστευτήριο που εκδώσατε. Το φιλοξενούμενο assertion Open Badges v2.0 επισημαίνεται με revoked: true (με προαιρετικό λόγο), ώστε κάθε επαληθευτής να βλέπει ότι το σήμα δεν είναι πλέον έγκυρο. Η εγγραφή του διαπιστευτηρίου διατηρείται για λόγους ελέγχου και δεν επιστρέφεται καμία πίστωση.

Η ανάκληση διαδίδεται επίσης στο Verifiable Credential Open Badges 3.0 του διαπιστευτηρίου: το bit του διαπιστευτηρίου αλλάζει στη W3C Bitstring Status List στην οποία παραπέμπει το credentialStatus του VC, ώστε και τα πορτοφόλια VC να την εντοπίζουν. Δείτε την Ανάκληση (Bitstring Status List).

POST /awards/{awardId}/revoke

Παράμετροι

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
`awardId`	string	Ναι	Το αναγνωριστικό του διαπιστευτηρίου (παράμετρος διαδρομής)
`reason`	string	Όχι	Λόγος ανάκλησης. Περικόπτεται στους 500 χαρακτήρες.
`notify`	boolean	Όχι	Όταν είναι `true`, στέλνει email στον παραλήπτη ότι το διαπιστευτήριό του ανακλήθηκε. Η προεπιλογή είναι `false`.

Παράδειγμα

bash

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Απάντηση

json

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Η ανάκληση ενός ήδη ανακληθέντος διαπιστευτηρίου είναι ισοδύναμη (idempotent) — επιστρέφει την ίδια απάντηση χωρίς να ξαναστείλει ειδοποίηση.

Μαζική ανάκληση

Για να ανακαλέσετε πολλά διαπιστευτήρια ταυτόχρονα, χρησιμοποιήστε το ανθεκτικό μαζικό endpoint με action: "revoke" αντί να καλείτε αυτό το endpoint για κάθε διαπιστευτήριο:

bash

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Επιστρέφει { "jobId", "total" }· η εργασία ανακαλεί κάθε αναγνωριστικό στον διακομιστή (παραλείποντας όσα έχουν ήδη ανακληθεί) και μπορεί να συνεχιστεί. Τα ήδη ανακληθέντα και τα ανύπαρκτα αναγνωριστικά αναφέρονται ως παραλειφθέντα.

Διαγραφή διαπιστευτηρίου

Διαγράψτε οριστικά ένα διαπιστευτήριο που εκδώσατε. Σε αντίθεση με την ανάκληση, αυτό αφαιρεί εντελώς την εγγραφή και η δημόσια σελίδα του διαπιστευτηρίου θα επιστρέφει 404. Χρησιμοποιήστε το για πραγματικά λάθη (π.χ. έκδοση σε λάθος άτομο)· για πραγματικά διαπιστευτήρια προτιμήστε την ανάκληση, ώστε το assertion να παραμένει επαληθεύσιμο ως ανακληθέν. Δεν επιστρέφεται καμία πίστωση.

DELETE /awards/{awardId}

Παράμετροι

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
`awardId`	string	Ναι	Το αναγνωριστικό του διαπιστευτηρίου (παράμετρος διαδρομής)

Παράδειγμα

bash

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Απάντηση

json

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

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

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

GET /certify-badge/award/{awardGuid}/pdf

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

Παράδειγμα

bash

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

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

Καταγραφή συμβάντος διαπιστευτηρίου

Καταγράψτε ένα συμβάν αλληλεπίδρασης. Χρησιμοποιείται από τη δημόσια σελίδα του διαπιστευτηρίου για τη συμπλήρωση των στατιστικών αλληλεπίδρασης. Δεν απαιτείται έλεγχος ταυτότητας.

POST /certify-badge/award/{awardGuid}/event

Παράμετροι

Αυτό το endpoint διαβάζει το σώμα του απευθείας (χωρίς περιτύλιγμα parameters).

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

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

Παράδειγμα

bash

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Απάντηση

json

{
  "ok": true
}

Λήψη στατιστικών διαπιστευτηρίου

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

GET /certify-badge/award/{awardGuid}/stats

Δεν απαιτείται έλεγχος ταυτότητας.

Απάντηση

Οι μετρητές επιστρέφονται με κλειδί τον ακατέργαστο τύπο συμβάντος. Το totals περιέχει το συνολικό πλήθος ανά συμβάν· το networks αναλύει την κατανομή ανά δίκτυο για συμβάντα που φέρουν network (προς το παρόν share). Συμβάντα χωρίς καταγεγραμμένη δραστηριότητα απλώς απουσιάζουν.

json

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}

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

Δημιουργία διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

Σημειώσεις ​

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

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

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

Παράδειγμα — Λίστα όλων των διαπιστευτηρίων ​

Παράδειγμα — Φιλτράρισμα ανά σήμα ​

Απάντηση ​

Αποστολή email διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

Κοινοποίηση διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

Ανάκληση διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

Μαζική ανάκληση ​

Διαγραφή διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

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

Παράδειγμα ​

Καταγραφή συμβάντος διαπιστευτηρίου ​

Παράμετροι ​

Παράδειγμα ​

Απάντηση ​

Λήψη στατιστικών διαπιστευτηρίου ​

Απάντηση ​

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

Δημιουργία διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

Σημειώσεις

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

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

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

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

Παράδειγμα — Φιλτράρισμα ανά σήμα

Απάντηση

Αποστολή email διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

Κοινοποίηση διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

Ανάκληση διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

Μαζική ανάκληση

Διαγραφή διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

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

Παράδειγμα

Καταγραφή συμβάντος διαπιστευτηρίου

Παράμετροι

Παράδειγμα

Απάντηση

Λήψη στατιστικών διαπιστευτηρίου

Απάντηση