API Emittenti

Gestisci gli emittenti di badge — le organizzazioni o i privati che emettono i badge.

Tutti gli endpoint richiedono l'autenticazione tramite l'header X-Api-Key. Vedi Autenticazione.

Crea emittente

Crea un nuovo emittente di badge.

POST /issuers

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome dell'organizzazione (minimo 3 caratteri)
url	string	Sì	Sito web dell'organizzazione (deve essere un URL HTTP/HTTPS valido)
email	string	Sì	Email di contatto dell'emittente
logo	string	No	Immagine codificata in Base64 (PNG o JPG)
linkedinOrganizationId	string	No	ID numerico della pagina aziendale LinkedIn. Se impostato, ogni pagina pubblica delle credenziali di questo emittente mostra un pulsante Add to LinkedIn Profile.

Esempio

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

Risposta

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

Note

• Conta ai fini del limite di emittenti del tuo piano (Free: 2, Starter: 5, Pro: 10). Nessuna deduzione di quota.
• Se l'email dell'emittente coincide con l'email del tuo account, l'emittente viene verificato automaticamente.
• Se l'email è diversa, viene inviata un'email di verifica all'indirizzo dell'emittente.
• Dopo aver configurato un emittente, usa l'API Credenziali per iniziare a emettere credenziali a suo nome.

---

Elenca emittenti

Recupera tutti gli emittenti che hai creato.

GET /issuers

Esempio

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

Risposta

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp è un Unix epoch in millisecondi. Quando gli emittenti sono più di quelli che stanno in una pagina, viene restituito anche un lastEvaluatedKey per la paginazione.

---

Verifica emittente

Verifica un emittente usando il codice di verifica inviato alla sua email.

POST /issuers/{issuerId}/verify

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
issuerId	string	Sì	L'ID dell'emittente (parametro del percorso)
code	string	Sì	Il codice di verifica ricevuto via email

Esempio

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Risposta

Una semplice stringa:

"issuer has been verified"

---

Elimina emittente

Elimina un emittente. L'emittente non deve avere badge collegati.

DELETE /issuers/{issuerId}

Esempio

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Risposta

Una semplice stringa:

"issuer has been deleted"

Errori

• 400 — l'emittente ha ancora badge collegati: issuer has {n} badge(s) linked — delete the badges first. L'eliminazione dipende solo dai badge collegati — le credenziali non la bloccano.
• 404 — emittente non trovato

---

Aggiorna emittente

Aggiorna i campi di un emittente. Possono essere modificati solo gli emittenti non verificati — una volta verificato un emittente, questo endpoint restituisce 400 verified issuers cannot be edited per preservare la stabilità delle credenziali. La modifica di un emittente rigenera il suo codice di verifica: se l'email coincide con l'email del tuo account l'emittente viene riverificato automaticamente, altrimenti viene inviata una nuova email di verifica a quell'indirizzo.

PUT /issuers/{issuerId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
issuerId	string	Sì	L'ID dell'emittente (parametro del percorso)
name	string	No	Nuovo nome
url	string	No	Nuovo URL
email	string	No	Nuova email (invia una nuova email di verifica a meno che non coincida con l'email del tuo account)
logo	string	No	Nuovo logo codificato in base64
linkedinOrganizationId	string	No	Nuovo ID organizzazione LinkedIn (o stringa vuota per rimuoverlo)

Risposta

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Errori

• 400 — verified issuers cannot be edited (l'emittente è già verificato)
• 400 — not authorized (l'emittente appartiene a un altro account)
• 404 — emittente non trovato