API de emissores

Faça a gestão dos emissores de distintivos — as organizações ou pessoas que atribuem distintivos.

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

Criar emissor

Crie um novo emissor de distintivos.

POST /issuers

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da organização (mínimo de 3 caracteres)
url	string	Sim	Sítio web 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, cada página pública de atribuição deste emissor apresenta 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 seu plano (Free: 1, Starter: 5, Pro: ilimitado). Sem dedução de quota.
• Se o e-mail do emissor coincidir com o e-mail da sua conta, o emissor fica auto-verificado.
• Se for diferente, é enviado um e-mail de verificação para o e-mail do emissor.

---

Listar emissores

Obtenha todos os emissores que criou.

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

Verifique um emissor usando 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	ID do emissor (parâmetro de caminho)
code	string	Sim	O código de verificação do 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 cadeia simples:

"issuer has been verified"

---

Eliminar emissor

Elimine um emissor. O emissor não pode ter distintivos 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 cadeia simples:

"issuer has been deleted"

Erros

• 400 — o emissor ainda tem distintivos associados: issuer has {n} badge(s) linked — delete the badges first. A eliminação é bloqueada apenas por distintivos associados — as atribuições não a impedem.
• 404 — emissor não encontrado

---

Actualizar emissor

Actualize os campos de um emissor. Apenas 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 seu código de verificação: se o email coincidir com o e-mail da sua conta, o emissor é reverificado automaticamente; 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	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 coincida com o e-mail da sua conta)
logo	string	Não	Novo logótipo em base64
linkedinOrganizationId	string	Não	Novo ID de organização no LinkedIn (ou cadeia 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