Emitir Open Badges através da API REST do Badges Ninja: guia de início rápido

A maioria dos programas de credenciais nunca precisa de uma API. Se gerires um curso com algumas centenas de diplomados por ano, o painel faz tudo: desenhas um emblema no designer visual, carregas um CSV e cada destinatário recebe uma página de verificação e um certificado em PDF. Se é o teu caso, começa por como emitir Open Badges a partir de um CSV e volta mais tarde.

A API justifica-se quando as credenciais devem ser emitidas por outro sistema: a tua plataforma de aprendizagem marca um curso como concluído, a tua ferramenta de inscrições encerra um evento, o teu sistema de RH regista um módulo de conformidade terminado. Nestes casos, ninguém quer exportar uma folha de cálculo no fim de cada semana. Uma única chamada HTTP no momento da conclusão é mais simples, e o destinatário recebe o emblema enquanto a conquista ainda está fresca.

Este guia percorre todo o caminho em quatro chamadas: obter uma chave, criar um emissor, criar um emblema e atribuí-lo. Depois vemos como entregar a ligação de verificação ao destinatário e como confirmar o resultado. Todos os formatos de pedido abaixo vêm dos handlers em produção, por isso podes copiá-los e executá-los.

O que precisas antes de começar

• Uma conta gratuita em badges.ninja. O plano Free chega para este tutorial: inclui 2 emissores, 5 emblemas, 2 lugares e 1 chave de API.
• Uma chave de API, criada no painel.
• Um PNG ou JPG para a imagem do emblema, ou um emblema que tenhas desenhado no designer visual.

O URL base para tudo é https://api.badges.ninja.

Passo 1: Criar uma chave de API

Inicia sessão, abre API Keys na barra lateral e clica em Create API Key. Dá-lhe um nome que diga onde vai ser usada, como “LMS integration”, para distinguires as chaves quando as rodares mais tarde.

A chave é mostrada uma única vez. Copia-a de imediato para o teu gestor de segredos ou para uma variável de ambiente. As chaves têm o formato bws_ seguido de 32 caracteres hexadecimais e são enviadas no cabeçalho X-Api-Key em todos os pedidos. Revogar uma chave no mesmo ecrã tem efeito imediato.

Alguns hábitos que evitam problemas mais tarde:

• Nunca coloques a chave em código de front-end nem num repositório público. Chama a API a partir de um servidor, de uma função serverless ou de uma ferramenta de automatização.
• Usa uma chave por integração. Se uma for divulgada, revogas apenas uma integração em vez de todas.
• O painel também aceita a tua sessão iniciada (um JWT do Cognito enviado como Authorization: Bearer), mas para scripts e integrações a chave de API é a ferramenta certa.

Todos os exemplos abaixo leem a chave de uma variável de ambiente chamada BADGES_API_KEY.

Passo 2: Criar um emissor

Um emissor é a organização que garante o emblema. Aparece em todas as páginas de verificação e nos dados Open Badge v2.0, por isso usa o nome que as pessoas realmente conhecem.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

Os campos obrigatórios são name (pelo menos 3 caracteres), url (um endereço http ou https válido) e email. Os campos opcionais são logo (uma imagem codificada em base64) e linkedinOrganizationId, que ativa o botão Add to LinkedIn Profile nas tuas páginas públicas de credenciais.

A resposta contém o identificador do emissor:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Guarda esse valor exatamente como foi devolvido. É a entrada do passo seguinte.

Verificação do emissor

Os emblemas só podem ser criados sob um emissor verificado. A verificação funciona assim:

• Se o email do emissor coincidir com o email da tua conta, o emissor é verificado automaticamente. É o caminho mais rápido para um primeiro teste.
• Se o email for diferente, é enviado um email de verificação com um código para esse endereço. Confirmas o código no painel (ou através da API de emissores) antes de criares emblemas.

Portanto, neste tutorial, usa o mesmo email com que te registaste.

Passo 3: Criar um emblema

Um emblema é o modelo reutilizável: nome, descrição, critérios e imagem. Cada atribuição que emitires depois aponta para ele.

O pedido é JSON simples. A imagem segue como uma cadeia base64, por isso não há carregamento multipart com que lutar. Um prefixo de data URL como data:image/png;base64, é aceite e removido.

JavaScript (Node 18 ou posterior):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Os cinco campos (name, description, criteria, image, issuerId) são obrigatórios. Vale a pena conhecer dois opcionais: shareText, o texto predefinido que os destinatários veem ao partilhar nas redes sociais (suporta os marcadores {{badge_name}}, {{issuer_name}} e {{award_url}}), e designJson, que guarda um documento do designer visual para que o emblema possa ser editado camada a camada mais tarde.

Um sucesso devolve HTTP 200 com { "badgeId": "<id>" }. A imagem fica armazenada de forma permanente e o emblema passa a ser uma BadgeClass Open Badge v2.0 que qualquer pessoa pode consultar.

Deves mesmo criar emblemas por código?

Normalmente não. O design de emblemas é uma tarefa criativa, e o designer visual (mais de 80 modelos, formas, ícones, 11 tipos de letra e carregamentos personalizados) é um local muito melhor para isso do que um script. Um padrão comum é desenhar cada emblema uma vez no painel e depois fazer a tua integração emitir apenas atribuições sobre ele. Podes listar os teus emblemas com GET /badges e copiar o id do que pretendes.

