Як видавати Open Badges із CSV менш ніж за 5 хвилин

Якщо ви колись видавали облікові дані для групи по одному отримувачу за раз, то вже знаєте цю проблему: воно не масштабується далі приблизно десяти осіб, перш ніж перетворитися на цілий пообідній час копіювання й вставляння імен та адрес електронної пошти. Група буткемпу на 40 осіб, список із 500 учасників конференції чи розгортання корпоративного навчання на 5000 осіб — усім потрібне те саме: завантажити список, обрати значок, натиснути «Видати» й піти геть.

Саме це й роблять Пакетні облікові дані на https://badges.ninja. Цей покроковий огляд охоплює весь процес: підготовку вашого CSV, налаштування пакета, спостереження за його виконанням та розв’язання заплутаних реальних випадків — рядок отримувача з друкарською помилкою, пакет, перерваний посередині, чи програму, яка хоче видавати в такий самий спосіб зі своїх власних систем, а не з панелі.

Перш ніж почати: що вам потрібно

Дві речі, які ви, найімовірніше, вже маєте:

1. Значок — розроблений один раз у візуальному конструкторі та повторно використаний для кожного отримувача в пакеті. Якщо ви ще жодного не створили, перегляньте наш посібник із проєктування вашого першого верифікованого сертифіката.
2. CSV з отримувачами — ім’я, електронна пошта та (за бажанням) дата видачі. Це вся схема.

Вам не потрібен акаунт емітента на кожного отримувача, поштовий сервер чи будь-який код. Усе в цьому розділі відбувається на панелі.

Крок 1: підготуйте свій CSV

Формат списку отримувачів навмисно мінімальний:

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 — обов’язкове. Заповнює поле отримувача в асерції та на сертифікаті.
• email — обов’язковий. Стає ідентичністю отримувача в асерції Open Badge v2.0 — хешується із сіллю для кожних облікових даних перед збереженням, ніколи не зберігається у відкритому вигляді.
• issued_on — необов’язкове. Залиште порожнім, і пакет використає момент обробки кожного рядка; задайте явно, якщо ви заповнюєте заднім числом групу, яка насправді завершила минулого місяця.

Більшість власників програм експортують це прямо звідти, де вони й так відстежують завершення — з Airtable, Google Sheets, таблиці, переданої викладачем, чи CSV, витягнутого з журналу оцінок LMS. Жодного спеціального інструмента експорту не потрібно; підходить будь-який CSV із цими трьома стовпцями.

Типові пастки CSV (і як попередній перегляд їх ловить)

Жменя проблем постійно виринає в реальних списках отримувачів, зазвичай тому, що CSV зібрали, об’єднавши два-три вихідні аркуші:

• Кінцеві пробіли в адресах електронної пошти — копіювання з PDF-реєстру чи експорту Google Form часто тягне за собою невидимий пробіл. У клітинці таблиці він виглядає нормально, але не проходить перевірку електронної пошти під час завантаження.
• Дубльовані рядки — той самий отримувач з’являється двічі, бо список групи та список пізніх реєстрацій склеїли без усунення дублікатів.
• Неузгоджені формати дат — один стовпець із 2026-07-01, змішаний із 07/01/2026 з іншого експорту. Дотримуйтеся ISO 8601 (YYYY-MM-DD), і це зникає повністю.
• Розбіжності в регістрі заголовків — Email проти email проти E-mail. Парсер поблажливий до поширених варіантів, але цілковито нестандартна назва заголовка не зіставиться автоматично.

Жодна з них не фатальна — крок попереднього перегляду (нижче) виявляє кожну, перш ніж щось буде видано, тож виправлення — це «відредагуйте таблицю, завантажте ще раз», а не «з’ясуйте, хто з 3000 отримувачів отримав зіпсований значок».

Крок 2: налаштуйте пакет

На панелі відкрийте Облікові дані → Пакетні облікові дані й оберіть значок, який видаєте. Це крок, де ви задаєте все, що стосується всього пакета: сам значок, спільну дату видачі, якщо ви не вносите в CSV дати для окремих рядків, та (якщо у вашому профілі емітента він є) ідентифікатор організації LinkedIn, який дозволить кожному отримувачу додати облікові дані до свого профілю одним кліком.

Це слушна мить, щоб перевірити ще раз, що обраний значок — це остаточна версія: отримувачі побачать те зображення й критерії, які прикріплені до нього в момент видачі, а не те, що ви оновите пізніше.

Крок 3: завантажте й перегляньте

Перетягніть свій CSV, і платформа розбирає його, показує вам таблицю попереднього перегляду й позначає все, що не може обробити — відсутню електронну пошту, неправильно сформовану дату, дубльований рядок. Нічого не видається, поки ви не підтвердите попередній перегляд.

Цей крок попереднього перегляду важливіший, ніж здається. Друкарську помилку в одному рядку CSV на 2000 рядків легко проґавити оком, і набагато дешевше зловити її до того, як 1999 правильних рядків уже видано, ніж намагатися це скасувати згодом. Виправте позначені рядки у своїй таблиці, завантажте ще раз, і попередній перегляд оновиться.

Крок 4: запустіть пакет

Натисніть «Видати», і пакет починає обробку. Смуга прогресу відстежує завершені рядки проти тих, що лишилися, а пакет виконується на боці сервера — вам не треба тримати вкладку відкритою, і закриття ноутбука посеред пакета не втрачає ваше місце.

