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

Se você já emitiu credenciais para uma turma um destinatário de cada vez, já conhece o problema: isso não escala além de umas dez pessoas antes de virar uma tarde inteira copiando e colando nomes e e-mails. Uma turma de bootcamp de 40 pessoas, uma lista de participantes de uma conferência com 500, ou o lançamento de um treinamento corporativo para 5.000 pessoas — todos precisam da mesma coisa: enviar uma lista, escolher um emblema, clicar em Emitir e ir embora.

É exatamente isso que o Bulk Credentials no https://badges.ninja faz. Este passo a passo cobre todo o fluxo: preparar o seu CSV, configurar o lote, vê-lo rodar e lidar com os casos bagunçados do mundo real — uma linha de destinatário com um erro de digitação, um lote que é interrompido no meio do caminho, 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 você precisa

Duas coisas, ambas que você provavelmente já tem:

1. Um emblema — desenhado uma única vez no designer visual e reutilizado para cada destinatário do lote. Se você ainda não criou um, veja o nosso guia sobre como desenhar o seu primeiro certificado verificável.
2. Um CSV de destinatários — nome, e-mail e (opcionalmente) uma data de emissão. Esse é todo o esquema.

Você não precisa de uma conta de emissor por destinatário, de um servidor de e-mail, nem de nenhum código. Tudo nesta seção acontece no painel.

Passo 1: Prepare o seu 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 puro.
• issued_on — opcional. Deixe em branco e o lote usa o momento em que cada linha é processada; defina explicitamente se você estiver preenchendo retroativamente uma turma que na verdade terminou no mês passado.

A maioria dos responsáveis por programas exporta isso direto de onde já acompanha as conclusões — Airtable, Google Sheets, uma planilha entregue por um instrutor, ou um CSV puxado do diário 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 pega)

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

• Espaços em branco no final dos endereços de e-mail — um copiar e colar de uma lista em PDF ou de uma exportação do Google Forms costuma carregar um espaço invisível. Parece bem numa célula de planilha, mas falha na validação de e-mail ao enviar.
• Linhas duplicadas — o mesmo destinatário aparecendo duas vezes porque uma lista da turma e uma lista de inscritos atrasados foram concatenadas sem remoção de duplicatas.
• Formatos de data inconsistentes — uma coluna com 2026-07-01 misturada com 07/01/2026 de outra exportação. Fique com o ISO 8601 (YYYY-MM-DD) e isso 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 nome totalmente personalizado não será mapeado automaticamente.

Nenhum desses é fatal — o passo de pré-visualização (abaixo) revela cada um antes de qualquer coisa ser emitida, então a correção é “edite a planilha, reenvie” em vez de “descubra qual dos 3.000 destinatários recebeu um emblema quebrado”.

Passo 2: Configure o lote

