API de distintivos

Gerencie modelos de distintivo — as credenciais que você concede aos destinatários.

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

Criar distintivo

Cria um novo distintivo sob um emissor verificado.

POST /badges

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Título do distintivo
description	string	Sim	O que o distintivo representa
criteria	string	Sim	O que o destinatário fez para obtê-lo
image	string	Sim	Imagem codificada em Base64 (PNG ou JPG)
issuerId	string	Sim	ID do emissor verificado
shareText	string	Não	Texto padrão de compartilhamento social para este distintivo. Suporta os marcadores , e . Recorre a um padrão embutido se omitido.
designJson	string	Não	Documento serializado do designer de distintivo, armazenado para que o distintivo 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 criar distintivos.
• A imagem é enviada ao IPFS para armazenamento permanente.

---

Listar distintivos

Recupera todos os distintivos 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://ipfs.ninja/ipfs/Qm...",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Obter distintivo

Recupera um único distintivo, incluindo seu texto de compartilhamento e o documento serializado do designer de distintivo (designJson). Este é o endpoint que o modal de Editar distintivo usa para reidratar as camadas individuais; 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	ID do distintivo (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://ipfs.ninja/ipfs/Qm...",
  "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 de listagem mais leve GET /badges?badgeId={id} retorna o mesmo documento sem designJson, e só inclui o texto de compartilhamento quando chamada com includeShareText=true.

---

Atualizar distintivo

Atualiza um distintivo existente. Apenas os campos informados são alterados.

PUT /badges/{badgeId}

Parâmetros

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

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

Define o texto personalizado exibido quando os destinatários compartilham este distintivo nas redes sociais.

PUT /badges/{badgeId}/share-text

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	ID do distintivo (parâmetro de caminho)
text	string	Sim	Texto de compartilhamento (sem HTML)

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 distintivo

Exclui um distintivo. O distintivo não pode ter concessões.

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 de confirmação simples:

"badge has been deleted"

Erros

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