Cria emblemas pela API quando os geras programaticamente, por exemplo um por curso num catálogo de centenas, ou quando estás a preparar um ambiente de teste.

Passo 4: Atribuir o emblema

Esta é a chamada que a tua integração fará milhares de vezes. Envia o emblema, o destinatário e a data.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

As regras em que as pessoas costumam tropeçar:

• recipient é um objeto aninhado com name e email. Campos planos como recipientEmail são rejeitados.
• recipient.name tem de ter pelo menos 5 caracteres.
• issuedOn é obrigatório. Envia milissegundos desde a época Unix ou uma data ISO como 2026-09-28.
• expires é opcional e aceita os mesmos formatos.

Um sucesso é HTTP 200 com um corpo que contém o awardId. O email do destinatário é guardado como hash SHA-256 nos dados Open Badge, pelo que o JSON público nunca o expõe.

Passo 5: Encontrar a página de verificação e o JSON Open Badge

A resposta da atribuição dá-te um identificador, não uma ligação pronta a usar. O identificador termina num GUID, e as páginas públicas são construídas a partir desse GUID:

• Página de verificação legível por pessoas: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Se o teu awardId vier como um URL completo, usa o último segmento do caminho como GUID.

Ambos são públicos. Qualquer pessoa com a ligação pode verificar a credencial sem criar conta, e é esse o objetivo: um empregador ou um responsável de admissões deve conseguir confirmar um emblema em dez segundos.

Obtém o JSON para ver o que o mundo vê:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Recebes uma Assertion Open Badge v2.0: o emblema a que se refere, a identidade do destinatário em hash, a data de emissão e um bloco de verificação que aponta para a assertion alojada. Como são dados Open Badges standard, qualquer ferramenta que perceba o formato consegue lê-los. Essa portabilidade é a razão para escolher Open Badges em vez de um PDF proprietário; Open Badges vs PDF certificates aprofunda esta comparação.

Como os destinatários recebem a credencial

Criar uma atribuição é diferente de avisar o destinatário. Os destinatários podem abrir as suas credenciais no portal do destinatário em badges.ninja/me, que usa início de sessão por magic link, sem palavra-passe, e podem publicar um perfil público em badges.ninja/u/<handle>. A partir da página de verificação, podem adicionar o emblema ao LinkedIn, descarregar o certificado em PDF ou partilhar a ligação.

Nos primeiros testes, envia uma atribuição para o teu próprio email e percorre a experiência do destinatário. É a forma mais rápida de reparar em coisas como uma descrição de emblema que soa estranha.

Tratamento de erros sem dores de cabeça

A API usa códigos de estado HTTP normais. Os que vais encontrar:

Duas dicas práticas. Primeiro, trata o 400 como um problema de dados e regista o corpo da resposta, já que indica o campo em falha. Segundo, torna a tua integração idempotente do teu lado: guarda o awardId junto do registo de conclusão na tua base de dados e verifica-o antes de voltares a chamar a API. Assim, um webhook repetido ou uma tarefa reexecutada nunca emite duas credenciais à mesma pessoa.

Juntar tudo numa integração real

Uma ligação típica é assim:

1. Desenha os emblemas no painel, um por curso ou marco, e anota o ID de cada um.
2. Guarda no teu sistema um mapeamento de curso para ID de emblema.
3. Quando um formando conclui um curso, o teu servidor chama POST /awards com o nome, o email e a data de conclusão.
4. Guarda o awardId devolvido no registo de conclusão.
5. Mostra a ligação de verificação dentro do teu próprio produto, para o formando a ver sem sair.

Se preferires não escrever código, a mesma chamada funciona a partir de qualquer ferramenta de automatização que envie um pedido HTTP com corpo JSON e um cabeçalho personalizado. Aponta-a para https://api.badges.ninja/awards e mapeia os campos do teu formulário ou folha de cálculo para badgeId, recipient.name, recipient.email e issuedOn.

Planos e limites que convém conhecer

A API está disponível em todos os planos; não pagas nada extra para a desbloquear. O plano Free ($0) cobre 2 emissores, 5 emblemas, 2 lugares, 1 chave de API e 1,200 credenciais por ano. O Starter custa $9 por mês e o Pro $29 por mês, com limites mais altos. Consulta a página de preços para ver os valores atuais antes de dimensionares uma implementação. Se estás a comparar o que outras plataformas cobram pelo acesso à API, Credly alternative apresenta os custos lado a lado.

Para onde ir a seguir

• A referência completa dos endpoints está na documentação da API, disponível em 40 idiomas.
• Para detalhes de autenticação e gestão de chaves, consulta o guia de autenticação.
• Para os códigos de erro em detalhe, consulta a referência de erros.
• Quando uma chamada de cada vez deixar de chegar, usa as atribuições em massa no painel: carrega um CSV e pausa ou retoma a execução se for preciso.

A primeira atribuição bem-sucedida é a parte difícil. Depois disso, o resto é ligar a mesma chamada aos sítios onde as conquistas já são registadas.

Pronto para emitir a tua primeira credencial verificável? Começa grátis em badges.ninja — designer visual, página pública de verificação, certificado em PDF, saída Open Badge v2.0. Sem cartão de crédito.