Como emitir Open Badges a partir de um CSV em menos de 5 minutos

Se alguma vez emitiste credenciais para uma turma um destinatário de cada vez, já conheces o problema: não escala para além de umas dez pessoas antes de se tornar uma tarde inteira a copiar e colar nomes e emails. Uma turma de bootcamp de 40 pessoas, uma lista de participantes de uma conferência com 500, ou o lançamento de uma formação empresarial para 5.000 pessoas — todos precisam da mesma coisa: carregar uma lista, escolher um emblema, clicar em Emitir e ir embora.

É exatamente isso que o Bulk Credentials em https://badges.ninja faz. Este guia percorre todo o fluxo: preparar o teu CSV, configurar o lote, vê-lo a correr e lidar com os casos confusos do mundo real — uma linha de destinatário com um erro de escrita, um lote que é interrompido a meio, ou um programa que quer emitir da mesma forma a partir dos seus próprios sistemas em vez do painel.

Antes de começar: o que precisas

Duas coisas, ambas que provavelmente já tens:

1. Um emblema — desenhado uma única vez no designer visual e reutilizado para cada destinatário do lote. Se ainda não criaste um, vê o nosso guia sobre como desenhar o teu primeiro certificado verificável.
2. Um CSV de destinatários — nome, email e (opcionalmente) uma data de emissão. É este o esquema todo.

Não precisas de uma conta de emissor por destinatário, de um servidor de email, nem de qualquer código. Tudo nesta secção acontece no painel.

Passo 1: Prepara o teu CSV

O formato da lista de destinatários é deliberadamente mínimo:

name,email,issued_on
Maria Gonzalez,maria@example.com,2026-07-01
David Kim,david@example.com,2026-07-01
Priya Patel,priya@example.com,

• name — obrigatório. Preenche o campo de destinatário na asserção e no certificado.
• email — obrigatório. Torna-se a identidade do destinatário na asserção do Open Badge v2.0 — convertido em hash com um salt por credencial antes de ser armazenado, nunca mantido em texto simples.
• issued_on — opcional. Deixa em branco e o lote usa o momento em que cada linha é processada; define-o explicitamente se estiveres a preencher retroativamente uma turma que na verdade terminou no mês passado.

A maioria dos responsáveis por programas exporta isto diretamente de onde já regista as conclusões — Airtable, Google Sheets, uma folha de cálculo entregue por um formador, ou um CSV extraído do livro de notas de um LMS. Não é preciso nenhuma ferramenta de exportação especial; qualquer CSV com essas três colunas funciona.

Armadilhas comuns do CSV (e como a pré-visualização as apanha)

Um punhado de problemas surge constantemente nas listas reais de destinatários, normalmente porque o CSV foi montado juntando duas ou três folhas de origem:

• Espaços em branco no fim dos endereços de email — um copiar e colar de uma lista em PDF ou de uma exportação do Google Forms costuma arrastar um espaço invisível. Parece bem numa célula de folha de cálculo, mas falha a validação de email ao carregar.
• Linhas duplicadas — o mesmo destinatário a aparecer duas vezes porque uma lista da turma e uma lista de inscritos tardios foram concatenadas sem remoção de duplicados.
• Formatos de data inconsistentes — uma coluna com 2026-07-01 misturada com 07/01/2026 de outra exportação. Mantém-te no ISO 8601 (YYYY-MM-DD) e isto desaparece por completo.
• Diferenças de maiúsculas nos cabeçalhos — Email vs email vs E-mail. O analisador é tolerante com as variantes comuns, mas um cabeçalho com um nome totalmente personalizado não será mapeado automaticamente.

Nenhum destes é fatal — o passo de pré-visualização (abaixo) revela cada um antes de qualquer coisa ser emitida, por isso a correção é “edita a folha de cálculo, volta a carregar” em vez de “descobre qual dos 3.000 destinatários recebeu um emblema partido”.

Passo 2: Configura o lote

No painel, abre Credentials → Bulk Credentials e escolhe o emblema que estás a emitir. Este é o passo em que defines tudo o que se aplica ao lote inteiro: o próprio emblema, uma data de emissão partilhada caso não vás pôr datas por linha no CSV, e (se o teu perfil de emissor tiver um) o ID da organização no LinkedIn que permitirá a cada destinatário adicionar a credencial ao seu perfil com um clique.

Este é um bom momento para confirmar duas vezes que o emblema que selecionaste é a versão final — os destinatários verão a imagem e os critérios anexados a ele no momento em que emitires, não o que atualizares depois.

Passo 3: Carrega e pré-visualiza

Larga o teu CSV e a plataforma analisa-o, mostra-te uma tabela de pré-visualização e assinala tudo o que não consegue processar — um email em falta, uma data malformada, uma linha duplicada. Nada é emitido até confirmares a pré-visualização.

Este passo de pré-visualização importa mais do que parece. Um erro de escrita numa linha de um CSV de 2.000 linhas é fácil de passar despercebido a olho nu, e é muito mais barato apanhá-lo antes de 1.999 linhas corretas já estarem emitidas do que tentar desfazê-lo depois. Corrige as linhas assinaladas na tua folha de cálculo, volta a carregar, e a pré-visualização atualiza-se.

Passo 4: Corre o lote

Clica em Emitir e o lote começa a processar. Uma barra de progresso acompanha as linhas concluídas face às restantes, e o lote corre do lado do servidor — não precisas de manter o separador aberto, e fechar o teu portátil a meio do lote não perde o teu lugar.

