Referință API Insigne: creare, verificare și obținere de insigne

Gestionează șabloanele de insigne — credențialele pe care le emiți către destinatari.

Pentru a emite această insignă către mulți destinatari simultan printr-un fișier CSV, în loc de API, consultă Acreditări în masă.

Toate endpoint-urile necesită autentificare prin antetul X-Api-Key. Consultă Autentificare.

Creează insignă

Creează o insignă nouă sub un emitent verificat.

POST /badges

Parametri

Parametru	Tip	Obligatoriu	Descriere
name	string	Da	Titlul insignei
description	string	Da	Ce reprezintă insigna
criteria	string	Da	Ce a făcut destinatarul pentru a obține această insignă
image	string	Da	Imagine codificată Base64 (PNG sau JPG)
issuerId	string	Da	ID-ul emitentului verificat
shareText	string	Nu	Textul implicit de distribuire socială pentru această insignă. Acceptă substituenții , și . Dacă este omis, se folosește o valoare implicită predefinită.
designJson	string	Nu	Documentul serializat al designerului de insigne, stocat pentru ca insigna să poată fi editată ulterior strat cu strat.

Exemplu

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

Răspuns

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

Note

• Emitentul trebuie să fie verificat înainte de a crea insigne.
• Imaginea este stocată pe Amazon S3 și servită prin CDN-ul nostru global, sub un URL imuabil, adresat prin conținut.
• După ce există o clasă de insignă, emite-o către destinatari folosind API-ul pentru credențiale.

---

Listează insignele

Obține toate insignele pe care le-ai creat.

GET /badges

Exemplu

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

Răspuns

[
  {
    "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"
  }
]

---

Obține o insignă

Obține o singură insignă, inclusiv textul de distribuire și documentul serializat al designerului de insigne (designJson). Acesta este endpoint-ul folosit de fereastra Edit Badge pentru a reîncărca straturile individuale; endpoint-ul de listare omite designJson pentru a menține răspunsurile compacte.

GET /badges/{badgeId}

Parametri

Parametru	Tip	Obligatoriu	Descriere
badgeId	string	Da	ID-ul insignei (parametru de cale)

Exemplu

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

Răspuns

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

Textul de distribuire este întotdeauna inclus. Varianta mai ușoară de listare GET /badges?badgeId={id} returnează același document fără designJson și include textul de distribuire doar când este apelată cu includeShareText=true.

---

Actualizează insigna

Actualizează o insignă existentă. Doar câmpurile pe care le furnizezi sunt modificate.

PUT /badges/{badgeId}

Parametri

Parametru	Tip	Obligatoriu	Descriere
badgeId	string	Da	ID-ul insignei (parametru de cale)
name	string	Nu	Noul titlu al insignei
description	string	Nu	Descriere nouă
criteria	string	Nu	Criterii noi
image	string	Nu	Imagine nouă codificată Base64
designJson	string	Nu	Document serializat nou al designerului de insigne.

Exemplu

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

Răspuns

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

---

Actualizează textul de distribuire

Setează textul personalizat afișat când destinatarii distribuie această insignă pe rețelele sociale.

PUT /badges/{badgeId}/share-text

Parametri

Parametru	Tip	Obligatoriu	Descriere
badgeId	string	Da	ID-ul insignei (parametru de cale)
text	string	Da	Text de distribuire (HTML nu este permis)

Exemplu

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

Răspuns

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

---

Șterge insigna

Șterge o insignă. Insigna nu trebuie să aibă credențiale.

DELETE /badges/{badgeId}

Exemplu

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

Răspuns

Returnează un șir simplu de confirmare:

"badge has been deleted"

Erori

• 400 — insigna are încă credențiale emise: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — insigna nu a fost găsită