Pular para o conteúdo principal

Como emitir uma credencial via API e filtrar por tags

Para emitir uma credencial com a API da POK Proof of Knowledge, você cria um template, gera uma chave de API e chama o endpoint de emissão com o ID do template. Se você adicionar tags à requisição, poderá depois filtrar as credenciais emitidas com o parâmetro de consulta tags. Este guia mostra o fluxo completo.

Parte 1: Configuração inicial​

Criar um template​

Você precisa de um template antes de emitir qualquer credencial.

  1. Acesse seu painel do POK pelo seletor de região.
  2. Vá até a seção Visualização.
  3. Crie um novo template.

Para instruções detalhadas, consulte como criar o design de um certificado.

Criar uma chave de API​

  1. No POK, abra o menu superior direito e acesse Integrações.
  2. Clique em Nova integração.
  3. Atribua um nome descritivo (por exemplo, "Integração do Sistema Interno").
  4. Selecione Integração de Chave de API.
  5. Copie sua chave de API e guarde-a em um local seguro. Ela é exibida apenas uma vez.
  6. Marque o botão "Já copiei a Chave de API…" e confirme para fechar o diálogo.

Parte 2: Emitir uma credencial via API​

Passo 1: Obter o ID do template​

Primeiro, identifique o ID do template que você criou. Chame o endpoint de listagem de templates para obter todos os templates disponíveis na sua organização. Para ver os detalhes completos da requisição, consulte a referência da API.

A resposta inclui cada template com seu nome e ID. Localize o template que você configurou anteriormente e copie o ID. Você vai usá-lo no próximo passo.

Exemplo de resposta:

{
    "pagination": {
        "next": "string"
    },
    "data": [
        {
            "id": "Qmx1ZQ==",
            "name": "Certified Frontend OB v2"
        }
    ]
}

Dados opcionais​

Passo 2: Emitir a credencial​

Chame o endpoint de emissão de credenciais. Para ver os detalhes completos do corpo da requisição, consulte a referência da API.

Dois campos são essenciais no corpo da requisição:

  • id dentro do objeto template: informe o ID do template obtido no Passo 1.
  • tags dentro do objeto credential: tags são valores arbitrários associados à credencial que permitem filtrar suas emissões mais tarde.

Exemplo de tags:

"tags": ["StudentId:65989", "#SALE", "Q1"]

Depois de preencher os valores do corpo da requisição, você poderá emitir credenciais vinculadas a tags.

Exemplo de corpo:

{
    "credential": {
        "tags": ["StudentId:65989", "#SALE", "Q1"],
        "skipAcceptance": false,
        "emissionType": "pok",
        "dateFormat": "dd/MM/yyyy",
        "emissionDate": "2022-10-09T00:00:00.000Z",
        "title": "Frontend developer",
        "emitter": "The World University"
    },
    "receiver": {
        "languageTag": "es-AR",
        "identification": "12345678",
        "email": "john.doe@pok.tech",
        "lastName": "Doe",
        "firstName": "John"
    },
    "customization": {
        "learningPath": {
            "stepId": "",
            "id": ""
        },
        "page": "",
        "template": {
            "customParameters": {},
            "id": "Qmx1ZQ=="
        }
    }
}

Parte 3: Obter e filtrar credenciais emitidas​

Listar credenciais emitidas​

Após a emissão, obtenha a lista completa de credenciais emitidas com o endpoint de listagem de credenciais. Para ver os detalhes completos da requisição, consulte a referência da API.

Filtrar por tags​

Para filtrar os resultados, use o parâmetro de consulta tags. O valor deve corresponder exatamente à tag usada no momento da emissão.

Exemplo de requisição:

GET /credential?tags=Q1

A API retorna apenas as credenciais que contêm essa tag.

O que você pode fazer agora​

Com esses passos você pode:

  • Emitir credenciais digitais via API.
  • Associá-las a identificadores personalizados (tags).
  • Filtrar suas emissões com facilidade.
  • Gerenciar grandes volumes de credenciais com segmentação avançada.