Jak wydawać odznaki Open Badge z pliku CSV w niecałe 5 minut

Jeśli kiedykolwiek wydawałeś poświadczenia dla grupy jednemu odbiorcy naraz, znasz już ten problem: nie skaluje się to powyżej mniej więcej dziesięciu osób, zanim zamieni się w popołudnie spędzone na kopiowaniu i wklejaniu nazwisk oraz adresów e-mail. Czterdziestoosobowa grupa bootcampowa, lista 500 uczestników konferencji czy wdrożenie szkolenia firmowego dla 5000 osób — wszystkie potrzebują tego samego: wgraj listę, wybierz odznakę, kliknij Wydaj i odejdź.

Dokładnie to robią Poświadczenia zbiorcze na https://badges.ninja. Ten przewodnik obejmuje cały proces: przygotowanie pliku CSV, konfigurację partii, obserwowanie jej przebiegu oraz radzenie sobie z niechlujnymi przypadkami z prawdziwego świata — wierszem odbiorcy z literówką, partią przerwaną w połowie albo programem, który chce wydawać w ten sam sposób z własnych systemów, a nie z panelu.

Zanim zaczniesz: czego potrzebujesz

Dwóch rzeczy, które prawdopodobnie już masz:

1. Odznaki — zaprojektowanej raz w wizualnym kreatorze, wykorzystywanej ponownie dla każdego odbiorcy w partii. Jeśli jeszcze żadnej nie stworzyłeś, zajrzyj do naszego poradnika o projektowaniu pierwszego weryfikowalnego certyfikatu.
2. Pliku CSV z odbiorcami — imię i nazwisko, e-mail oraz (opcjonalnie) data wydania. To cały schemat.

Nie potrzebujesz konta wystawcy na każdego odbiorcę, serwera pocztowego ani żadnego kodu. Wszystko w tej sekcji dzieje się w panelu.

Krok 1: przygotuj plik CSV

Format listy odbiorców jest celowo minimalny:

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 — wymagane. Wypełnia pole odbiorcy w asercji i na certyfikacie.
• email — wymagany. Staje się tożsamością odbiorcy w asercji Open Badge v2.0 — haszowany z solą przypisaną do danego poświadczenia przed zapisaniem, nigdy nieprzechowywany w postaci jawnej.
• issued_on — opcjonalne. Zostaw puste, a partia użyje momentu przetwarzania każdego wiersza; ustaw jawnie, jeśli uzupełniasz wstecznie grupę, która faktycznie skończyła w zeszłym miesiącu.

Większość właścicieli programów eksportuje to bezpośrednio stamtąd, gdzie i tak śledzą ukończenia — z Airtable, Arkuszy Google, arkusza przekazanego przez prowadzącego albo z pliku CSV pobranego z dziennika ocen w LMS. Nie jest wymagane żadne specjalne narzędzie eksportu; działa dowolny plik CSV z tymi trzema kolumnami.

Typowe pułapki plików CSV (i jak podgląd je wychwytuje)

Garść problemów pojawia się nieustannie w rzeczywistych listach odbiorców, zwykle dlatego, że plik CSV powstał ze złączenia dwóch lub trzech arkuszy źródłowych:

• Końcowe białe znaki w adresach e-mail — skopiowanie z listy w PDF lub eksportu z Google Form często przenosi ze sobą niewidoczną spację. Wygląda w porządku w komórce arkusza, ale nie przechodzi walidacji e-maila przy wgrywaniu.
• Zduplikowane wiersze — ten sam odbiorca pojawiający się dwukrotnie, bo lista grupy i lista spóźnionych zapisów zostały sklejone bez usuwania duplikatów.
• Niespójne formaty dat — jedna kolumna 2026-07-01 zmieszana z 07/01/2026 z innego eksportu. Trzymaj się ISO 8601 (YYYY-MM-DD) i problem znika całkowicie.
• Rozbieżności wielkości liter w nagłówkach — Email kontra email kontra E-mail. Parser wybacza typowe warianty, ale całkowicie niestandardowa nazwa nagłówka nie zmapuje się automatycznie.

Żaden z nich nie jest krytyczny — krok podglądu (poniżej) ujawnia każdy z nich, zanim cokolwiek zostanie wydane, więc naprawa to „popraw arkusz, wgraj ponownie” zamiast „ustal, który z 3000 odbiorców dostał uszkodzoną odznakę”.

