Gravação de nota de avaliação parcial

Este tópico lista as características do WebService Json de gravação das notas de alunos em uma determinada avaliação.
Este método deverá ser chamado para gravar as notas de alunos para uma determinada avaliação.
Em caso de algum erro ocorrer, no retorno (detalhe) é enviada uma lista com os alunos inconsistentes. Em alguns casos, não é necessário interromper o processo de gravação de notas, retornando os alunos inconsistentes somente para notificação, porém, deve-se analisar a tabela de retornos pra verificar se as notas foram gravadas ou não.

Nome do método: gravaNotaAvaliacaoParcialParaListaDeAlunos

Parâmetros para chamada do WebService

Atributos retornados do WebService para o chamador

Possíveis retornos para o chamador do WebService

Exemplo de chamada do WebService

URL: http://IP:PORTA/APLICACAO/rest/ICorujaACA/gravaNotaAvaliacaoParcialParaListaDeAlunos

Exemplo da passagem de parâmetros por Json:

/*ctx:*/
{"usuario": 28}
 
 
/*avaliacaoParcialDTO:*/
{
    "idAvaliacao":null,
    "codigoIntegracaoAvaliacao":"123",
    "listAlunoNota":[
        {
            "idAluno":null,
            "codigoIntegracaoAluno":"230",
            "nota":"vinte"
        },
        {
            "idAluno":11868,
            "codigoIntegracaoAluno":"",
            "nota":"IMP"
        },
        {
            "idAluno":94667,
            "codigoIntegracaoAluno":"",
            "nota":"10"
        }
    ]
}

Atenção: O parâmetro usuario deve ser solicitado para a instituição de ensino. Orientamos a instituição a criar um usuário com o nome/login da empresa que está fazendo a integração.

Exemplo do retorno do WebService Json:

{
    "codigoRetornoIntegracao":"ICA_00000",
    "descricaoRetornoIntegracao":"Sucesso.",
    "observacaoRetornoIntegracao":null,
    "idAvaliacao":54133,
    "codigoIntegracaoAvaliacao":"123",
    "listAlunoNotaComInconsistencia":null
}

Quando o valor do atributo codigoRetornoIntegracao é diferente de ICA_00000 e ICA_00800, significa que ocorreu algum erro no WebService e não foi possível realizar a gravação das notas.
Para identificar melhor o erro, deve-se analisar a lista de alunos inconsistentes retornadas no atributo listAlunoNotaComInconsistencia que conterá todos os alunos que estão inconsistentes. Deve-se consultar o código retornado no atributo descrito acima na documentação, e ainda observar os atributos descricaoRetornoIntegracao e observacaoRetornoIntegracao que conterão maiores detalhes sobre o ocorrido.
O código de retorno ICA_00800 indica que o registro atual não foi gravado, porém, não interferiu no processo e os demais registros foram gravados com sucesso. Segue abaixo um exemplo de erro retornado, onde uma das notas foi informada com valor inválido, interrompendo todo o processo:

{
    "codigoRetornoIntegracao":"ICA_00407",
    "descricaoRetornoIntegracao":"Nota inválida",
    "observacaoRetornoIntegracao":"Foi informada alguma nota inválida, e o processo foi interrompido. Nenhuma nota foi gravada, por favor, analise o retorno dos detalhes pra verificar quais as notas que estão incorretas, e realize a correção.",
    "idAvaliacao":54133,
    "codigoIntegracaoAvaliacao":"123",
    "listAlunoNotaComInconsistencia":[
        {
            "codigoRetornoIntegracao":"ICA_00407",
            "descricaoRetornoIntegracao":"Nota inválida",
            "observacaoRetornoIntegracao":"Nota não informada ou não está no formato numérico. Se é utilizada a digitação por conceito, não foi encontrado a nota respectiva ao conceito informado.",
            "idAluno":null,
            "codigoIntegracaoAluno":"230",
            "nota":"vinte"
        }
    ]
}

Exemplo de chamada do WebService na linguagem PHP

<?php
header("Content-Type: text/html; charset=utf-8");
 
$curl = curl_init();
 
//realizar o urlencode de cada VALOR de parâmetro. O valor de cada parâmetro já deve estar no formato Json pra fazer o urlencode.
$paramCtx = "ctx=".urlencode('{"usuario":28}');
$paramAvaliacaoParcialDTO = "avaliacaoParcialDTO=".urlencode('{"idAvaliacao":null,"codigoIntegracaoAvaliacao":"123","listAlunoNota":[{"idAluno":null,"codigoIntegracaoAluno":"230","nota":"vinte"},{"idAluno":11868,"codigoIntegracaoAluno":"","nota":"IMP"},{"idAluno":94667,"codigoIntegracaoAluno":"","nota":"10"},{"idAluno":87558,"codigoIntegracaoAluno":"","nota":"9"},{"idAluno":94597,"codigoIntegracaoAluno":"","nota":"8"},{"idAluno":41503,"codigoIntegracaoAluno":"","nota":"7"},{"idAluno":946.20,"codigoIntegracaoAluno":"","nota":"6"},{"idAluno":47496,"codigoIntegracaoAluno":"","nota":"5"},{"idAluno":87621,"codigoIntegracaoAluno":"","nota":"4"},{"idAluno":95265,"codigoIntegracaoAluno":"","nota":"3"},{"idAluno":94672,"codigoIntegracaoAluno":"","nota":"1.558"},{"idAluno":40228,"codigoIntegracaoAluno":"","nota":"2"},{"idAluno":94784,"codigoIntegracaoAluno":"","nota":"5.5"},{"idAluno":95016,"codigoIntegracaoAluno":"","nota":"0"},{"idAluno":87612,"codigoIntegracaoAluno":"","nota":"7.5"}]}');
 
$parametros = $paramCtx."&".$paramAvaliacaoParcialDTO;
 
curl_setopt_array($curl, array(
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://192.168.0.66:8080/ICoruja/rest/ICorujaACA/gravaNotaAvaliacaoParcialParaListaDeAlunos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $parametros,
  CURLOPT_HTTPHEADER => array(
    "cache-control: no-cache",
    "content-type: application/x-www-form-urlencoded",
    "postman-token: 2635cd9e-ae8b-2db0-92d0-3eba7b19524c"
  ),
));
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>

Atenção: Conforme descrito acima, os valores dos parâmetros deverão ser codificados na forma application/x-www-form-urlencoded. No exemplo acima, o método urlencode é responsável por essa codificação.

Caso ocorra um erro parecido com o erro abaixo, a requisição não chegou até o método que realiza a gravação das notas das avaliações, muito provavelmente por conta de ter sido passado um parâmetro inválido, ou seja, geralmente uma String onde esperava-se um Inteiro.

{"central":false,"causaRaiz":{"causaRaizMsg":"RESTEASY003320: Failed processing arguments of
 org.jboss.resteasy.spi.metadata.ResourceMethod@3341b456","causaRaizStackTrace".........}