API de Credenciais

Cria e gere credenciais (assertions) — emblemas emitidos para destinatários específicos.

Todos os endpoints exigem autenticação através do cabeçalho X-Api-Key. Vê Autenticação.

Criar credencial

Emite um emblema para um destinatário.

Precisas de emitir para centenas ou milhares de destinatários de uma só vez, em vez de uma chamada à API por pessoa? Usa a funcionalidade de interface Credenciais em massa, que aceita o carregamento de um CSV.

POST /awards

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	O ID do emblema a emitir
recipient	object	Sim	Dados do destinatário (ver abaixo)
recipient.name	string	Sim	Nome completo do destinatário (mínimo de 5 caracteres)
recipient.email	string	Sim	Endereço de e-mail do destinatário
issuedOn	string	Sim	Data de emissão no formato ISO 8601 (p. ex., 2025-01-15)
expires	string	Não	Data de validade no formato ISO 8601

Exemplo

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Resposta

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Notas

• Conta como uma credencial no teu conjunto anual de credenciais (Free: 1200/ano, Starter: 12 000/ano, Pro: 120 000/ano). O conjunto é uma quota anual flexível — usa-a quando quiseres ao longo do ano, incluindo em picos — e é renovada no aniversário do registo da tua conta. A faturação continua mensal; apenas a quota de credenciais é anual. Vê Planos e faturação para mais detalhes.

---

Listar credenciais

Obtém credenciais com filtragem e paginação opcionais.

GET /awards

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
filter	JSON string	Não	Objeto de filtro (ver abaixo)
lastEvaluatedKey	string	Não	Token de paginação de uma resposta anterior

Objeto de filtro

O parâmetro filter aceita uma string JSON com estes campos:

Campo	Tipo	Descrição
badgeId	string	Filtra por ID do emblema.
search	string	Excerto a procurar nos nomes ou e-mails dos destinatários (ver searchField).
searchField	string	name (predefinição) ou email — qual a coluna a pesquisar.

A paginação através de lastEvaluatedKey funciona com ou sem filtros. O tamanho da página é 50.

Exemplo — listar todas as credenciais

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

Exemplo — filtrar por emblema

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Se lastEvaluatedKey estiver presente na resposta, existem mais resultados. Passa-o como parâmetro de consulta no pedido seguinte para obter a página seguinte.

---

Enviar e-mail da credencial

Envia ao destinatário uma notificação por e-mail sobre a sua credencial.

POST /awards/{awardId}/send

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho e corpo)
email	string	Sim	Endereço de e-mail do destinatário

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Resposta

Devolve uma string de confirmação simples:

"email sent"

---

Partilhar credencial

Partilha uma credencial por e-mail com vários destinatários.

POST /awards/{awardId}/share

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho e corpo)
recipients	string	Sim	Lista de endereços de e-mail separados por vírgulas
subject	string	Sim	Linha de assunto do e-mail
message	string	Sim	Corpo da mensagem do e-mail

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Resposta

Devolve uma string de confirmação simples:

"email sent"

---

Revogar credencial

Revoga uma credencial que emitiste. A assertion alojada do Open Badges v2.0 é marcada com revoked: true (com um motivo opcional), para que qualquer verificador veja que o emblema deixou de ser válido. O registo da credencial é mantido para efeitos de auditoria, e não é reembolsado qualquer crédito.

A revogação propaga-se também ao Verifiable Credential do Open Badges 3.0 da credencial: o bit da credencial é alterado na W3C Bitstring Status List referenciada pelo credentialStatus do VC, pelo que as carteiras de VC também a detetam. Vê Revogação (Bitstring Status List).

POST /awards/{awardId}/revoke

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho)
reason	string	Não	Motivo da revogação. Truncado a 500 caracteres.
notify	boolean	Não	Quando true, envia um e-mail ao destinatário a informar que a credencial foi revogada. A predefinição é false.

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Resposta

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Revogar uma credencial já revogada é idempotente — devolve a mesma resposta sem reenviar a notificação.

Revogar em massa

Para revogar muitas credenciais de uma só vez, usa o endpoint durável de envio em massa com action: "revoke" em vez de chamares este endpoint para cada credencial:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Devolve { "jobId", "total" }; a tarefa revoga cada ID no servidor (ignorando os já revogados) e pode ser retomada. Os IDs já revogados e os inexistentes são comunicados como ignorados.

---

Eliminar credencial

Elimina definitivamente uma credencial que emitiste. Ao contrário da revogação, isto remove o registo por completo e a página pública da credencial passa a devolver 404. Usa-o para erros genuínos (por exemplo, emitida à pessoa errada); para credenciais reais, prefere revogar, para que a assertion continue verificável como revogada. Não é reembolsado qualquer crédito.

DELETE /awards/{awardId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho)

Exemplo

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Transferir certificado em PDF

Gera um certificado em PDF A4 pronto a imprimir para uma credencial.

GET /certify-badge/award/{awardGuid}/pdf

Não exige autenticação — este endpoint é público para que os destinatários possam transferir o seu próprio certificado.

Exemplo

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

A resposta é o PDF binário com o cabeçalho Content-Type: application/pdf.

---

Registar evento da credencial

Regista um evento de interação. Usado pela página pública da credencial para alimentar as estatísticas de interação. Não exige autenticação.

POST /certify-badge/award/{awardGuid}/event

Parâmetros

Este endpoint lê o corpo diretamente (sem o wrapper parameters).

Parâmetro	Tipo	Obrigatório	Descrição
event	string	Sim	Um de view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Não	Quando event=share, a rede social: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Supressão de duplicados por IP: o mesmo evento proveniente do mesmo IP é contabilizado uma vez a cada 24 horas.

Exemplo

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Resposta

{
  "ok": true
}

---

Obter estatísticas da credencial

Obtém os contadores cumulativos de interação de uma credencial.

GET /certify-badge/award/{awardGuid}/stats

Não exige autenticação.

Resposta

Os contadores são devolvidos indexados pelo tipo bruto do evento. totals contém a contagem total por evento; networks detalha a divisão por rede dos eventos que transportam um network (atualmente share). Os eventos sem atividade registada simplesmente não aparecem.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}