Casos de Uso

Nesta seção, estão listados alguns casos de uso e exemplos de erros comuns encontrados ao lidar com nossa API.

Atualizando a Série de um Aluno

Um dos processos comuns realizados pelas escolas anualmente é a atualização da série dos alunos. Na Árvore, como a série é um atributo de uma estrutura, o que define a série de um aluno acaba sendo sua alocação em uma turma. Assim, quando um aluno passa para o próximo ano escolar, é preciso movimentá-lo para uma turma com a série correta. Esse processo é referenciado como enturmamento.

Para manter o histórico de leitura e gamificação de um aluno, basta atualizar sua alocação através do campo entity_reference_id. A nova referência deverá ser de uma entidade da estrutura que possua a série correta.

Apesar de não ser necessário, alguns clientes optam por referenciar o ano escolar no nome da escola, como no seguinte exemplo:

# 2023:
Turma 1A - 2023
Turma 2A - 2023

# 2024:
Turma 2A - 2024
Turma 3A - 2024

Dessa forma, durante o processo anual de enturmamento, são realizadas as criações das respectivas turmas daquele ano (no exemplo, 2024), e então todos os alunos de uma turma são movimentados para as novas turmas em 2024, seguindo os seguintes passos:

Criando as respectivas turmas do ano em questão (ex: 2024).
Atualizando os alunos de uma série para a turma do próximo ano escolar (ex: 1A 2023 vai para 2A 2024).
Mantendo os alunos na mesma série, porém movimentando-os para uma turma do próximo ano (ex: 1A 2023 vai para 1A 2024).
Listando os alunos que sobraram nas turmas de 2023.
Excluindo os alunos que sobraram nas turmas 2023.
Finalmente, excluindo as turmas de 2023.

Erros Comuns

Gerenciando Usuários de Múltiplos Clientes

O vínculo de um usuário externo com um usuário Árvore é realizado através do campo reference_id. Esse ID é um identificador externo único que deve ser fornecido pelo parceiro ao cadastrar um usuário. Caso um usuário com o mesmo reference_id seja criado mais de uma vez, a API retornará um erro, indicando que o usuário já existe.

O reference_id deve ser único dentro do escopo de cada parceiro. No entanto, fora do escopo de um cliente, o reference_id poderá se repetir.

Por isso, se você for um prestador de serviços que atenda a mais de um cliente, verifique com cautela com qual chave de acesso você está utilizando para autenticar no momento de realizar diferentes operações, a fim de evitar que a estrutura de diferentes clientes se misture.

Atualizando um Usuário com uma Entidade Inválida

Ao realizar a atualização cadastral de um professor ou leitor, é possível também realizar a atualização da entidade a qual esse usuário está associado. Para isso, será preciso que um novo ID de entidade seja fornecido para ele.

Para que a atualização de um usuário tenha sucesso, é necessário que o ID da entidade fornecido seja válido. Ou seja: essa entidade precisa existir dentro do escopo do cliente autenticado. Caso o ID de entidade fornecido não exista, a API retornará um HTTP 422, indicando que o recurso não pode ser processado corretamente.

Tentativa de Atualizar um Usuário Não Existente

Como já descrito nas seções anteriores, o reference_id é um identificador único para um usuário dentro do escopo de um cliente. Caso você busque um usuário que não exista dentro do escopo de um cliente, a API retornará um erro HTTP 404, indicando que o usuário não foi encontrado.

Caso um usuário não seja encontrado através da API, é possível investigar a estrutura atual da conta através dos recursos Entidades, tais como:

Listar os descendentes de uma entidade
Listar os leitores de uma entidade

Erro de Limite de Requisições

Atualmente, o limite de requisições na API é de 5 requisições por segundo para cada cliente.

Caso diferentes aplicações da sua organização utilizem as mesmas credenciais para acessar a API da Árvore simultaneamente, é possível que o servidor comece a retornar HTTP 429 Too Many Requests, falhando as requisições e indicando que o limite foi ultrapassado.

Consulte o time da Árvore caso deseje alguma mudança nesta configuração.