API de emissores

Gerencie emissores de distintivos — as organizações ou pessoas que concedem 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 concessão 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 no limite de emissores do seu plano (Free: 1, Starter: 5, Pro: ilimitado). Não desconta cota.
• Se o e-mail do emissor coincide com o 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.

---

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 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 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 string simples:

"issuer has been verified"

---

Excluir emissor

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

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 a ele: issuer has {n} badge(s) linked — delete the badges first. A exclusão é bloqueada apenas por distintivos vinculados — concessões não a impedem.
• 404 — emissor não encontrado

---

Atualizar emissor

Atualiza os campos de um emissor. Apenas emissores não verificados podem ser editados — após um emissor ser verificado, este endpoint retorna 400 verified issuers cannot be edited, para preservar a estabilidade das credenciais. Editar um emissor regenera seu código de verificação: se o email coincidir com o e-mail da sua conta, o emissor é reverificado automaticamente; 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 coincida com o e-mail da sua conta)
logo	string	Não	Novo logo codificado em Base64
linkedinOrganizationId	string	Não	Novo ID de organização do LinkedIn (ou string vazia para remover)

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