Emitindo Open Badges pela API REST do Badges Ninja: guia de início rápido

A maioria dos programas de credenciais nunca precisa de uma API. Se você dá um curso com algumas centenas de formandos por ano, o painel faz tudo: você desenha um emblema no designer visual, envia um CSV e cada destinatário recebe uma página de verificação e um certificado em PDF. Se esse é o seu caso, comece por como emitir Open Badges a partir de um CSV e volte depois.

A API conquista seu lugar quando as credenciais precisam ser emitidas por outro sistema: sua plataforma de aprendizagem marca um curso como concluído, sua ferramenta de inscrições encerra um evento, seu sistema de RH registra um módulo de compliance finalizado. Nesses casos, ninguém quer exportar uma planilha no fim de toda 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 concedê-lo. Depois, vemos como entregar o link de verificação ao destinatário e conferir o resultado. Todos os formatos de requisição abaixo vêm dos handlers em produção, então você pode copiar, colar e executar.

O que você precisa antes de começar

• Uma conta gratuita no badges.ninja. O plano Free basta para este tutorial: inclui 2 emissores, 5 emblemas, 2 assentos 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 você desenhou no designer visual.

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

Passo 1: Crie uma chave de API

Entre na sua conta, abra API Keys na barra lateral e clique em Create API Key. Dê um nome que diga onde ela vai viver, como “LMS integration”, para distinguir as chaves quando você for rotacioná-las mais tarde.

A chave é exibida uma única vez. Copie-a na hora para o seu gerenciador de segredos ou para uma variável de ambiente. As chaves têm o formato bws_ seguido de 32 caracteres hexadecimais, e você as envia no cabeçalho X-Api-Key em toda requisição. Revogar uma chave na mesma tela tem efeito imediato.

Alguns hábitos que evitam dor de cabeça depois:

• Nunca coloque a chave em código de front-end nem em um repositório público. Chame a API a partir de um servidor, de uma função serverless ou de uma ferramenta de automação.
• Use uma chave por integração. Se uma vazar, você revoga uma integração em vez de todas.
• O painel também aceita sua sessão autenticada (um JWT do Cognito enviado como Authorization: Bearer), mas, para scripts e integrações, a ferramenta certa é a chave de API.

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

Passo 2: Crie um emissor

Um emissor é a organização que respalda o emblema. Ele aparece em cada página de verificação e dentro dos dados do Open Badge v2.0, então use 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 suas 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"
}

Guarde esse valor exatamente como foi retornado. Ele é a entrada do próximo passo.

Verificação do emissor

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

• Se o e-mail do emissor coincide com o e-mail da sua conta, o emissor é verificado automaticamente. É o caminho mais rápido para um primeiro teste.
• Se o e-mail for diferente, um e-mail de verificação com um código é enviado a esse endereço. Você confirma o código no painel (ou pela API de emissores) antes de criar emblemas.

Então, neste tutorial, use o mesmo e-mail com que você se cadastrou.

Passo 3: Crie um emblema

Um emblema é o modelo reutilizável: nome, descrição, critérios e imagem. Cada concessão que você emitir depois aponta de volta para ele.

