API dei rilasci

Crea e gestisci rilasci di credenziali (assertion) — credenziali consegnate a destinatari specifici.

Tutti gli endpoint richiedono autenticazione tramite l'intestazione X-Api-Key. Consulta Autenticazione.

Creare un rilascio

Consegna una credenziale a un destinatario.

POST /awards

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID della credenziale da rilasciare
recipient	object	Sì	Dati del destinatario (vedi sotto)
recipient.name	string	Sì	Nome completo del destinatario (minimo 5 caratteri)
recipient.email	string	Sì	E-mail del destinatario
issuedOn	string	Sì	Data di rilascio in formato ISO 8601 (es. 2025-01-15)
expires	string	No	Data di scadenza in formato ISO 8601
blockchain	string	No	Blockchain per la verifica on-chain. È supportato soltanto matchain. Disponibile nel piano Pro.

Esempio

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

Risposta

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

Note

• Scala uno dalla dotazione mensile (Free: 100/mese, Starter: 1.000/mese, Pro: 10.000/mese). La dotazione si azzera a ogni ciclo di fatturazione.
• Il parametro blockchain è disponibile soltanto nel piano Pro.

---

Elencare i rilasci

Recupera i rilasci con filtri opzionali e paginazione.

GET /awards

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
filter	JSON string	No	Oggetto filtro (vedi sotto)
lastEvaluatedKey	string	No	Token di paginazione da una risposta precedente

Oggetto filtro

Il parametro filter accetta una stringa JSON con questi campi:

Campo	Tipo	Descrizione
badgeId	string	Filtra per ID credenziale.
search	string	Sottostringa da cercare fra nomi o e-mail dei destinatari (vedi searchField).
searchField	string	name (default) oppure email — quale colonna cercare.

La paginazione con lastEvaluatedKey funziona con o senza filtri. La pagina ha dimensione 50.

Esempio — Elencare tutti i rilasci

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

Esempio — Filtrare per credenziale

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"

Risposta

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

Se lastEvaluatedKey è presente nella risposta, ci sono altri risultati. Passalo come parametro di query nella richiesta successiva per ottenere la pagina seguente.

---

Inviare e-mail del rilascio

Invia un'e-mail di notifica al destinatario sul proprio rilascio.

POST /awards/{awardId}/send

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID del rilascio (parametro di percorso e corpo)
email	string	Sì	E-mail del destinatario

Esempio

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

Risposta

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

---

Condividere un rilascio

Condivide un rilascio con più destinatari via e-mail.

POST /awards/{awardId}/share

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID del rilascio (parametro di percorso e corpo)
recipients	string	Sì	Elenco di e-mail separate da virgole
subject	string	Sì	Oggetto dell'e-mail
message	string	Sì	Corpo del messaggio

Esempio

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

Risposta

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

---

Scaricare il certificato PDF

Genera un certificato PDF A4 pronto per la stampa relativo a un rilascio.

GET /awards/{awardGuid}/pdf

Nessuna autenticazione richiesta — questo endpoint è pubblico affinché i destinatari possano scaricare il proprio certificato.

Esempio

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

La risposta è il PDF binario con intestazione Content-Type: application/pdf.

---

Registrare un evento del rilascio

Registra un evento di interazione (visualizzazione, condivisione, download, aggiunta a LinkedIn). Usato dalla pagina pubblica del rilascio per alimentare le statistiche. Nessuna autenticazione richiesta.

POST /awards/{awardGuid}/event

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
kind	string	Sì	Uno fra view, share, download, linkedin_add.
network	string	No	Se kind=share, il social: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Soppressione dei duplicati per IP: lo stesso tipo dalla stessa IP viene conteggiato una volta ogni 24 ore.

Esempio

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

---

Ottenere statistiche del rilascio

Recupera i contatori cumulativi di interazione di un rilascio.

GET /awards/{awardGuid}/stats

Nessuna autenticazione richiesta.

Risposta

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