Как отозвать Open Badge (и что происходит с копией получателя)

Отзыв в Open Badges: как он работает, что меняется для получателя и как правильно действовать в случаях «выдано по ошибке», «срок действия истёк» и «нарушение правил».

Nacho Coll Автор Обновлено 9 мин чтения
Отзыв в Open Badges: как он работает, что меняется для получателя и как правильно действовать в случаях «выдано по ошибке», «срок действия истёк» и «нарушение правил».

Рано или поздно каждой программе, выдающей цифровые документы о квалификации, приходится забирать один из них обратно. Сертификат ушёл не тому человеку. Выяснилось, что слушатель сжульничал на итоговом экзамене. Контракт с партнёром закончился, и значки «Certified Partner» больше не должны считаться действительными. Выдача — это удачный сценарий; отзыв определяет, можно ли вашим документам действительно доверять.

В этом руководстве объясняется, как работает отзыв в Open Badges, что получатель видит и чего не видит после него, и как отозвать один документ или несколько сотен на https://badges.ninja — через панель управления или API.

Что означает «отозвать» в Open Badges

В спецификации Open Badges v2.0 каждый выданный значок — это assertion: небольшой JSON-LD-документ по публичному URL, который сообщает: «этот издатель присудил этот значок этому получателю в эту дату». Отзыв — это просто изменение этого размещённого документа. В assertion появляется "revoked": true и, при желании, строка "revocationReason" с объяснением причины.

У такого устройства есть важное следствие, которое удивляет многих владельцев программ:

  • Размещённый assertion — источник истины. Любой, кто проверяет документ, открыв URL assertion или страницу верификации, сразу видит статус «отозван».
  • Копии не отзываются. Если получатель скачал изображение значка или JSON либо закрепил его в портфолио, этот файл не меняется. В нём по-прежнему есть ссылка на ваш размещённый assertion, поэтому верификатор, перейдя по ссылке, увидит отзыв, а человек, мельком взглянувший на сохранённый PNG, — нет.

Таким образом, отзыв — это заявление на конечной точке верификации, а не удаление. Представьте, что вы ставите штамп «НЕДЕЙСТВИТЕЛЬНО» на главной записи, а не гоняетесь за каждой ксерокопией.

Если хотите подробнее рассмотреть сам документ, наш разбор Open Badge JSON-LD проходит по каждому полю.

Отозвать, выдать заново или удалить: выберите правильное действие

Прежде чем нажимать что-либо, решите, какое из трёх действий подходит к ситуации. Они не взаимозаменяемы.

СитуацияЛучшее действиеПочему
Документ выдан не тому человеку или с опечаткойУдалить (если не отправлялся) или отозвать, затем выдать зановоУдаление стирает запись полностью; отзыв сохраняет аудиторский след
Слушатель нарушил правила или получил документ недобросовестноОтозвать, с указанием причиныЗапись остаётся проверяемой как отозванная — это то, что нужно при споре
Срок действия документа просто закончилсяНичего не делать; задавайте срок действия при выдачеИстечение срока — обычное событие жизненного цикла, а не отзыв
Программа отменена, поток аннулированМассовый отзывОдна задача, одна причина, применяется ко всем
Данные были неверны, но в остальном документ действителенОтредактировать до отправки либо отозвать и выдать заново после отправкиНе портит впечатление получателя

Два практических правила:

  1. Для всего реального предпочитайте отзыв удалению. Публичная страница удалённого документа возвращает ошибку «не найдено». Отозванный документ по-прежнему открывается и чётко сообщает, что он отозван, — это гораздо лучшее свидетельство, если позже кто-то спросит, что произошло.
  2. Никогда не используйте отзыв вместо срока действия. Если документ действителен только два года, задайте дату окончания при выдаче. Значок, который тихо истёк, — это не то же самое, что значок, который был отозван, и ваша страница верификации должна говорить, о чём именно речь.

Отзыв из панели управления

Для нескольких документов панель — самый быстрый путь, и код не нужен.

  1. Войдите и откройте Awards в боковом меню.
  2. Найдите документ. В списке показаны получатель, название значка, дата выдачи и срок действия; можно искать по получателю.
  3. Нажмите на строку (или View), чтобы открыть окно с деталями документа.
  4. Нажмите Revoke.
  5. В диалоге подтверждения при желании введите причину и при желании отметьте Email the recipient that their credential was revoked.
  6. Подтвердите.

Award detail modal