No painel, abra Credentials → Bulk Credentials e escolha o emblema que você está emitindo. Este é o passo em que você define tudo o que se aplica ao lote inteiro: o próprio emblema, uma data de emissão compartilhada caso você não vá colocar datas por linha no CSV, e (se o seu 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 conferir duas vezes se o emblema que você selecionou é a versão final — os destinatários verão a imagem e os critérios anexados a ele no momento em que você emitir, não o que você atualizar depois.

Passo 3: Envie e pré-visualize

Solte o seu CSV e a plataforma o analisa, mostra uma tabela de pré-visualização e sinaliza tudo o que não consegue processar — um e-mail faltando, uma data malformada, uma linha duplicada. Nada é emitido até você confirmar a pré-visualização.

Este passo de pré-visualização importa mais do que parece. Um erro de digitação numa linha de um CSV de 2.000 linhas é fácil de passar despercebido a olho nu, e é muito mais barato pegá-lo antes que 1.999 linhas corretas já tenham sido emitidas do que tentar desfazer isso depois. Corrija as linhas sinalizadas na sua planilha, reenvie, e a pré-visualização se atualiza.

Passo 4: Rode o lote

Clique em Emitir e o lote começa a processar. Uma barra de progresso acompanha as linhas concluídas contra as restantes, e o lote roda no lado do servidor — você não precisa manter a aba aberta, e fechar o seu notebook no meio do lote não perde o seu lugar.

Vale a pena detalhar essa última parte porque é o detalhe que realmente importa para turmas grandes: o estado do lote fica no servidor, não no seu navegador. Se a sua conexão cair, o seu notebook entrar em suspensão, ou você simplesmente fechar a aba porque uma reunião começou, o lote continua rodando (ou retoma exatamente de onde parou, se você tiver pausado) em vez de recomeçar do zero. Para uma turma de bootcamp de 40 pessoas, isso é um bônus. Para um lançamento corporativo de 5.000 linhas, é a diferença entre “simplesmente funciona” e “alguém tem que ficar de babá de uma aba do navegador por vinte minutos”.

Você também pode pausar um lote em execução de propósito — digamos que alguém sinalize que o texto dos critérios do emblema precisa de um ajuste no meio de uma rodada de 3.000 linhas — corrigir o problema e retomar sem reemitir as linhas já concluídas.

Passo 5: Lide com as falhas

Listas reais de destinatários têm linhas ruins: um domínio de e-mail digitado errado, um campo de nome que na verdade está vazio, uma entrada duplicada de duas planilhas exportadas que foram juntadas. Quando uma linha falha, o lote não para — ele continua processando o resto e sinaliza a falha para revisão depois. Você recebe uma exportação de resultados mostrando exatamente quais linhas tiveram sucesso e quais não, para que você possa corrigir só as linhas que falharam e rodar um pequeno lote de acompanhamento em vez de reconferir a lista inteira.

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

O caminho da API: mesmo fluxo, sem painel

Tudo acima pressupõe que alguém está sentado no painel clicando pelo assistente. Se as suas conclusões já vivem em um sistema — um LMS, um CRM, uma automação de planilha — você pode dirigir 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 loop as linhas lidas do mesmo CSV que você de outra forma enviaria à 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 isso quando a emissão de credenciais é disparada por algo totalmente diferente — um webhook de conclusão de curso, uma mudança de estágio no CRM, o envio de um formulário — em vez de uma pessoa exportando um CSV manualmente. Cobrimos a autenticação e o formato completo de requisição/resposta no guia rápido da API. Toda credencial criada desta forma é idêntica a uma criada pelo assistente do painel: mesma asserção do Open Badge v2.0, mesma URL de verificação, mesmo certificado em PDF.

Assistente do painel vs. API: qual você realmente quer?

A maioria das equipes começa com o assistente do painel porque ele não exige nada além de um CSV, e só migra para a API depois que o mesmo lote já foi rodado manualmente três ou quatro vezes e o padrão claramente vale a pena automatizar.

Privacidade: o que de fato é armazenado

Um CSV de nomes e e-mails é dado pessoal, e vale a pena saber o que acontece com ele depois do envio. O endereço de e-mail do destinatário nunca é armazenado em texto puro na própria credencial — ele é 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 bruto. O campo de nome é armazenado como foi digitado, 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 escrito errado, o mais comum — você pode editar ou revogar a credencial individual pelo painel de credenciais sem mexer no resto do lote.

Depois do lote: notifique os destinatários

Emitir o emblema e avisar o destinatário são dois passos distintos. Se o seu CSV já não dispara um e-mail pelo seu próprio sistema, o fluxo de compartilhamento em lote do painel permite que você selecione várias credenciais que acabou de criar e envie um e-mail de compartilhamento personalizado para todas elas de uma só vez — veja o envio em lote de e-mails de compartilhamento para o passo a passo completo, incluindo como a personalização por destinatário (nome, imagem do emblema, link 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” combina com o mundo real: uma turma que terminou no mesmo dia, uma conferência que acabou de encerrar, um lançamento de treinamento chegando a um prazo de conformidade. Se, em vez disso, você está emitindo 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 linha só.

Para qualquer coisa recorrente — o mesmo curso rodando todo mês, um funil de onboarding contínuo — o caminho da API acima vale a pena configurar uma única vez. Ele transforma “rodar 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 sua primeira credencial verificável? Comece 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.