Alterações na API na versão de agosto de 2026 do Adobe Learning Manager

API do administrador de grupos de usuários no Adobe Learning Manager

Esta versão adiciona três novos endpoints de API públicos com escopo de administrador para gerenciar grupos de usuários personalizados de forma programática. Você pode criar, renomear e excluir grupos de usuários personalizados sem usar o aplicativo Admin, permitindo automatizar o gerenciamento de grupos como parte de sua identidade ou fluxos de trabalho de provisionamento.

Esses endpoints funcionam apenas com grupos de usuários personalizados. Os grupos gerenciados pelo sistema, como o grupo Todos os usuários e os grupos de usuários gerados automaticamente, têm somente leitura: true na resposta da API e não pode ser modificado nem excluído por meio desses endpoints.

Para obter os requisitos de autenticação da API, consulte Autenticação da API do Adobe Learning Manager.

Pontos finais de API de grupos de usuários

Todos os três pontos de extremidade exigem um token de acesso de administrador com permissões de gravação (ROLE_ADMIN).

Cabeçalhos de solicitação comuns

Todos os três pontos de extremidade exigem os seguintes cabeçalhos.

Authorization: Bearer \<access-token\>
X-acap-user: \<user-id\>
X-acap-account: \<account-id\>
X-acap-caller-role: ROLE_ADMIN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Criar um grupo de usuários

POST /primeapi/v2/userGroups

Cria um novo grupo de usuários personalizado com uma lista inicial de membros. O grupo fica imediatamente disponível para uso no aplicativo do administrador.

Corpo da solicitação

{
  "name": "Marketing Team",
  "description": "Custom user group for marketing onboarding",
  "data": [
    { "type": "user", "id": "11282373" },
    { "type": "user", "id": "11282374" }
  ]
}

Parâmetros de solicitação

Observação: a matriz de dados é usada apenas na criação para definir a lista de membros inicial. Para adicionar ou remover membros após a criação, use os endpoints de associação ao grupo de usuários existente.

Resposta 201 Criada

{
  "links": {
    "self": "https://<host>/primeapi/v2/userGroups"
  },
  "data": {
    "id": "2769204",
    "type": "userGroup",
    "attributes": {
      "dateCreated": "2026-06-04T14:19:53.000Z",
      "description": "Custom user group for marketing onboarding",
      "name": "Marketing Team",
      "readOnly": false,
      "userCount": 2
    }
  }
}

POST de regras de validação

Atualizar um grupo de usuários

PUT /primeapi/v2/userGroups/{id}

Atualiza o nome e/ou a descrição de um grupo de usuários personalizado existente. Este ponto de extremidade não pode adicionar ou remover membros do grupo.

Qualquer um dos campos pode ser omitido; a omissão de um campo deixa seu valor atual inalterado. Passar nulo para descrição limpa-o. A transmissão de uma sequência em branco para o nome foi rejeitada.

Corpo da solicitação

{
  "name": "Updated Group Name",
  "description": "Updated description text"
}

Parâmetros de solicitação

Resposta 200 OK

{
  "data": {
    "type": "userGroup",
    "id": "2767870",
    "attributes": {
      "name": "Updated Group Name",
      "description": "Updated description text",
      "readOnly": false,
      "state": "Active",
      "userCount": 3
    }
  }
}

PUT de regras de validação

Excluir um grupo de usuários

DELETE /primeapi/v2/userGroups/{id}

Marca o grupo de usuários personalizado especificado como excluído. O registro do grupo não é removido permanentemente; seu estado é definido como EXCLUÍDO, o que o torna invisível no aplicativo do administrador e inelegível para uso em novas configurações. A ID do grupo não pode ser reutilizada.

Exemplo de solicitação

DELETE /primeapi/v2/userGroups/2767870
Authorization: Bearer <access-token>
X-acap-user: <user-id>
X-acap-account: <account-id>
X-acap-caller-role: ROLE_ADMIN

Resposta 204 Sem Conteúdo

O corpo da resposta está vazio.

Observação: DELETE não é idempotente. O envio de uma segunda solicitação de DELETE para o mesmo ID de grupo retorna um erro 400 com o código DELETED_USERGROUP — não 204. Tratar uma resposta 400 DELETED_USERGROUP como confirmação de que o grupo já foi excluído. Não há suporte para exclusão em massa; cada grupo requer uma solicitação DELETE separada.

DELETE de regras de validação

API de aprendizado externa no Adobe Learning Manager

Esta versão adiciona cinco novos endpoints de API com escopo de aluno para o recurso de aprendizado externo. Esses endpoints permitem que os alunos criem, recuperem e atualizem envios de aprendizado externos de forma programática, por exemplo, a partir de um aplicativo móvel, um sistema de RH integrado ou um portal de aprendizado personalizado.

