Referência da API de emblemas: criar, verificar e recuperar emblemas

Gerencie modelos de emblemas — as credenciais que você emite para os destinatários.

Para emitir este emblema para vários destinatários de uma só vez por meio de upload de CSV, em vez da API, consulte Credenciais em massa.

Todos os endpoints exigem autenticação por meio do cabeçalho X-Api-Key. Consulte Autenticação.

Criar emblema

Crie um novo emblema em um emissor verificado.

POST /badges

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Título do emblema
description	string	Sim	O que o emblema representa
criteria	string	Sim	O que o destinatário fez para conquistar este emblema
image	string	Sim	Imagem codificada em Base64 (PNG ou JPG)
issuerId	string	Sim	O ID do emissor verificado
shareText	string	Não	Texto padrão de compartilhamento social para este emblema. Aceita os marcadores , e . Se omitido, usa um padrão interno.
designJson	string	Não	Documento serializado do designer de emblemas, armazenado para que o emblema possa ser reeditado camada por camada mais tarde.

Exemplo

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Resposta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Observações

• O emissor precisa estar verificado antes de você criar emblemas.
• A imagem é armazenada no Amazon S3 e servida pelo nosso CDN global em uma URL imutável, baseada no conteúdo.
• Depois que uma classe de emblema existir, emita-a para os destinatários usando a API de credenciais.

---

Listar emblemas

Recupere todos os emblemas que você criou.

GET /badges

Exemplo

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

Resposta

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Obter emblema

Recupere um único emblema, incluindo o texto de compartilhamento e o documento serializado do designer de emblemas (designJson). Este é o endpoint que o modal Editar emblema usa para reidratar cada camada; o endpoint de listagem omite designJson para manter as respostas enxutas.

GET /badges/{badgeId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	O ID do emblema (parâmetro de caminho)

Exemplo

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

O texto de compartilhamento sempre é incluído. A variante mais leve de listagem GET /badges?badgeId={id} retorna o mesmo documento sem designJson e só inclui o texto de compartilhamento quando chamada com includeShareText=true.

---

Atualizar emblema

Atualize um emblema existente. Somente os campos que você informar são alterados.

PUT /badges/{badgeId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	O ID do emblema (parâmetro de caminho)
name	string	Não	Novo título do emblema
description	string	Não	Nova descrição
criteria	string	Não	Novos critérios
image	string	Não	Nova imagem codificada em Base64
designJson	string	Não	Novo documento serializado do designer de emblemas.

Exemplo

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Resposta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Atualizar texto de compartilhamento

Defina o texto personalizado exibido quando os destinatários compartilham este emblema nas redes sociais.

PUT /badges/{badgeId}/share-text

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	O ID do emblema (parâmetro de caminho)
text	string	Sim	Texto de compartilhamento (HTML não é permitido)

Exemplo

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Resposta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Excluir emblema

Exclua um emblema. O emblema não pode ter credenciais.

DELETE /badges/{badgeId}

Exemplo

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

Retorna uma string simples de confirmação:

"badge has been deleted"

Erros

• 400 — o emblema ainda tem credenciais emitidas: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — emblema não encontrado