Документ остаётся в вашем списке с красной меткой Revoked рядом с получателем, так что вы и ваша команда всегда видите, что было отозвано. Отзыв не возвращает документ в квоту вашего тарифа. Вы его выдали — он засчитан.

Замечание о поле причины

Причина необязательна, но заполняйте её. Она хранится вместе с документом, появляется как revocationReason в публичном assertion Open Badges и входит в payload вебхука, который получают ваши системы. Поскольку она публична в assertion, пишите её так, как писали бы для постороннего читателя. «Выдано по ошибке» или «Программа отменена» — нормально. «Джейн списала на вопросе 14» — нет. Личные подробности храните в своих записях, а публичную причину делайте нейтральной.

Стоит ли уведомлять получателя по почте?

Обычно да. Слушатель, узнавший, что его документ аннулирован, только когда работодатель нажал на ссылку верификации, имеет полное право быть вами недоволен. Уведомление включается по желанию именно потому, что некоторые отзывы (например, массовая очистка тестовых наград) никого не должны беспокоить. Наша рекомендация:

  • Отправляйте письмо, когда отзыв затрагивает реального человека, который может всё ещё демонстрировать документ.
  • Пропускайте письмо, когда вы наводите порядок в тестовых данных или аннулируете документы, которые так и не были отправлены.

Отзыв многих документов сразу

Программам редко нужно отзывать один документ изолированно; чаще речь идёт о целом потоке. В списке Awards:

  1. Отметьте флажками документы, которые хотите отозвать.
  2. Нажмите Revoke selected в панели массовых действий.
  3. Добавьте причину, решите, уведомлять ли получателей, и подтвердите.

Массовый отзыв выполняется как надёжная фоновая задача, поэтому несколько сотен документов не вызовут тайм-аут вкладки браузера. Уже отозванные документы пропускаются, а не обрывают пакет, и задачу, прерванную на полпути, можно возобновить. Тот же механизм лежит в основе массовой выдачи из таблицы, о которой мы рассказываем в статье как выдавать Open Badges из CSV.

Отзыв через API

Если ваша обучающая система или HR-платформа решает, кто больше не сертифицирован, вы можете отзывать программно. Конечная точка — POST /awards/{awardId}/revoke, аутентификация по API-ключу (X-Api-Key: bws_<32-hex>) или по Bearer-токену Cognito. ID награды указывается в пути; reason и notify передаются в JSON-теле, оба необязательны.

С помощью curl:

curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
  -H "X-Api-Key: bws_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}

На JavaScript:

const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true

И на Python:

