Pular para o conteúdo principal

Como habilitar e usar os campos dinâmicos nas Informações Adicionais da sua credencial POK

Os campos dinâmicos permitem personalizar as Informações Adicionais de uma credencial do POK Proof of Knowledge para cada destinatário, em vez de usar o mesmo valor para todos. Você os habilita no editor de designs e os preenche no momento da emissão (manual, em massa ou via API). Este guia cobre as duas partes: configurar os campos dinâmicos em um design e emitir credenciais com eles pela API.

Parte 1: Configurar campos dinâmicos em um design​

1. Abrir o editor de designs​

  1. Acesse seu painel do POK pelo seletor de região, com seu usuário e senha.
  2. No menu lateral, selecione Visualização.
  3. Clique em Novo desenho para construir um template do zero.

A partir daqui, você pode editar tanto o design visual quanto as informações estruturais que compõem sua credencial.

2. Abrir a seção Informações Adicionais​

  1. Dentro do editor do template, selecione Informações Adicionais no menu lateral esquerdo. Nessa seção fica o conteúdo extra que acompanha cada credencial.
  2. Na seção Informações Gerais, clique em Adicionar para configurar os campos que descrevem a credencial a ser emitida.

3. Habilitar opções avançadas (opcional)​

Dentro do diálogo de Informações Gerais, você encontrará uma opção extra:

  • Ative o toggle "Melhorar a qualidade da minha credencial OpenBadge" para liberar mais campos opcionais. Esses campos acrescentam detalhe, transparência e contexto para o destinatário, e elevam a qualidade da sua credencial dentro do padrão OpenBadge.

Essa configuração não é obrigatória, mas é altamente recomendada se você quer entregar credenciais mais completas e alinhadas às boas práticas internacionais.

4. Ativar os campos dinâmicos​

  1. Dentro do acordeão Detalhes, marque o checkbox Habilitar campos dinâmicos.

  2. Ao habilitar essa opção, cada campo de informações gerais exibe um novo checkbox: Habilitar campo dinâmico.

Assim você define quais informações ficam fixas para todos os destinatários e quais são personalizadas caso a caso.

O que significa habilitar um campo dinâmico?​

  • Se você marcar a opção, o campo se torna dinâmico: seu valor é preenchido com informações personalizadas para cada destinatário no momento da emissão (manual, em massa ou via API).
  • Se você não marcar, o valor será o mesmo para todos os destinatários e virá diretamente do design.

Identificador do campo dinâmico​

Quando você ativa um campo dinâmico, aparece um nome entre colchetes, por exemplo: [nota final].

Guarde esse identificador: você vai usá-lo na emissão para atribuir um valor diferente a cada destinatário.

5. Salvar o design​

Depois de configurar as Informações Adicionais e definir os campos dinâmicos necessários:

  • Clique em Salvar Design para manter as alterações e habilitar o template para emissões.

Parte 2: Emitir credenciais com campos dinâmicos via API​

A emissão via API permite emitir credenciais de forma automatizada, integrando seus sistemas externos ao POK.

1. Obter sua API Key​

  1. No POK, abra o menu superior direito e acesse Integrations.

  2. Clique em Nova integração.

  3. Dê um nome descritivo (por exemplo, "Integração Sistema Interno").

  4. Selecione Integração por API Key.

  5. Copie sua API Key e guarde-a em um local seguro. Ela é exibida apenas uma vez.

  6. Marque o toggle "Já copiei a API Key..." e confirme para fechar o diálogo.

2. Obter o ID do template com campos dinâmicos​

Antes de emitir credenciais com campos dinâmicos, identifique o ID do template que os contém. Chame o endpoint de listagem de templates para obter a lista completa de templates disponíveis na sua organização. Para mais detalhes da requisição, consulte a documentação do endpoint de listagem de templates.

A resposta lista todos os templates com nome e ID. Encontre o template que você configurou com informações adicionais dinâmicas e copie o ID dele: você vai usá-lo nos próximos passos.

Exemplo de resposta

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

3. Consultar os detalhes do template​

Com o ID do template em mãos, consulte os detalhes dele para extrair os campos dinâmicos definidos. No parâmetro id, use o ID do template copiado no passo anterior. Para mais detalhes da requisição, consulte a documentação do endpoint para obter um template.

A resposta inclui a estrutura completa do template, onde você pode identificar:

  • O objeto customParameters, que contém os campos dinâmicos criados.
  • O ID e o label de cada um desses campos.

Você vai precisar desses IDs para montar o corpo da requisição do próximo passo, já que cada campo dinâmico deve ser enviado dentro do objeto customParameters.

Exemplo de resposta

{
    "id": "Qmx1ZQ==",
    "name": "Certified Frontend OB v2",
    "version": "2",
    "customParameters": [
        {
            "id": "achievement_description",
            "label": "achievement_description"
        },
        {
            "id": "37c53975-c57c-4f3b-a894-238ed118f7b7",
            "label": "final grade"
        }
    ]
}

4. Emitir uma credencial usando campos dinâmicos​

Para emitir a credencial com seus campos dinâmicos, use o endpoint de emissão de credenciais. Para mais detalhes da requisição, consulte a documentação do endpoint de emissão de credenciais.

Dentro do corpo da requisição:

  • No objeto customization template, inclua o objeto customParameters. Dentro dele, adicione cada um dos IDs identificados no passo 3, junto com o valor que você quer atribuir a cada campo dinâmico.
  • No campo id do objeto template, informe o ID do template obtido no passo 2.

Com esses passos, sua credencial é emitida com todos os valores dinâmicos definidos.

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": "pt-BR",
        "identification": "12345678",
        "email": "john.doe@pok.tech",
        "lastName": "Doe",
        "firstName": "John"
    },
    "customization": {
        "learningPath": {
            "stepId": "01J4MM0KYVR71D7VSCAN09TYW4",
            "id": "01J4MM0KYTAW0MJDJVGCG7XDBE"
        },
        "page": "48a975cd-be42-48b4-967a-84c1c09b730e",
        "template": {
            "customParameters": {
                "achievement_description": "Este certificado comprova que John Doe concluiu com êxito o programa de estudos...",
                "37c53975-c57c-4f3b-a894-238ed118f7b7": "+A"
            },
            "id": "Qmx1ZQ=="
        }
    }
}

Personalizações adicionais (opcional)​

Além dos campos dinâmicos, você pode adicionar outros elementos à emissão:

Essas opções enriquecem ainda mais o contexto que o aluno recebe.

Resposta bem-sucedida​

Quando a credencial é emitida corretamente, a resposta inclui:

  • O ID da credencial.
  • O state da emissão.
  • A viewUrl, onde a credencial poderá ser visualizada depois que o destinatário a aceitar.

Exemplo de resposta

{
    "id": "cf0a0360-85f7-494f-86bd-dba8c1b86893",
    "state": "waitingForApproval"
}

Com esses passos, os campos dinâmicos ficam totalmente configurados, permitindo criar experiências mais personalizadas e flexíveis para cada destinatário dentro do ecossistema POK.