A requisição é JSON puro. A imagem vai como string em base64, então não há upload multipart para complicar a vida. Um prefixo de data URL como data:image/png;base64, é aceito 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 conhecer dois opcionais: shareText, o texto padrão que os destinatários veem ao compartilhar nas redes sociais (aceita 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 por camada depois.

Um sucesso retorna HTTP 200 com { "badgeId": "<id>" }. A imagem é armazenada permanentemente, e o emblema agora é uma BadgeClass do Open Badge v2.0 que qualquer pessoa pode consultar.

Você deve mesmo criar emblemas por código?

Em geral, não. O design de emblemas é uma tarefa criativa, e o designer visual (mais de 80 modelos, formas, ícones, 11 fontes e uploads personalizados) é um lugar muito melhor para isso do que um script. Um padrão comum é desenhar cada emblema uma vez no painel e fazer sua integração apenas emitir concessões contra ele. Você pode listar seus emblemas com GET /badges e copiar o id do que quiser.

Crie emblemas pela API quando você os gera de forma programática, por exemplo um por curso em um catálogo de centenas, ou quando está preparando um ambiente de testes.

Passo 4: Conceda o emblema

Esta é a chamada que sua integração fará milhares de vezes. Envie 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 que costumam pegar as pessoas:

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

Um sucesso é um HTTP 200 com um corpo contendo o awardId. O e-mail do destinatário é armazenado como hash SHA-256 nos dados do Open Badge, então o JSON público nunca o expõe.

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

A resposta da concessão traz um identificador, não um link pronto. O identificador termina em um GUID, e as páginas públicas são montadas a partir desse GUID:

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

Se o seu awardId voltar como uma URL completa, use o último segmento do caminho como GUID.

Ambas são públicas. Qualquer pessoa com o link pode verificar a credencial sem criar uma conta, e esse é justamente o ponto: um empregador ou um responsável por admissões deve conseguir conferir um emblema em dez segundos.

Busque o JSON para ver o que o mundo vê:

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

Você recebe uma Assertion do Open Badge v2.0: o emblema ao qual ela se refere, a identidade do destinatário em hash, a data de emissão e um bloco de verificação apontando de volta para a assertion hospedada. Por serem dados padrão do Open Badges, qualquer ferramenta que entenda o formato consegue lê-los. Essa portabilidade é o motivo para escolher Open Badges em vez de um PDF proprietário; Open Badges vs PDF certificates aprofunda essa comparação.

Como os destinatários recebem a credencial

Criar uma concessão é separado de avisar o destinatário. Os destinatários podem abrir suas credenciais pelo portal do destinatário em badges.ninja/me, que usa login com link mágico, sem senha, e podem publicar um perfil público em badges.ninja/u/<handle>. Na página de verificação, eles podem adicionar o emblema ao LinkedIn, baixar o certificado em PDF ou compartilhar o link.

Nos primeiros testes, envie uma concessão para o seu próprio e-mail e percorra a experiência do destinatário. É a forma mais rápida de notar coisas como uma descrição de emblema que soa estranha.

Tratamento de erros sem dor

A API usa códigos de status HTTP comuns. Os que você vai encontrar:

Duas dicas práticas. Primeiro, trate o 400 como um problema de dados e registre o corpo da resposta, já que ele nomeia o campo com falha. Segundo, torne sua integração idempotente do seu lado: guarde o awardId junto ao registro de conclusão no seu próprio banco de dados e verifique-o antes de chamar a API de novo. Assim, um webhook reenviado ou um job executado outra vez nunca emitirá duas credenciais para a mesma pessoa.

Juntando tudo em uma integração real

Uma ligação típica é assim:

1. Desenhe os emblemas no painel, um por curso ou marco, e anote o ID de cada um.
2. Guarde no seu sistema um mapeamento de curso para ID de emblema.
3. Quando um aluno conclui um curso, seu servidor chama POST /awards com nome, e-mail e data de conclusão.
4. Salve o awardId retornado no registro de conclusão.
5. Mostre o link de verificação dentro do seu próprio produto, para que o aluno o veja sem sair dele.

Se você prefere não escrever código, a mesma chamada funciona em qualquer ferramenta de automação que consiga enviar uma requisição HTTP com corpo JSON e um cabeçalho personalizado. Aponte-a para https://api.badges.ninja/awards e mapeie os campos do seu formulário ou planilha para badgeId, recipient.name, recipient.email e issuedOn.

Planos e limites que vale conhecer

A API está disponível em todos os planos; você não paga a mais para liberá-la. O plano Free ($0) cobre 2 emissores, 5 emblemas, 2 assentos, 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 maiores. Consulte a página de preços para ver os números atuais antes de dimensionar uma implantação. Se você está comparando o que outras plataformas cobram pelo acesso à API, Credly alternative mostra os custos lado a lado.

Para onde ir a seguir

• A referência completa de endpoints está na documentação da API, disponível em 40 idiomas.
• Para detalhes de autenticação e manuseio de chaves, veja o guia de autenticação.
• Para os códigos de erro em profundidade, veja a referência de erros.
• Quando uma chamada por vez não bastar mais, use as concessões em massa do painel: envie um CSV e pause ou retome a execução se precisar.

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

Pronto para emitir sua primeira credencial digital verificável? Comece de graça no 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.