API de concessões

Crie e gerencie concessões de distintivo (assertions) — distintivos emitidos para destinatários específicos.

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

Criar concessão

Concede um distintivo a um destinatário.

POST /awards

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	ID do distintivo a conceder
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
blockchain	string	Não	Blockchain para verificação on-chain. Apenas matchain é suportado. Disponível no plano Pro.

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 concessão na sua cota mensal (Free: 100/mês, Starter: 1.000/mês, Pro: 10.000/mês). A cota é medida contra as concessões 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.
• O parâmetro blockchain só está disponível no plano Pro e aceita apenas matchain.
• A ancoragem em blockchain ainda não está ativa. Passar blockchain: "matchain" é aceito e registrado como uma solicitação, mas nenhuma prova on-chain é gravada ainda — as concessões não carregam registro on-chain verificável no momento.

---

Listar concessões

Recupera concessões 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 concessões

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 concessão

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

POST /awards/{awardId}/send

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	ID da concessão (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 concessão

Compartilha uma concessão 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 concessão (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 concessão

Revoga uma concessão 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 concessão é 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 concessão (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 concessão 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 concessão já revogada é idempotente — retorna a mesma resposta sem reenviar uma notificação.

---

Excluir concessão

Exclui permanentemente uma concessão que você emitiu. Ao contrário da revogação, isso remove o registro por completo e a página pública da concessão passa a retornar 404. Use isto para erros genuínos (ex.: concedida à 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 concessão (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 concessão.

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 concessão

Registra um evento de engajamento. Usado pela página pública de concessão 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 concessão

Recupera contadores acumulados de engajamento de uma concessão.

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