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

{
  "statusCode": 200,
  "info": {
    "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

{
  "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"
      }
    ]
  }
}

---

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

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

---

Eliminar emissor

Elimine um emissor. O emissor não pode ter distintivos.

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

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

Erros

• 400 — o emissor tem distintivos ou atribuições e não pode ser eliminado (apague-os primeiro)
• 404 — emissor não encontrado

---

Actualizar emissor

Actualize os campos de um emissor não verificado. Depois de um emissor ser verificado, apenas logo e linkedinOrganizationId ficam editáveis para preservar a estabilidade das credenciais.

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 (apenas quando não verificado)
url	string	Não	Novo URL (apenas quando não verificado)
email	string	Não	Novo e-mail (apenas quando não verificado — envia um novo e-mail de verificação)
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)

---

Rodar código de verificação

Invalida a ligação de verificação anterior e envia uma nova por e-mail. Só é válido enquanto o emissor ainda não estiver verificado.

POST /issuers/{issuerId}/rotate-code

Resposta

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