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

{
  "statusCode": 200,
  "info": {
    "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 é redefinida a cada ciclo de faturamento.
• O parâmetro blockchain só está disponível no plano Pro.

---

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

{
  "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, 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

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

---

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

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

---

Baixar certificado em PDF

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

GET /awards/{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/awards/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 (visualização, compartilhamento, download, adição ao LinkedIn). Usado pela página pública de concessão para popular as estatísticas. Sem necessidade de autenticação.

POST /awards/{awardGuid}/event

Parâmetros

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

Recupera contadores acumulados de engajamento de uma concessão.

GET /awards/{awardGuid}/stats

Sem necessidade de autenticação.

Resposta

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