import requests
res = requests.post(
    f"https://api.badges.ninja/awards/{award_id}/revoke",
    headers={"X-Api-Key": API_KEY},
    json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"])  # True

Несколько практических деталей, которые стоит знать:

  • Операция идемпотентна. Повторный отзыв уже отозванного документа возвращает тот же успешный ответ и не отправляет второе уведомление. Поэтому её безопасно вызывать из задачи с повторными попытками.
  • Причины обрезаются до 500 символов.
  • notify по умолчанию false. Письма не отправляются, пока вы не попросите.
  • Массовый отзыв доступен через массовую конечную точку с action: "revoke" и списком ID наград; она возвращает ID задачи, которую можно отслеживать. Все параметры описаны в справочнике API наград.

API нужен только тогда, когда отзыв инициирует другая система. Для разового случая панель быстрее, и в ней есть шаг подтверждения, который защищает от неверно набранного ID.

Что видят получатель и верификатор

После отзыва меняется следующее — и вот как быстро.

На публичной странице верификации. Страница по адресу https://badges.ninja/awards/<award-id> показывает документ как отозванный, а заголовок страницы для публикации в соцсетях получает префикс «[Revoked]», чтобы опубликованная ссылка не выглядела в карточке предпросмотра как действующий документ.

В assertion Open Badges v2.0. Размещённый JSON по адресу https://api.badges.ninja/certify-badge/award/<award-id> теперь содержит "revoked": true, а также "revocationReason", если вы указали причину. Отозванные assertion кэшируются всего около 30 секунд, тогда как действующие — пять минут, поэтому изменение быстро доходит до верификаторов.

В credential Open Badges 3.0. Отзыв также переключает бит документа в W3C Bitstring Status List — именно так его обнаруживают кошельки и верификаторы верифицируемых документов. Этот список кратко кэшируется, так что распространение займёт примерно минуту. Если вы сравниваете две версии, см. Open Badges v2 vs v3.

В собственной копии получателя. В скачанном файле ничего не меняется. Изображение значка на его ноутбуке выглядит так же. Меняется результат верификации: любой, кто перейдёт по ссылке или проверит документ программно, получит ответ «отозван». Если вы уведомили получателя, у него есть и письмо с объяснением причины.

В LinkedIn. Документ, добавленный в профиль LinkedIn, — это ссылка с метаданными, указывающая на вашу страницу верификации. LinkedIn не опрашивает статус отзыва за вас, поэтому запись может оставаться в профиле, но тот, кто перейдёт по ссылке, попадёт на страницу с отметкой об отзыве. Это ещё одна причина отправить уведомление и попросить получателя удалить запись.

Сообщите своим системам: вебхуки

Отзыв редко бывает концом истории внутри вашей организации. Слушатель может лишиться доступа к сообществу, в записи работодателя может понадобиться обновление, из CRM нужно убрать тег. Badges Ninja отправляет событие вебхука credential.revoked при отзыве документа, с URL награды и причиной:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Подпишитесь на него, и ваши последующие системы будут синхронизированы без того, чтобы кто-то помнил об их обновлении. Подробности настройки — в документации по вебхукам, а более широкую модель событий мы разбираем в статье настройка вебхуков для событий значков.

Простая политика отзыва, которую можно принять уже сегодня

Инструменты — лёгкая половина дела. Трудная половина — заранее решить, когда вы будете отзывать и кому это разрешено. Короткая письменная политика предотвратит споры потом. Рабочий шаблон:

  1. Основания для отзыва. Перечислите их: выдано по ошибке, получено недобросовестным путём, требование больше не выполняется (например, членство истекло) или программа свёрнута.
  2. Кто решает. Назовите роль, а не человека. Ограничьте право отзыва этой ролью.
  3. Уведомление. Укажите, что получателей уведомляют по электронной почте с указанием причины, если только документ не был доставлен.
  4. Апелляция. Дайте получателям способ оспорить решение и укажите, сколько времени вы будете отвечать. Если апелляция удовлетворена, выдайте новый документ, а не пытайтесь отменить отзыв — так история останется чистой.
  5. Учёт. Ведите внутреннюю запись о том, кто что и почему отозвал, отдельно от нейтральной публичной причины.

Опубликуйте политику на той же странице, где вы описываете документ, чтобы претенденты знали правила до регистрации.

Распространённые ошибки

  • Удаление вместо отзыва. Удаление необратимо, его нельзя отменить, и публичная страница исчезает. Используйте его для настоящих ошибок в документах, которых никто не видел.
  • Личные данные в причине. Она публична в assertion.
  • Ожидание, что сохранённые копии изменятся. Отзыв живёт на конечной точке верификации. Просите получателей удалить документ из профилей и портфолио.
  • Отзыв вместо истечения срока. Для документов с ограниченным сроком используйте дату окончания.
  • Расчёт на возврат. Отозванные документы по-прежнему учитываются в квоте вашего тарифа.
  • Забытые последующие системы. Настройте вебхук, чтобы доступы и записи следовали за статусом документа.

Часто задаваемые вопросы

Можно ли отменить отзыв? Через интерфейс — нет. Если вы отозвали по ошибке, выдайте получателю новый документ. Отозванный останется как часть аудиторского следа.

Нужно ли получателю что-то делать? Нет. Если вы выбрали уведомление, он получит письмо. Иначе изменение произойдёт молча на странице верификации.

Работает ли отзыв для документов, которые так и не были отправлены? Да, хотя для неотправленного документа с простой ошибкой вы можете предпочесть отредактировать его до отправки или удалить, если его никто не видел.

Есть ли ограничение на число отзываемых документов? Массовый отзыв выполняется как возобновляемая фоновая задача, поэтому большие пакеты обрабатываются одной операцией, а не по одному.

Увидят ли работодатели, что документ отозван? Любой, кто проверяет его по публичному URL или assertion, видит статус «отозван» и причину, если вы её указали.

Заключение

Отзыв Open Badge — небольшое действие с реальными последствиями для доверия. Делайте это из панели, когда речь об одном документе, используйте массовый отзыв для потока, а к API и вебхукам обращайтесь, когда решение принадлежит другой системе. Держите причины нейтральными, уведомляйте тех, кому нужно знать, и помните: отзыв меняет то, что видят верификаторы, а не файлы, которые уже у получателей.

Готовы выдать свой первый верифицируемый документ? Начните бесплатно на badges.ninja — визуальный дизайнер, публичная страница верификации, PDF-сертификат, вывод в формате Open Badge v2.0. Банковская карта не нужна.

Nacho Coll

Об авторе

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Назад в блог

Похожие статьи