Krok 2: skonfiguruj partię

W panelu otwórz Poświadczenia → Poświadczenia zbiorcze i wybierz odznakę, którą wydajesz. To krok, w którym ustawiasz wszystko, co dotyczy całej partii: samą odznakę, wspólną datę wydania, jeśli nie umieszczasz w CSV dat dla poszczególnych wierszy, oraz (jeśli twój profil wystawcy go ma) identyfikator organizacji LinkedIn, który pozwoli każdemu odbiorcy dodać poświadczenie do profilu jednym kliknięciem.

To dobry moment, by upewnić się, że wybrana odznaka to wersja ostateczna — odbiorcy zobaczą taki obraz i kryteria, jakie są do niej dołączone w chwili wydania, a nie to, co zaktualizujesz później.

Krok 3: wgraj i sprawdź podgląd

Przeciągnij plik CSV, a platforma go przetworzy, pokaże tabelę podglądu i oznaczy wszystko, czego nie może przetworzyć — brakujący e-mail, błędnie sformatowaną datę, zduplikowany wiersz. Nic nie zostaje wydane, dopóki nie potwierdzisz podglądu.

Ten krok podglądu ma większe znaczenie, niż się wydaje. Literówkę w jednym wierszu pliku CSV liczącego 2000 wierszy łatwo przeoczyć gołym okiem, a znacznie taniej jest ją wychwycić, zanim 1999 poprawnych wierszy zostanie już wydanych, niż próbować to odkręcić później. Popraw oznaczone wiersze w arkuszu, wgraj ponownie, a podgląd się zaktualizuje.

Krok 4: uruchom partię

Kliknij Wydaj, a partia zacznie się przetwarzać. Pasek postępu śledzi ukończone wiersze względem pozostałych, a partia działa po stronie serwera — nie musisz trzymać karty otwartej, a zamknięcie laptopa w połowie partii nie powoduje utraty miejsca.

Warto to ostatnie wyraźnie podkreślić, bo to szczegół, który naprawdę ma znaczenie dla dużych grup: stan partii żyje na serwerze, a nie w twojej przeglądarce. Jeśli połączenie zerwie się, laptop uśpi się albo po prostu zamkniesz kartę, bo zaczyna się spotkanie, partia dalej działa (lub wznawia dokładnie tam, gdzie ją zatrzymałeś) zamiast startować od zera. Dla czterdziestoosobowej grupy bootcampowej to miły dodatek. Dla firmowego wdrożenia na 5000 wierszy to różnica między „po prostu działa” a „ktoś musi przez dwadzieścia minut pilnować karty przeglądarki”.

Możesz też celowo wstrzymać działającą partię — powiedzmy, ktoś zgłasza, że tekst kryteriów odznaki wymaga poprawki w połowie przebiegu na 3000 wierszy — naprawić problem i wznowić bez ponownego wydawania już ukończonych wierszy.

Krok 5: obsłuż błędy

Prawdziwe listy odbiorców mają wadliwe wiersze: domenę e-maila z literówką, pole nazwiska, które faktycznie jest puste, zduplikowany wpis powstały ze złączenia dwóch wyeksportowanych arkuszy. Gdy wiersz się nie powiedzie, partia się nie zatrzymuje — przetwarza dalej resztę i oznacza błąd do późniejszego przeglądu. Otrzymujesz eksport wyników pokazujący dokładnie, które wiersze się powiodły, a które nie, dzięki czemu możesz poprawić tylko wiersze z błędem i uruchomić małą partię uzupełniającą, zamiast sprawdzać całą listę od nowa.

To ważne dla nawyku eksportu CSV, już powszechnego w panelu poświadczeń — w każdej chwili możesz pobrać plik CSV z tym, co faktycznie zostało wydane, zestawić go z listą źródłową i dokładnie wiedzieć, kto wciąż potrzebuje odznaki.

Ścieżka API: ten sam proces, bez panelu

Wszystko powyżej zakłada, że ktoś siedzi przy panelu i klika przez kreatora. Jeśli twoje ukończenia już żyją w jakimś systemie — LMS, CRM, automatyzacji arkuszy — możesz sterować tym samym procesem poświadczeń zbiorczych bezpośrednio z Awards API.

