API degli emittenti

Gestisci gli emittenti di credenziali — le organizzazioni o le persone che rilasciano credenziali.

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

Creare un emittente

Crea un nuovo emittente di credenziali.

POST /issuers

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Ragione sociale dell'organizzazione (minimo 3 caratteri)
url	string	Sì	Sito web dell'organizzazione (URL HTTP/HTTPS valido)
email	string	Sì	E-mail di contatto dell'emittente
logo	string	No	Immagine codificata in Base64 (PNG o JPG)
linkedinOrganizationId	string	No	ID numerico della pagina aziendale LinkedIn. Quando impostato, ogni pagina pubblica di rilascio 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

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

Note

• Scala dal limite di emittenti del piano (Free: 1, Starter: 5, Pro: illimitati). Nessun addebito di quota.
• Se l'e-mail dell'emittente coincide con l'e-mail dell'account, viene verificato automaticamente.
• Se l'e-mail è diversa, un'e-mail di verifica viene inviata all'indirizzo dell'emittente.

---

Elencare gli 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

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "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": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Verificare un emittente

Verifica un emittente tramite il codice di verifica inviato alla sua e-mail.

POST /issuers/{issuerId}/verify

Parametri

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

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

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

---

Eliminare un emittente

Elimina un emittente. L'emittente non deve avere credenziali associate.

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

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

Errori

• 400 — l'emittente ha credenziali o rilasci e non può essere eliminato (eliminali prima)
• 404 — emittente non trovato

---

Aggiornare un emittente

Aggiorna i campi di un emittente non verificato. Una volta verificato, soltanto logo e linkedinOrganizationId restano modificabili per preservare la stabilità delle credenziali.

PUT /issuers/{issuerId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
issuerId	string	Sì	L'ID dell'emittente (parametro di percorso)
name	string	No	Nuovo nome (solo se non verificato)
url	string	No	Nuovo URL (solo se non verificato)
email	string	No	Nuova e-mail (solo se non verificato — invia una nuova e-mail di verifica)
logo	string	No	Nuovo logo codificato in Base64
linkedinOrganizationId	string	No	Nuovo LinkedIn organization ID (oppure stringa vuota per cancellarlo)

---

Ruotare il codice di verifica

Invalida il link di verifica precedente e ne invia uno nuovo via e-mail. Valido soltanto finché l'emittente non è ancora verificato.

POST /issuers/{issuerId}/rotate-code

Risposta

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