API de credenciais

Crie e gerencie credenciais (assertions) — distintivos emitidos para destinatários específicos.

Todos os endpoints exigem autenticação pelo cabeçalho X-Api-Key. Veja Autenticação.

Criar credencial

Emite um distintivo a um destinatário.

POST /awards

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	ID do distintivo a emitir
recipient	object	Sim	Detalhes do destinatário (veja abaixo)
recipient.name	string	Sim	Nome completo do destinatário (mínimo de 5 caracteres)
recipient.email	string	Sim	E-mail do destinatário
issuedOn	string	Sim	Data de emissão em formato ISO 8601 (ex.: 2025-01-15)
expires	string	Não	Data de expiração em 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"
}

Observações

• Conta como uma credencial na sua cota mensal (Free: 100/mês, Starter: 1.000/mês, Pro: 10.000/mês). A cota é medida contra as credenciais criadas desde as 00:00 UTC do dia 1º do mês corrente do calendário — ela é redefinida no limite do mês do calendário em UTC, não no aniversário do seu ciclo de faturamento.

---

Listar credenciais

Recupera credenciais com filtragem e paginação opcionais.

GET /awards

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
filter	JSON string	Não	Objeto de filtro (veja 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 de distintivo.
search	string	Subcadeia para buscar nos nomes ou e-mails dos destinatários (veja searchField).
searchField	string	Ou name (padrão) ou email — em qual coluna pesquisar.

A paginação via lastEvaluatedKey funciona com ou sem filtros. O tamanho de 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 distintivo

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://ipfs.ninja/ipfs/Qm..."
      },
      "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, há mais resultados. Passe-o como query parameter na próxima requisição para obter a próxima página.

---

Enviar e-mail de credencial

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

POST /awards/{awardId}/send

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	ID da credencial (parâmetro de caminho e corpo)
email	string	Sim	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

Retorna uma string de confirmação simples:

"email sent"

---

Compartilhar credencial

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

POST /awards/{awardId}/share

Parâmetros

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

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

Retorna uma string de confirmação simples:

"email sent"

---

Revogar credencial

Revoga uma credencial que você emitiu. A assertion Open Badges v2.0 hospedada é marcada como revoked: true (com um motivo opcional), de modo que qualquer verificador vê que o distintivo não é mais válido. O registro da credencial é mantido para fins de auditoria, e nenhum crédito é reembolsado.

POST /awards/{awardId}/revoke

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	ID da credencial (parâmetro de caminho)
reason	string	Não	Motivo da revogação. Truncado em 500 caracteres.
notify	boolean	Não	Quando true, envia um e-mail ao destinatário informando que sua credencial foi revogada. Padrã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 — retorna a mesma resposta sem reenviar uma notificação.

---

Excluir credencial

Exclui permanentemente uma credencial que você emitiu. Ao contrário da revogação, isso remove o registro por completo e a página pública da credencial passa a retornar 404. Use isto para erros genuínos (ex.: emitida à pessoa errada); prefira revogar para credenciais reais, para que a assertion permaneça verificável como revogada. Nenhum crédito é reembolsado.

DELETE /awards/{awardId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	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"
}

---

Baixar certificado em PDF

Gera um certificado em PDF A4 pronto para impressão para uma credencial.

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

Sem necessidade de autenticação — este endpoint é público para que destinatários possam baixar 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 cabeçalho Content-Type: application/pdf.

---

Registrar evento de credencial

Registra um evento de engajamento. Usado pela página pública de credencial para popular as estatísticas. Sem necessidade de autenticação.

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

Parâmetros

Este endpoint lê seu corpo diretamente (sem o invólucro parameters).

Parâmetro	Tipo	Obrigatório	Descrição
event	string	Sim	Um dos valores 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 duplicatas por IP: o mesmo event do mesmo IP é contado 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

Recupera contadores acumulados de engajamento de uma credencial.

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

Sem necessidade de autenticação.

Resposta

Os contadores são retornados indexados pelo tipo bruto de evento. totals contém a contagem total por evento; networks detalha a divisão por rede para eventos que carregam um network (atualmente share). Eventos sem atividade registrada são simplesmente omitidos.

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