APIs Públicas

Fluxo geral do processo

APIs disponíveis

URL	Método	Descrição	Headers
https://paisalunos.suite.betha.cloud/parceiros/v1/acessos/{chave}	GET	Consultar informações das chaves dos alunos	authorization, user-access
https://paisalunos.suite.betha.cloud/parceiros/v1/alunos	GET	Consultar informações dos alunos	authorization,user-access, app-context
https://paisalunos.suite.betha.cloud/parceiros/v1/enturmacoes	GET	Consultar informações das enturmações dos alunos	authorization, user-access, app-context
https://paisalunos.suite.betha.cloud/parceiros/v1/frequencias?enturmacaoId={idEnturmacaoAluno}	GET	Consultar informações de frequência das enturmações dos alunos	authorization, user-access, app-context

Visão geral das APIs disponíveis

• A API referente à /acessos/{chave} é responsável por retornar os dados de ID do aluno referente à chave de acesso (a chave é disponibilizada aos pais através do boletim ou em contato com a secretaria de educação) e também os dados de identificação da entidade do cliente. Conforme exemplo abaixo:

 {
 "id": 123456,
 "entidade": 1,
 "database": 2,
 "usarSolicitacaoRematricula": false
 }

Com os dados retornados é possível gerar o header app-context que será utilizado para as outras APIs (conforme descrito com mais detalhes na seção abaixo no item referente à contexto de aplicação)

• A API referente à /alunos é responsável por retornar os dados do aluno, conforme ID do mesmo incluído criptografado no header app-context, como nome do aluno, foto, data de nascimento, sexo e CPF. Conforme exemplo abaixo:

  • Obs: A URL gerada para acesso à foto do aluno é válida por 1 dia para download do arquivo

    {
    "id": 123456,
    "pessoa": {
     "id": 978654,
    "nome": "Fulana de Tal",
    "nomeFantasia": "Nome Social",
    "emails": [],
    "fisica": {
    "id": 5678910,
    "dataNascimento": "2000-01-01",
    "sexo": "FEMININO",
    "cpf": "49411744426"
    }
    },
    "foto": {
    "id": 10111213,
    "nome": "foto.jpg",
    "tipo": "image/jpeg",
    "url": "https://s3.sa-east-1.amazonaws.com/educacao.betha.cloud/educacao/5f0361ce-5b1d-4108-9678-67303cb4b7ba?response-content
    },
    "chaveAcesso": "YmrsVH1KlzJf"
    }

• A API referente à /enturmacoes é responsável por retornar os dados das matrículas e turmas em que o aluno, conforme ID do mesmo incluído criptografado no header app-context, possui vínculo na entidade em questão, retornando informações como situação da matrícula, turno da matrícula, número da chamada, estabelecimento e turma em que está matriculado e também o ano letivo. Conforme exemplo abaixo:

  [
  {
  "id": 11121314,
  "matricula": {
  "id": 15161718,
  "situacao": "CURSANDO",
  "turno": "MATUTINO",
  "estabelecimento": {
  "id": 123,
  "pessoa": {
  "id": 141516,
  "nome": "ESCOLA MUNICIPAL API PUBLICA"
  }
  },
  "anoLetivo": {
  "id": 1234,
  "ano": 2023
  }
  },
  "turma": {
  "id": 1234567,
  "nome": "8º Ano B"
  },
  "numeroChamada": 4,
  "anoLetivo": {
  "id": 1234,
  "ano": 2023
  }
  }
  ]

• A API referente à /frequencias?enturmacaoId={idEnturmacaoAluno} é responsável por retornar os dados das faltas e percentuais de frequência do aluno no ano letivo e períodos avaliativos que o mesmo estiver enturmado. O parâmetro idEnturmacaoAluno é o ID da enturmação retornado através da API /enturmacoes. Exemplo de retorno da requisição:

  {
  "faltas": [
  {
  "itemEducacional": {
  "id": 15161718,
  "descricao": "1º Bimestre"
  },
  "totalFaltas": 1,
  "periodoAvaliativo": {
  "id": 12131415,
  "descricao": "1º Bimestre",
  "dataInicial": "2023-02-08",
  "dataFinal": "2023-04-16"
  }
  }
  ],
  "isAtividade": false,
  "faltasAnoLetivo": 1,
  "percentualAnoLetivo": 99.87
  }

Geração dos headers para as requisições

Chave de acesso (user-acess)

É necessário acessar a aplicação administrativa do sistema Pais e Alunos (https://admin.paisalunos.betha.cloud) e seguir os passos das imagens abaixo:

Acesse a opção Gerenciador de acessos

Acesse a opção Aplicações e adicione um novo registro

Informe a chave pública disponibilizada via email e clique em Continuar

Será visualizada a tela de confirmação, clique em Confirmar e obter chave de acesso

A chave de acesso será disponibilizada para copiar clicando em Copiar chave de acesso, fique atento as orientações repassadas na tela.

Token de autorização (authorization)

O token de autorização é disponibilizado via email em conjunto com a chave pública e deve ser utilizado como valor no header conforme exemplo: Bearer 57y93af1-61b1-40b5-b76k-79ax12f9p829

Contexto de aplicação (app-context)

Para a API de chave de acesso são necessários apenas os headers de Authorization e User-Access, já para as restantes é necessário também o header de App-Context que deverá ser gerado conforme abaixo:

• Primeiramente é necessário buscar os dados através da API /acessos/{chave} informando a chave do aluno em questão (a chave é disponibilizada aos pais através do boletim ou em contato com a secretaria de educação)

• Através do método GET na API citada será retornada a seguinte estrutura:

     {
     "id": 123456,
     "entidade": 1,
     "database": 2,
     "usarSolicitacaoRematricula": false
     }

• Com os dados retornados na API é necessário codificar no formato Base64 para gerar o valor para o header App-Context, com base no formato abaixo:

       {"database":2,"entidade":1,"aluno":123456,"usarSoliciacaoRematricula":false}

• Ao codificar a estrutura acima no formato Base64 será gerado um valor semelhante ao abaixo:

  • eyJkYXRhYmFzZSI6MiwiZW50aWRhZGUiOjEsImFsdW5vIjoxMjM0NTYsInVzYXJTb2xpY2lhY2FvUmVtYXRyaWN1bG

Exemplo de utilização dos headers para uso nas APIs

Com os headers gerados e disponíveis é possível então realizar as requisições, conforme exemplo abaixo utilizando a API /alunos:

GET na api /alunos retornando os dados do aluno conforme ID do aluno gerado no header app-context

      curl --location 'https://paisalunos.suite.betha.cloud/parceiros/v1/alunos' \
     --header 'Authorization: Bearer 57b93af1-61b1-40b5-b76c-79ab12f9d829' \
     --header 'app-context: eyJkYXRhYmFzZSI6MiwiZW50aWRhZGUiOjEsImFsdW5vIjoxMjM0NTYsInVzYXJTb2xpY2lhY2FvUmVtYXRyaWN1bGEiOmZhbHNlfQ==' \
     --header 'user-access: l-CKIej_x_5Mi9OMHDoxvmaxkZc5a3n4PJjt8Vu_zSY='