O fluxo de trabalho de aprendizado externo por meio da API espelha o fluxo de trabalho no aplicativo do aluno: um aluno envia detalhes de treinamento e um documento de prova opcional, seu gerente direto recebe uma notificação para revisar o envio e, na aprovação, o registro aparece na transcrição do aluno.

Todos os cinco pontos de extremidade têm escopo do aluno. Um aluno só pode acessar seus próprios envios — a API retorna um erro se um aluno tentar acessar os dados de outro aluno.

Para obter os requisitos de autenticação da API, consulte Autenticação da API do Adobe Learning Manager.

Pontos de extremidade da API de aprendizado externos

Todos os pontos de extremidade exigem um token de acesso do aluno (ROLE_LEARNER).

Cabeçalhos de solicitação comuns

Authorization: Bearer <access-token>
X-acap-user: <user-id>
X-acap-account: <account-id>
X-acap-caller-role: ROLE_LEARNER
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json (POST and PUT only)

Ciclo de vida do status do envio

APROVADO e REJEITADO são estados terminais. Um envio rejeitado não pode ser reaberto; o aluno deve criar um novo envio.

Buscar configuração do formulário da conta

GET /primeapi/v2/externalLearningSettings

Retorna a configuração do formulário no nível da conta. Chame esse ponto de extremidade antes de renderizar um formulário de envio. A resposta define quais campos exibir, quais são obrigatórios, seus tipos de dados e quaisquer campos personalizados configurados pelo administrador.

Verifique o atributo de nível superior ativado antes de continuar, se falso, o recurso Aprendizado externo não está ativo para esta conta e os pontos de extremidade de envio retornarão erros.

Resposta 200 OK

{
  "data": {
    "id": "8627",
    "type": "externalLearningSettings",
    "attributes": {
      "enabled": true,
      "updatedAt": "2026-06-05T06:51:20.000Z",
      "coreFields": [
        { "id": "title", "type": "TEXT", "mandatory": true, "editable": false, "order": 0 },
        { "id": "description_notes", "type": "TEXT", "mandatory": false, "editable": true, "order": 1 },
        { "id": "date", "type": "TIMESTAMP", "mandatory": false, "editable": true, "order": 2 },
        { "id": "score", "type": "NUMBER", "mandatory": true, "editable": true, "order": 3 },
        { "id": "duration", "type": "TEXT", "mandatory": false, "editable": true, "order": 4 },
        { "id": "attachments", "type": "FILE_UPLOAD", "mandatory": true, "editable": true, "order": 5 }
      ],
      "customFields": [
        {
          "id": "960369b2-...",
          "type": "NUMBER",
          "mandatory": true,
          "order": 0,
          "label": { "en_US": "Employee Code" }
        },
        {
          "id": "3c6cc6d9-...",
          "type": "DROPDOWN",
          "mandatory": true,
          "order": 1,
          "label": { "en_US": "Department" },
          "options": [
            { "option_id": "opt_1", "label": { "en_US": "IT" } },
            { "option_id": "opt_2", "label": { "en_US": "HR" } },
            { "option_id": "opt_3", "label": { "en_US": "FIN" } }
          ]
        }
      ]
    }
  }
}

Referência de campo principal

Os campos personalizados são definidos pelo administrador e retornados em customFields[]. Suas IDs, tipos, sinalizadores obrigatórios, etiquetas e opções suspensas variam de acordo com a configuração da conta.

Listar envios

GET /primeapi/v2/externalLearnings

Retorna uma lista paginada dos próprios envios do aluno autenticado, classificada por modifiedAt decrescente (modificado mais recentemente primeiro).

Parâmetros de consulta

Resposta 200 OK

{
  "links": {
    "next": "/primeapi/v2/externalLearnings?page[offset]=10&page[limit]=10"
  },
  "data": [
    { "id": "1001", "type": "externalLearning", "attributes": { "status": "PENDING", ... } },
    { "id": "1002", "type": "externalLearning", "attributes": { "status": "APPROVED", ... } }
  ]
}

Buscar um envio

GET /primeapi/v2/externalLearnings/{id}

Retorna o registro completo de um único envio pertencente ao aluno autenticado.

**Resposta 200 OK

{
  "data": {
    "id": "1001",
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "https://<cdn-url>/cert.pdf",
      "title": "Java Fundamentals Certification",
      "status": "PENDING",
      "creationSource": "LEARNER",
      "createdAt": "2026-04-14T08:30:00.000Z",
      "modifiedAt": "2026-04-16T11:45:00.000Z",
      "fields": [ "...resolved against live settings..." ]
    },
    "relationships": {
      "reviewerUser": { "data": null }
    }
  }
}

Criar um envio

POST /primeapi/v2/externalLearnings

Cria um novo envio de aprendizado externo no estado PENDENTE. Todos os campos obrigatórios definidos nas configurações da conta devem ser incluídos. Após um POST bem-sucedido, o gerente do aluno recebe uma notificação na plataforma para revisar o envio.