Vale a pena detalhar essa última parte porque é o detalhe que realmente importa para turmas grandes: o estado do lote vive no servidor, não no teu navegador. Se a tua ligação cair, o teu portátil entrar em suspensão, ou simplesmente fechares o separador porque começou uma reunião, o lote continua a correr (ou retoma exatamente onde ficou, se o tiveres pausado) em vez de recomeçar do zero. Para uma turma de bootcamp de 40 pessoas isto é um extra agradável. Para um lançamento empresarial de 5.000 linhas, é a diferença entre “simplesmente funciona” e “alguém tem de ficar de vigia a um separador do navegador durante vinte minutos”.

Também podes pausar de propósito um lote em execução — digamos que alguém assinala que o texto dos critérios do emblema precisa de um retoque a meio de uma ronda de 3.000 linhas — corrigir o problema e retomar sem reemitir as linhas já concluídas.

Passo 5: Lida com as falhas

As listas reais de destinatários têm linhas más: um domínio de email mal escrito, um campo de nome que na verdade está vazio, uma entrada duplicada de duas folhas exportadas que foram juntadas. Quando uma linha falha, o lote não para — continua a processar o resto e assinala a falha para revisão depois. Recebes uma exportação de resultados a mostrar exatamente que linhas tiveram sucesso e quais não, para que possas corrigir só as linhas que falharam e voltar a correr um pequeno lote de seguimento em vez de reverificar a lista inteira.

Isto importa para o hábito de exportar CSV que já é comum no painel de credenciais — podes extrair um CSV do que foi realmente emitido a qualquer momento, cruzá-lo com a tua lista de origem e saber com precisão quem ainda precisa de um emblema.

O caminho da API: mesmo fluxo, sem painel

Tudo o que está acima pressupõe que alguém está sentado no painel a clicar pelo assistente. Se as tuas conclusões já vivem num sistema — um LMS, um CRM, uma automação de folha de cálculo — podes conduzir o mesmo fluxo de credenciais em lote diretamente pela Awards API.

Uma chamada mínima de emissão por destinatário fica assim:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{
    "badgeId": "badge_9f8e7d6c5b4a",
    "recipient": {
      "name": "Maria Gonzalez",
      "email": "maria@example.com"
    },
    "issuedOn": "2026-07-01T00:00:00Z"
  }'

Ou em Python, percorrendo em ciclo as linhas lidas do mesmo CSV que de outra forma carregarias à mão:

import csv
import requests

API_KEY = "bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
BADGE_ID = "badge_9f8e7d6c5b4a"

with open("recipients.csv") as f:
    for row in csv.DictReader(f):
        requests.post(
            "https://api.badges.ninja/awards",
            headers={"X-Api-Key": API_KEY},
            json={
                "badgeId": BADGE_ID,
                "recipient": {"name": row["name"], "email": row["email"]},
                "issuedOn": row.get("issued_on") or None,
            },
        )

Vale a pena recorrer a isto quando a emissão de credenciais é despoletada por algo totalmente diferente — um webhook de conclusão de curso, uma mudança de fase no CRM, a submissão de um formulário — em vez de uma pessoa a exportar um CSV manualmente. Cobrimos a autenticação e o formato completo de pedido/resposta no guia rápido da API. Toda a credencial criada desta forma é idêntica a uma criada pelo assistente do painel: mesma asserção do Open Badge v2.0, mesmo URL de verificação, mesmo certificado em PDF.

Assistente do painel vs. API: qual queres mesmo?

A maioria das equipas começa com o assistente do painel porque não exige nada para além de um CSV, e só passa para a API depois de o mesmo lote já ter sido corrido manualmente três ou quatro vezes e o padrão claramente valer a pena automatizar.

Privacidade: o que é de facto armazenado

Um CSV de nomes e emails é dado pessoal, e vale a pena saber o que lhe acontece depois de carregado. O endereço de email do destinatário nunca é armazenado em texto simples na própria credencial — é convertido em hash com um salt por credencial como parte da asserção do Open Badge v2.0, seguindo o formato de identidade de destinatário hashed da especificação. Esse hash é o que um verificador confere, não o endereço em bruto. O campo de nome é armazenado tal como foi introduzido, já que se destina a ficar visível no certificado e na página de verificação. Se uma linha precisar de correção após a emissão — um nome mal escrito, o mais comum — podes editar ou revogar a credencial individual pelo painel de credenciais sem mexer no resto do lote.

Depois do lote: notifica os destinatários

Emitir o emblema e avisar o destinatário são dois passos distintos. Se o teu CSV já não despoleta um email pelo teu próprio sistema, o fluxo de partilha em lote do painel permite-te selecionar várias credenciais que acabaste de criar e enviar um email de partilha personalizado para todas elas de uma só vez — vê o envio em lote de emails de partilha para o guia completo, incluindo como a personalização por destinatário (nome, imagem do emblema, ligação de verificação) é substituída automaticamente.

Quando o Bulk Credentials é a ferramenta certa

A emissão em lote é a escolha certa sempre que o enquadramento de “lote” encaixa no mundo real: uma turma que terminou no mesmo dia, uma conferência que acabou de encerrar, um lançamento de formação a chegar a um prazo de conformidade. Se, em vez disso, estás a emitir credenciais pontuais à medida que marcos individuais são atingidos — uma única promoção, a conclusão de um único projeto — o formulário de credencial individual é mais rápido do que montar um CSV de uma só linha.

Para qualquer coisa recorrente — o mesmo curso a correr todos os meses, um funil de integração contínuo — o caminho da API acima vale a pena configurar uma única vez. Transforma “correr credenciais em lote manualmente a cada turma” em “as conclusões já emitem credenciais automaticamente”, que é a versão deste fluxo de trabalho que a maioria dos responsáveis por programas realmente quer depois do segundo ou terceiro lote manual.

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