Minimalne wywołanie wydania dla pojedynczego odbiorcy wygląda tak:

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"
  }'

Albo w Pythonie, iterując po wierszach wczytanych z tego samego pliku CSV, który inaczej wgrałbyś ręcznie:

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,
            },
        )

Warto po to sięgnąć, gdy wydanie poświadczenia wyzwala coś zupełnie innego — webhook ukończenia kursu, zmiana etapu w CRM, przesłanie formularza — zamiast osoby ręcznie eksportującej plik CSV. Uwierzytelnianie oraz pełną strukturę żądania/odpowiedzi omawiamy w szybkim starcie API. Każde poświadczenie utworzone w ten sposób jest identyczne z tym utworzonym przez kreatora w panelu: ta sama asercja Open Badge v2.0, ten sam adres weryfikacji, ten sam certyfikat PDF.

Kreator w panelu kontra API: czego naprawdę potrzebujesz?

Większość zespołów zaczyna od kreatora w panelu, bo nie wymaga on niczego poza plikiem CSV, i przechodzi na API dopiero wtedy, gdy ta sama partia została uruchomiona ręcznie trzy lub cztery razy, a schemat oczywiście zasługuje na automatyzację.

Prywatność: co faktycznie jest przechowywane

Plik CSV z nazwiskami i adresami e-mail to dane osobowe, więc warto wiedzieć, co się z nimi dzieje po wgraniu. Adres e-mail odbiorcy nigdy nie jest przechowywany w postaci jawnej na samym poświadczeniu — jest haszowany z solą przypisaną do poświadczenia jako część asercji Open Badge v2.0, zgodnie z formatem tożsamości odbiorcy hashed ze specyfikacji. To ten hasz sprawdza weryfikator, a nie surowy adres. Pole nazwiska jest przechowywane w takiej postaci, w jakiej je wpisano, bo ma być widoczne na certyfikacie i stronie weryfikacji. Jeśli wiersz wymaga poprawy po wydaniu — najczęściej błędnie zapisanego nazwiska — możesz edytować lub unieważnić pojedyncze poświadczenie z panelu poświadczeń bez ruszania reszty partii.

Po partii: powiadom odbiorców

Wydanie odznaki i poinformowanie o niej odbiorcy to dwa różne kroki. Jeśli twój plik CSV nie wyzwala już e-maila przez twój własny system, panelowy proces udostępniania zbiorczego pozwala zaznaczyć wiele właśnie utworzonych poświadczeń i wysłać do wszystkich spersonalizowany e-mail udostępniający w jednym przebiegu — zobacz zbiorcze wysyłanie e-maili udostępniających, aby poznać pełny przewodnik, w tym jak personalizacja dla każdego odbiorcy (nazwisko, obraz odznaki, link weryfikacyjny) podstawiana jest automatycznie.

Kiedy Poświadczenia zbiorcze to właściwe narzędzie

Wydawanie zbiorcze to właściwy wybór, gdy rama „partii” pasuje do prawdziwego świata: grupa, która skończyła tego samego dnia, konferencja, która właśnie się zakończyła, wdrożenie szkoleniowe trafiające w termin zgodności. Jeśli natomiast wydajesz jednorazowe poświadczenia w miarę osiągania pojedynczych kamieni milowych — jeden awans, ukończenie jednego projektu — formularz pojedynczego poświadczenia jest szybszy niż składanie jednowierszowego pliku CSV.

W przypadku wszystkiego, co cykliczne — ten sam kurs prowadzony co miesiąc, ciągły potok onboardingu — powyższą ścieżkę API warto skonfigurować raz. Zamienia „uruchamiaj poświadczenia zbiorcze ręcznie dla każdej grupy” w „ukończenia już automatycznie wydają poświadczenia”, co jest wersją tego procesu, jakiej większość właścicieli programów naprawdę chce po drugiej lub trzeciej ręcznej partii.

Gotowy, by wydać swoje pierwsze weryfikowalne poświadczenie? Zacznij za darmo na badges.ninja — wizualny kreator, publiczna strona weryfikacji, certyfikat PDF, wynik w formacie Open Badge v2.0. Karta kredytowa niewymagana.