Carregamento de arquivo

O campo de anexos é tratado separadamente dos outros campos. Não o inclua dentro de campos[]. Em vez disso:

​1. Obtenha um URL de upload S3 pré-assinado no ponto de extremidade de upload de arquivos do ALM.

​2. Faça upload do arquivo nesse URL.

​3. Transmita o URL resultante como o atributo submissionUrl de nível superior em sua solicitação POST.

Corpo da solicitação

{
  "data": {
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "<pre-signed-upload-url>",
      "fields": [
        { "id": "title", "type": "TEXT", "value": "Java Fundamentals Certification" },
        { "id": "description_notes", "type": "TEXT", "value": "Completed via online course platform." },
        { "id": "date", "type": "TIMESTAMP", "value": { "start_date": "2026-05-01T00:00:00.000Z", "end_date": "2026-05-15T00:00:00.000Z" } },
        { "id": "score", "type": "NUMBER", "value": { "achieved_score": 88, "max_score": 100 } },
        { "id": "duration", "type": "TEXT", "value": "40 hours" },
        { "id": "960369b2-...", "type": "NUMBER", "value": "1225" },
        { "id": "3c6cc6d9-...", "type": "DROPDOWN", "value": "opt_3" }
      ]
    }
  }
}

Formas de valor do campo

POST de regras de validação

Atualizar um envio

PUT /primeapi/v2/externalLearnings/{id}

Atualiza um envio PENDENTE existente. Somente envios PENDING podem ser atualizados. A tentativa de PUT de um envio APPROVED ou REJECTED retorna um erro 409.

Este ponto de extremidade usa semântica de substituição completa. Forneça a matriz completa fields[] em cada solicitação PUT, não apenas os campos que você está alterando. Os campos omitidos da matriz são apagados.

Campos que o aluno pode atualizar

Corpo da solicitação

{
  "data": {
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "<cdn-url>/cert-v2.pdf",
      "fields": [
        { "id": "title", "type": "TEXT", "value": "Java Fundamentals — Updated" },
        { "id": "description_notes", "type": "TEXT", "value": "Updated notes." },
        { "id": "date", "type": "TIMESTAMP", "value": { "start_date": null, "end_date": null } },
        { "id": "score", "type": "NUMBER", "value": { "achieved_score": 92, "max_score": 100 } },
        { "id": "duration", "type": "TEXT", "value": "42 hours" },
        { "id": "960369b2-...", "type": "NUMBER", "value": "1227" },
        { "id": "3c6cc6d9-...", "type": "DROPDOWN", "value": "opt_2" }
      ]
    }
  }
}

API para ID de certificação relevante para o aluno e ID de certificação raiz no LT

Quando uma certificação recorrente é renovada, o Adobe Learning Manager cria uma nova versão da certificação e inscreve automaticamente os alunos ativos nela. Se a integração consultar dados de certificação diretamente em vez de depender da experiência do aluno do Adobe Learning Manager, você pode usar essa API para determinar exatamente qual versão de uma certificação recorrente é relevante para um aluno específico a qualquer momento.

Finalidade da API

As certificações recorrentes geram uma nova ID de certificação toda vez que são renovadas. Na experiência nativa do aluno do Adobe Learning Manager, somente a versão relevante para cada aluno é exibida. As versões mais antigas são ocultadas automaticamente assim que um aluno passa para uma mais recente.

Se a sua integração recuperar dados de certificação independentemente, por exemplo, para exibir informações de certificação em um portal externo, ela pode não aplicar automaticamente essa filtragem. Sem ela, um aluno podia ver cada versão histórica de uma certificação recorrente, incluindo aquelas que não eram mais relevantes para ele, sem nenhuma indicação sobre a qual agir.

Essa API resolveu essa lacuna. Dado o ID de certificação raiz, ele retorna a versão de certificação específica que se aplica a um determinado aluno, contabilizando seu histórico de inscrição e quaisquer recorrências.

Entender a recorrência da certificação

Quando uma certificação é configurada para recorrência, cada renovação cria uma nova versão de certificação com sua própria ID exclusiva. Todas as versões retornam a uma única ID de certificação raiz, a ID da certificação original quando ela foi criada pela primeira vez.

Por exemplo, uma certificação que se repete todos os meses pode produzir uma sequência de versões ao longo do tempo, onde cada nova versão é gerada automaticamente quando o intervalo de recorrência é atingido. Os alunos que estão inscritos ativamente quando ocorre uma recorrência são inscritos automaticamente na nova versão.

Como cada versão tem uma ID distinta, a versão relevante de um aluno depende de sua linha do tempo de inscrição individual:

Determinar a versão de certificação relevante

Use a API da versão de certificação para identificar qual versão de uma certificação recorrente é relevante para um aluno específico.

