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

{
  "statusCode": 200,
  "info": {
    "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 é reposta em cada período de facturação.
• O parâmetro blockchain está disponível apenas no plano Pro.

---

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

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "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

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

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

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

Transferir certificado em PDF

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

GET /awards/{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/awards/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 (visualização, partilha, transferência, adição ao LinkedIn). Utilizado pela página pública de atribuição para preencher as estatísticas de envolvimento. Não requer autenticação.

POST /awards/{awardGuid}/event

Parâmetros

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

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

Exemplo

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

---

Obter estatísticas de atribuição

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

GET /awards/{awardGuid}/stats

Não requer autenticação.

Resposta

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}