API de atribuições

Crie e faça a gestão de atribuições de distintivos (assertions) — distintivos emitidos a destinatários específicos.

Todos os endpoints requerem autenticação através do cabeçalho X-Api-Key. Consulte Autenticação.

Criar atribuição

Emita um distintivo a um destinatário.

POST /awards

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	ID do distintivo a atribuir
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 (por exemplo, 2025-01-15)
expires	string	Não	Data de expiração no formato ISO 8601
blockchain	string	Não	Blockchain para verificação em cadeia. Só 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"
}

Notas

• Conta como uma atribuição contra a sua quota mensal (Free: 100/mês, Starter: 1000/mês, Pro: 10 000/mês). A quota é medida em relação às atribuições criadas desde as 00:00 UTC do dia 1 do mês de calendário actual — é reposta na fronteira do mês de calendário UTC, e não no aniversário da sua facturação.
• O parâmetro blockchain está disponível apenas no plano Pro e só aceita matchain.
• A ancoragem em blockchain ainda não está activa. Passar blockchain: "matchain" é aceite e registado como um pedido, mas ainda não é escrita qualquer prova em cadeia — as atribuições não têm, de momento, qualquer registo verificável em cadeia.

---

Listar atribuições

Obtenha atribuições com filtragem e paginação opcionais.

GET /awards

Parâmetros de consulta

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

Objecto de filtro

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

Campo	Tipo	Descrição
badgeId	string	Filtra por ID do distintivo.
search	string	Sub-cadeia a procurar em nomes ou e-mails dos destinatários (ver searchField).
searchField	string	name (predefinição) ou email — coluna onde procurar.

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

Exemplo — listar todas as atribuiçõ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, existem mais resultados. Passe-o como parâmetro de consulta no próximo pedido para obter a página seguinte.

---

Enviar e-mail de atribuição

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

POST /awards/{awardId}/send

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	ID da atribuição (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 cadeia de confirmação simples:

"email sent"

---

Partilhar atribuição

Partilhe uma atribuiçã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 atribuição (parâmetro de caminho e corpo)
recipients	string	Sim	Lista de endereços 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

Devolve uma cadeia de confirmação simples:

"email sent"

---

Revogar atribuição

Revogue uma atribuição que emitiu. A assertion Open Badges v2.0 alojada é marcada como revoked: true (com um motivo opcional) para que qualquer verificador veja que o distintivo já não é válido. O registo da atribuição é mantido para fins de auditoria e não há reembolso de crédito.

POST /awards/{awardId}/revoke

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	ID da atribuição (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 sua atribuição foi revogada. 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 atribuição já revogada é idempotente — devolve a mesma resposta sem reenviar uma notificação.

---

Eliminar atribuição

Elimine definitivamente uma atribuição que emitiu. Ao contrário da revogação, isto remove o registo por completo e a página pública da atribuição devolve 404. Utilize esta operação para erros genuínos (por exemplo, atribuída à pessoa errada); prefira a revogação para credenciais reais, para que a assertion continue verificável como revogada. Não há reembolso de crédito.

DELETE /awards/{awardId}

Parâmetros

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

---

Transferir certificado em PDF

Gera um certificado A4 em PDF pronto a imprimir para uma atribuição.

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

Não requer 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 de atribuição

Regista um evento de envolvimento. Utilizado pela página pública de atribuição para preencher as estatísticas de envolvimento. Não requer autenticação.

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

Parâmetros

Este endpoint lê o corpo directamente (sem o invólucro 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 event 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 de atribuição

Obtém contadores cumulativos de envolvimento para uma atribuição.

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

Não requer autenticação.

Resposta

Os contadores são devolvidos indexados pelo tipo de evento em bruto. totals contém a contagem total por evento; networks detalha a repartição por rede para os eventos que transportam um network (actualmente share). Os eventos sem actividade registada estão simplesmente ausentes.

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