API de distintivos

Faça a gestão de modelos de distintivos — as credenciais que atribui a destinatários.

Todos os endpoints requerem autenticação através do cabeçalho X-Api-Key. Consulte Autenticação.

Criar distintivo

Crie 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	Aquilo que o distintivo representa
criteria	string	Sim	O que o destinatário fez para obter este distintivo
image	string	Sim	Imagem codificada em base64 (PNG ou JPG)
issuerId	string	Sim	O ID do emissor verificado
shareText	string	Não	Texto predefinido de partilha social para este distintivo. Suporta os marcadores , e . Recorre a um valor predefinido interno se for omitido.
designJson	string	Não	Documento serializado do editor de distintivos, guardado para que o distintivo possa ser reeditado camada a 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"
}

Notas

• O emissor tem de estar verificado para poder criar distintivos.
• A imagem é enviada para o IPFS para armazenamento permanente.

---

Listar distintivos

Obtenha todos os distintivos que 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

Obtenha um único distintivo, incluindo o respectivo texto de partilha e o documento serializado do editor de distintivos (designJson). Este é o endpoint que a janela Editar distintivo utiliza para reidratar camadas individuais; o endpoint de listagem omite designJson para manter as respostas leves.

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 partilha é sempre incluído. A variante de listagem mais leve GET /badges?badgeId={id} devolve o mesmo documento sem designJson, e apenas inclui o texto de partilha quando é chamada com includeShareText=true.

---

Actualizar distintivo

Actualize um distintivo existente. Apenas os campos que indicar 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 editor de distintivos.

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
}

---

Actualizar texto de partilha

Defina o texto personalizado que aparece quando os destinatários partilham 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 partilha (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-..."
}

---

Eliminar distintivo

Elimine um distintivo. O distintivo não pode ter atribuiçõ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

Devolve uma string de confirmação simples:

"badge has been deleted"

Erros

• 400 — o distintivo ainda tem atribuiçõ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