API de Atribuições

Atribua até 100 alunos a um pacote por solicitação. A API cria uma conta se o e-mail for novo.

Antes de usar esta API, ative Atribuir usuários para o cliente em Acesso à API e solicite um token com scope=assignments.write. Os clientes são somente leitura por padrão. Consulte Autenticação para obter o token.

Atribuir alunos

POST /api/v1/assignments

Escopo necessário: assignments.write.

curl --request POST \
  --url "https://courses.e-learningcourses.com/api/v1/assignments" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"packageId":"46647b28-2785-4435-9fa9-715e8c461902","groupId":"d812aa9e-160b-4a19-b7ef-8be3112f4e6a","users":[{"firstName":"Alex","lastName":"Example","email":"alex@example.com","doNotEmail":false}]}'

Corpo da solicitação

Campo	Tipo	Obrigatório	Descrição
packageId	UUID	Sim	Pacote a atribuir. Consulte a API de Pacotes.
groupId	UUID ou null	Não	Para um cliente de organização, grupo da atribuição. Omita para atribuir sem grupo. Um cliente de grupo sempre usa o próprio grupo; se informado, o ID deve corresponder a ele.
users	array	Sim	Entre 1 e 100 alunos.
users[].firstName	string	Sim	Nome do aluno.
users[].lastName	string	Sim	Sobrenome do aluno.
users[].email	string	Sim	E-mail; contas existentes são identificadas por ele.
users[].doNotEmail	boolean	Não	false por padrão. Use true para não enviar e-mails de atribuição ou convite a esse aluno.

O pacote deve pertencer à organização do cliente. O grupo deve estar vinculado a esse pacote. As atribuições exigem uma assinatura válida e respeitam o limite de alunos do grupo, quando aplicável.

Resposta

Os alunos são processados separadamente. Um lote válido retorna 200 OK mesmo que alguns alunos falhem:

{
  "packageId": "46647b28-2785-4435-9fa9-715e8c461902",
  "groupId": "d812aa9e-160b-4a19-b7ef-8be3112f4e6a",
  "succeeded": 1,
  "failed": 1,
  "results": [
    { "index": 0, "email": "alex@example.com", "success": true, "userId": "learner-id" },
    { "index": 1, "email": "invalid-address", "success": false, "error": "A valid email address is required." }
  ]
}

index é a posição do aluno na solicitação, começando em zero. Resultados bem-sucedidos incluem userId; falhas incluem error. Repita somente as falhas. Repetir uma atribuição bem-sucedida pode iniciar uma nova tentativa de treinamento.

Atribuições existentes em outro grupo

Atribuir um aluno existente pode mover a atribuição desse pacote de outro grupo. Ative a permissão de atribuição apenas para integrações confiáveis.

Erros e limites

Um lote inválido retorna 400. Um token ausente ou expirado retorna 401; um token sem permissão de atribuição ou uma assinatura inválida retorna 403. Um pacote ou grupo indisponível ou fora do escopo retorna 404. São permitidas 2 solicitações de atribuição por minuto e cliente; as demais retornam 429. Consulte Autenticação para saber quando tentar novamente.

OpenAPI

https://courses.e-learningcourses.com/api/v1/openapi.json