API-ul acordărilor

Creează și gestionează acordări (assertions) — credențiale livrate unor destinatari anume.

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

Creează acordare

Livrează o credențială unui destinatar.

POST /awards

Parametri

Parametru	Tip	Obligatoriu	Descriere
badgeId	string	Da	ID-ul credențialei de acordat
recipient	object	Da	Datele destinatarului (mai jos)
recipient.name	string	Da	Numele complet al destinatarului (minimum 5 caractere)
recipient.email	string	Da	E-mailul destinatarului
issuedOn	string	Da	Data emiterii în format ISO 8601 (ex. 2025-01-15)
expires	string	Nu	Data expirării în format ISO 8601
blockchain	string	Nu	Blockchain pentru verificare on-chain. Se acceptă doar matchain. Disponibil în planul Pro.

Exemplu

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

Răspuns

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

Note

• Scade una din alocația lunară (Free: 100/lună, Starter: 1.000/lună, Pro: 10.000/lună). Alocația se resetează la fiecare perioadă de facturare.
• Parametrul blockchain este disponibil doar în planul Pro.

---

Listează acordările

Recuperează acordările cu filtre și paginare opționale.

GET /awards

Parametri de interogare

Parametru	Tip	Obligatoriu	Descriere
filter	JSON string	Nu	Obiect de filtrare (mai jos)
lastEvaluatedKey	string	Nu	Token de paginare dintr-un răspuns anterior

Obiect de filtrare

Parametrul filter acceptă un JSON string cu aceste câmpuri:

Câmp	Tip	Descriere
badgeId	string	Filtrează după ID-ul credențialei.
search	string	Subșir căutat în numele sau e-mailurile destinatarilor (vezi searchField).
searchField	string	Fie name (implicit), fie email — ce coloană se caută.

Paginarea prin lastEvaluatedKey funcționează cu sau fără filtre. Dimensiunea paginii este 50.

Exemplu — Listează toate acordările

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

Exemplu — Filtrează după credențială

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"

Răspuns

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

Dacă răspunsul include lastEvaluatedKey, există mai multe rezultate. Transmite-l ca parametru de interogare în cererea următoare pentru a obține pagina următoare.

---

Trimite e-mail de acordare

Trimite o notificare prin e-mail destinatarului despre acordarea sa.

POST /awards/{awardId}/send

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul acordării (parametru de rută și corp)
email	string	Da	E-mailul destinatarului

Exemplu

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

Răspuns

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

Distribuie acordare

Distribuie o acordare mai multor destinatari prin e-mail.

POST /awards/{awardId}/share

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul acordării (parametru de rută și corp)
recipients	string	Da	Listă de adrese de e-mail separate prin virgulă
subject	string	Da	Subiectul e-mailului
message	string	Da	Corpul mesajului

Exemplu

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

Răspuns

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

Descarcă certificatul PDF

Generează un certificat PDF A4 gata pentru tipărire pentru o acordare.

GET /awards/{awardGuid}/pdf

Nu necesită autentificare — acest endpoint este public pentru ca destinatarii să-și poată descărca propriul certificat.

Exemplu

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

Răspunsul este PDF-ul binar cu antetul Content-Type: application/pdf.

---

Înregistrează eveniment al acordării

Înregistrează un eveniment de interacțiune (vizualizare, distribuire, descărcare, adăugare LinkedIn). Folosit de pagina publică a acordării pentru a alimenta statisticile de interacțiune. Nu necesită autentificare.

POST /awards/{awardGuid}/event

Parametri

Parametru	Tip	Obligatoriu	Descriere
kind	string	Da	Una dintre view, share, download, linkedin_add.
network	string	Nu	Dacă kind=share, rețeaua socială: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Suprimarea duplicatelor pe IP: același tip de la aceeași IP se numără o singură dată la fiecare 24 de ore.

Exemplu

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

---

Obține statisticile acordării

Recuperează contoarele cumulative de interacțiune pentru o acordare.

GET /awards/{awardGuid}/stats

Nu necesită autentificare.

Răspuns

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}