API de emissores

Gere emissores de emblemas — as organizações ou pessoas que emitem emblemas.

Todos os endpoints exigem autenticação através do cabeçalho X-Api-Key. Consulta Autenticação.

Criar emissor

Cria um novo emissor de emblemas.

POST /issuers

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da organização (mínimo de 3 carateres)
url	string	Sim	Website da organização (tem de ser um URL HTTP/HTTPS válido)
email	string	Sim	E-mail de contacto do emissor
logo	string	Não	Imagem codificada em Base64 (PNG ou JPG)
linkedinOrganizationId	string	Não	ID numérico da página de empresa no LinkedIn. Quando definido, todas as páginas públicas de credenciais deste emissor mostram um botão Adicionar ao perfil do LinkedIn.

Exemplo

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

Resposta

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

Notas

• Conta para o limite de emissores do teu plano (Free: 2, Starter: 5, Pro: 10). Sem dedução de quota.
• Se o e-mail do emissor for igual ao e-mail da tua conta, o emissor é verificado automaticamente.
• Se o e-mail for diferente, é enviado um e-mail de verificação para o e-mail do emissor.
• Depois de configurares um emissor, usa a API de credenciais para começares a emitir credenciais através desse emissor.

---

Listar emissores

Obtém todos os emissores que criaste.

GET /issuers

Exemplo

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

Resposta

{
  "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 é um Unix epoch em milissegundos. Quando existem mais emissores do que os que cabem numa página, é também devolvido um lastEvaluatedKey para paginação.

---

Verificar emissor

Verifica um emissor com o código de verificação enviado para o seu e-mail.

POST /issuers/{issuerId}/verify

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
issuerId	string	Sim	O ID do emissor (parâmetro de caminho)
code	string	Sim	O código de verificação recebido por e-mail

Exemplo

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

Resposta

Uma string simples:

"issuer has been verified"

---

Eliminar emissor

Elimina um emissor. O emissor não pode ter emblemas associados.

DELETE /issuers/{issuerId}

Exemplo

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

Resposta

Uma string simples:

"issuer has been deleted"

Erros

• 400 — o emissor ainda tem emblemas associados: issuer has {n} badge(s) linked — delete the badges first. A eliminação depende apenas dos emblemas associados — as credenciais não a bloqueiam.
• 404 — emissor não encontrado

---

Atualizar emissor

Atualiza os campos de um emissor. Só os emissores não verificados podem ser editados — depois de um emissor ser verificado, este endpoint devolve 400 verified issuers cannot be edited para preservar a estabilidade das credenciais. Editar um emissor regenera o respetivo código de verificação: se o email for igual ao e-mail da tua conta, o emissor é novamente verificado de forma automática; caso contrário, é enviado um novo e-mail de verificação para esse endereço.

PUT /issuers/{issuerId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
issuerId	string	Sim	O ID do emissor (parâmetro de caminho)
name	string	Não	Novo nome
url	string	Não	Novo URL
email	string	Não	Novo e-mail (envia um novo e-mail de verificação, a menos que seja igual ao e-mail da tua conta)
logo	string	Não	Novo logótipo codificado em Base64
linkedinOrganizationId	string	Não	Novo ID de organização do LinkedIn (ou string vazia para limpar)

Resposta

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

Erros

• 400 — verified issuers cannot be edited (o emissor já está verificado)
• 400 — not authorized (o emissor pertence a outra conta)
• 404 — emissor não encontrado