Forneça a ID de certificação raiz como entrada. A API avalia o histórico de inscrição do aluno e retorna a versão apropriada com base nas seguintes regras:

Isso significa que dois alunos que consultam a mesma ID de certificação raiz ao mesmo tempo podem receber resultados diferentes, dependendo do histórico de inscrição individual de cada aluno.

Exemplo

Considere uma certificação que se repete mensalmente, onde quatro versões foram criadas ao longo do tempo devido a recorrências sucessivas:

Isso permite que a integração sempre direcione um aluno para a versão de certificação que é relevante para ele, em vez de mostrar cada versão histórica ou adivinhar qual se aplica.

Referência da API

Obter a certificação aplicável para uma certificação raiz

GET /primeapi/v2/learningObjects/{loId}/applicableCertification

Resolve a versão de certificação que se aplica ao aluno atual, dada a ID de uma certificação raiz. Para alunos inscritos, isso retorna a versão na qual eles estão inscritos no momento. Para alunos não inscritos, isso retorna a versão ativa mais recente.

Observação: esta API retorna informações de versão para um único aluno por vez. Ela não retorna uma lista de todas as versões de uma certificação.

Parâmetros de caminho

Parâmetros de consulta

Exemplo de solicitação

GET /primeapi/v2/learningObjects/certification%3A167658/applicableCertification?include=subLOs
Accept: application/vnd.api+json
Authorization: oauth <access-token>

curl -X GET --header 'Accept: application/vnd.api+json' \
--header 'Authorization: oauth <access-token>' \
'https://<host>/primeapi/v2/learningObjects/certification%3A167658/applicableCertification?include=subLOs'

Observação: o valor loId deve ser codificado por URL. Dois-pontos em uma ID de certificação, como certification:167658, está codificado como %3A.

Exemplo de resposta 200 OK

A resposta usa a mesma estrutura de uma resposta de Objeto de aprendizado padrão, retornando a certificação resolvida.

Importante: o campo de ID na resposta é a ID da certificação resolvida, a versão específica aplicável a este aluno. Normalmente, ela será diferente da ID de certificação raiz transmitida como loId, uma vez que o objetivo dessa API é traduzir uma ID raiz para a versão atual correta.

{
  "data": {
    "id": "string",
    "type": "string",
    "attributes": {
      "authorNames": [
        "string"
      ],
      "bannerUrl": "string",
      "catalogs": [
        ...
      ]
    }
  }
}

Códigos de resposta

Exemplo de resposta de erro

{
  "meta": {
    "error": "string",
    "detail": "string"
  }
}

Observação: esta API resolve a versão para um aluno por chamada. Ele não retorna uma lista de todas as versões existentes para uma certificação raiz.

Pontos importantes

Observação: um equivalente no escopo do administrador desta API não está disponível no momento e está sendo avaliado para uma versão futura.

Usar esta API na integração

Um caso de uso comum é uma página ou portal externo que lista certificações que um aluno pode acessar. Em vez de vincular diretamente a uma ID de certificação específica, que pode ficar desatualizada após uma recorrência. Vincule usando a ID de certificação raiz e resolva a versão correta no momento em que o aluno a selecionar.

1.Armazene ou referencie certificações em sua integração usando a ID de certificação raiz, a ID da certificação como ela foi criada pela primeira vez, antes de qualquer recorrência.

​2. Quando um aluno seleciona uma certificação para exibir ou agir, chame GET /primeapi/v2/learningObjects/{loId}/appliedCertification, transmitindo a ID de certificação raiz como loId.

​3. Use a versão de certificação retornada na resposta para direcionar o aluno para o destino correto, seja uma ação de inscrição ou uma exibição de seu progresso atual.

Isso garante que os alunos sempre tenham acesso à versão da certificação que corresponde à sua inscrição real e ao progresso, mesmo que a certificação ocorra novamente com o tempo e gere novas versões.

Relatório: ID de treinamento raiz na transcrição do aluno

A coluna ID de treinamento raiz está disponível por padrão na transcrição do aluno para todas as contas.

Observação: para contas muito grandes com um alto volume de certificações, os valores de ID de treinamento raiz na transcrição do aluno são resolvidos em lotes. Isso não altera a precisão dos dados, mas transcrições muito grandes podem demorar mais para serem geradas.

Essa coluna permite agrupar e relatar o histórico completo de um aluno em todas as versões de uma certificação recorrente, em vez de tratar cada recorrência como um registro independente e não relacionado. Cada recorrência ainda aparece como sua própria linha na transcrição do aluno. A coluna ID do treinamento raiz simplesmente identifica quais linhas pertencem à mesma certificação subjacente.

Observação: use a coluna de ID de treinamento raiz quando precisar rastrear o histórico completo de participação de um aluno em uma certificação recorrente.