Цю останню частину варто проговорити явно, бо це та деталь, яка справді має значення для великих груп: стан пакета живе на сервері, а не у вашому браузері. Якщо з’єднання обірветься, ноутбук засне чи ви просто закриєте вкладку, бо починається нарада, пакет продовжує працювати (або відновлюється рівно з того місця, де ви його призупинили) замість перезапуску з нуля. Для групи буткемпу на 40 осіб це приємний бонус. Для корпоративного розгортання на 5000 рядків це різниця між «воно просто працює» та «хтось має двадцять хвилин няньчити вкладку браузера».

Ви також можете свідомо призупинити пакет, що виконується — скажімо, хтось зауважує, що текст критеріїв значка потребує правки посеред виконання на 3000 рядків — виправити проблему й відновити без повторної видачі вже завершених рядків.

Крок 5: обробіть невдачі

Реальні списки отримувачів містять погані рядки: домен пошти з друкарською помилкою, поле імені, яке насправді порожнє, дубльований запис через об’єднання двох експортованих аркушів. Коли рядок зазнає невдачі, пакет не зупиняється — він продовжує обробляти решту й позначає невдачу для подальшого перегляду. Ви отримуєте експорт результатів, який показує точно, які рядки вдалися, а які ні, тож ви можете виправити лише невдалі рядки й перезапустити невеликий додатковий пакет замість перевіряти весь список наново.

Це має значення для звички експортувати CSV, яка вже поширена на панелі облікових даних — ви будь-якої миті можете витягти CSV із тим, що насправді було видано, звірити його з вашим вихідним списком і точно знати, кому досі потрібен значок.

Шлях API: той самий процес, без панелі

Усе вищенаведене припускає, що хтось сидить за панеллю й клікає крізь майстра. Якщо ваші завершення вже живуть у якійсь системі — LMS, CRM, автоматизації таблиць — ви можете керувати тим самим процесом пакетних облікових даних безпосередньо з Awards API.

Мінімальний виклик видачі для окремого отримувача виглядає так:

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

Або на Python, у циклі по рядках, прочитаних із того самого CSV, який ви інакше завантажували б вручну:

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

По це варто тягнутися, коли видачу облікових даних запускає щось цілком інше — вебхук завершення курсу, зміна етапу в CRM, надсилання форми — а не людина, яка вручну експортує CSV. Ми розглядаємо автентифікацію й повну структуру запиту/відповіді у швидкому старті API. Кожні облікові дані, створені в такий спосіб, ідентичні тим, що створені через майстра на панелі: та сама асерція Open Badge v2.0, та сама URL-адреса верифікації, той самий PDF-сертифікат.

Майстер на панелі проти API: чого ви насправді хочете?

Більшість команд починають із майстра на панелі, бо він не вимагає нічого, окрім CSV, і переходять на API лише тоді, коли той самий пакет запустили вручну три-чотири рази, і схему очевидно варто автоматизувати.

Приватність: що насправді зберігається

CSV з іменами й адресами електронної пошти — це персональні дані, і варто знати, що з ними відбувається після завантаження. Адреса електронної пошти отримувача ніколи не зберігається у відкритому вигляді на самих облікових даних — вона хешується із сіллю для кожних облікових даних як частина асерції Open Badge v2.0, згідно з форматом ідентичності отримувача hashed зі специфікації. Саме цей хеш перевіряє верифікатор, а не сиру адресу. Поле імені зберігається так, як введено, бо воно має бути видимим на сертифікаті та сторінці верифікації. Якщо рядок потребує виправлення після видачі — найчастіше неправильно написаного імені — ви можете відредагувати чи відкликати окремі облікові дані з панелі облікових даних, не чіпаючи решту пакета.

Після пакета: сповістіть отримувачів

Видати значок і розповісти про нього отримувачу — це два різні кроки. Якщо ваш CSV ще не запускає лист через вашу власну систему, процес пакетного поширення на панелі дозволяє вам виділити кілька щойно створених облікових даних і надіслати всім їм персоналізований лист-поширення за один прохід — див. пакетне надсилання листів-поширень, щоб отримати повний огляд, зокрема як персоналізація для кожного отримувача (ім’я, зображення значка, посилання для верифікації) підставляється автоматично.

Коли Пакетні облікові дані — правильний інструмент

Пакетна видача — правильний вибір щоразу, коли рамка «пакет» відповідає реальному світу: група, яка завершила того самого дня, конференція, яка щойно скінчилася, розгортання навчання, що встигає до дедлайну відповідності. Якщо ж ви видаєте разові облікові дані в міру досягнення окремих віх — одне підвищення, завершення одного проєкту — то форма для окремих облікових даних швидша, ніж збирати CSV з одного рядка.

Для чогось повторюваного — той самий курс щомісяця, безперервний конвеєр онбордингу — наведений вище шлях API варто налаштувати один раз. Він перетворює «запускай пакетні облікові дані вручну для кожної групи» на «завершення вже видають облікові дані автоматично» — версію цього робочого процесу, якої більшість власників програм насправді хочуть після другого чи третього ручного пакета.

Готові видати ваші перші верифіковані облікові дані? Почніть безкоштовно на badges.ninja — візуальний конструктор, публічна сторінка верифікації, PDF-сертифікат, вихід у форматі Open Badge v2.0. Кредитна картка не потрібна.