API de emissores

Gerencie emissores de distintivos — as organizações ou pessoas que emitem distintivos.

Todos os endpoints exigem autenticação pelo cabeçalho X-Api-Key. Veja Autenticação.

Criar emissor

Cria 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	Site da organização (precisa ser uma URL HTTP/HTTPS válida)
email	string	Sim	E-mail de contato 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, toda página pública de credencial deste emissor exibe 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"
}

Observações

• Conta para o limite de emissores do seu plano (Free: 2, Starter: 5, Pro: 10). Sem dedução de cota.
• Se o e-mail do emissor for igual ao e-mail da sua conta, o emissor é verificado automaticamente.
• Se o e-mail for diferente, um e-mail de verificação é enviado ao e-mail do emissor.
• Depois de configurar um emissor, use a API de credenciais para começar a emitir credenciais por esse emissor.

---

Listar emissores

Recupera todos os emissores que você 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 cabem em uma página, um lastEvaluatedKey também é retornado para paginação.

---

Verificar emissor

Verifica um emissor usando o código de verificação enviado ao e-mail dele.

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"

---

Excluir emissor

Exclui um emissor. O emissor não pode ter distintivos vinculados.

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 distintivos vinculados: issuer has {n} badge(s) linked — delete the badges first. A exclusão depende apenas dos distintivos vinculados — as credenciais não a bloqueiam.
• 404 — emissor não encontrado

---

Atualizar emissor

Atualiza os campos de um emissor. Somente emissores não verificados podem ser editados — depois que um emissor é verificado, este endpoint retorna 400 verified issuers cannot be edited para preservar a estabilidade das credenciais. Editar um emissor regenera o código de verificação: se o email for igual ao e-mail da sua conta, o emissor é verificado novamente de forma automática; caso contrário, um novo e-mail de verificação é enviado a 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	Nova 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 sua conta)
logo	string	Não	Novo logotipo 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