README

这是一个用于IFRN的SUAP（Sistema Unificado de Administração Publica，统一公共管理系统）API的PHP包装器。该软件包允许您在PHP应用程序中访问SUAP数据。

它是SUAP Bot的主要组件。

目前提供成绩单（成绩，出勤率）信息、课程、时间表、上课地点和学生数据。

此软件包已更新，现在通过SUAP官方API访问数据，而不是通过web scraping。如果您需要使用进行web scraping的版本，请查看标签 0.2.0。

安装

建议使用Composer来安装。

将以下依赖项添加到您的composer.json中，并执行composer update。

"require": {
    "ivmelo/suap-api-php": "1.0.*"
}

或者，您可以直接通过命令行安装

$ composer require "ivmelo/suap-api-php": "1.0.*"

使用

您可以使用访问令牌实例化一个客户端，或者使用空构造函数。

$suap = SUAP('token');
// ou
$suap = SUAP();
$suap->setToken('token');

身份验证

为了进行身份验证，只需调用方法autenticar($usuario, $chave)。

$suap = SUAP();
$data = $suap->autenticar('20121014040000', 'senhaouchave');

该方法将返回一个包含访问令牌（$data['token']）的数组。

Array
(
    [token] => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJ1c2VybmFtZSI6IjIwMTIxMDE0MDQwMDgzIiwib3JpZ19pYXQiOjE0OTQwMjcyMDksInVzZXJfaWQiOjEwODQyLCJlbWFpbCI6Iml2YW5pbHNvbi5tZWxvQGFjYWRlbWljby5pZnJuLmVkdS5iciIsImV4cCI6MTQ5NDExMzYwOX0
)

令牌将保存在对象中，以便在后续请求中重复使用。如果您不想保存令牌，只需将构造函数的第四个参数设置为false：autenticar($matricula, $senha, true, false)。

您还可以使用负责人访问令牌进行登录。为此，只需将方法autenticar($matricula, $chave, true)的第三个参数传递为true。

$suap = SUAP();
$suap->autenticar('20121014040000', 'chave', true);

要获取访问令牌，请登录SUAP，然后在“我的数据”>“个人信息”>“一般数据”中查找“访问令牌”。它应该是5位数，类似于4d5f9。

学生数据

要获取学生数据，请调用方法getMeusDados()。

$meusDados = $suap->getMeusDados();

输出将是一个包含学生和课程基本信息的数组。

Array
(
    [id] => 123456
    [matricula] => 20121014040000
    [nome_usual] => Nome Sobrenome
    [email] => nome.sobrenome@academico.ifrn.edu.br
    [url_foto_75x100] => /media/alunos/000000.jpg
    [tipo_vinculo] => Aluno
    [vinculo] => Array
        (
            [matricula] => 20121014040000
            [nome] => Nome Completo Do Estudante
            [curso] => Tecnologia em Análise e Desenvolvimento de Sistemas
            [campus] => CNAT
            [situacao] => Matriculado
            [cota_sistec] =>
            [cota_mec] =>
            [situacao_sistemica] => Migrado do Q-Acadêmico para o SUAP
        )

)

学年度

要获取学生的学年度，请使用方法getMeusPeriodosLetivos()。

$meusDados = $suap->getMeusPeriodosLetivos();

输出将是一个包含学生学年度列表的数组。

Array
(
    [0] => Array
        (
            [ano_letivo] => 2012
            [periodo_letivo] => 1
        )

    [1] => Array
        (
            [ano_letivo] => 2012
            [periodo_letivo] => 2
        )

    ...

    [10] => Array
        (
            [ano_letivo] => 2017
            [periodo_letivo] => 1
        )

)

成绩单

要获取学生的成绩单数据，请实例化一个客户端并调用方法getMeuBoletim($anoLetivo, $periodoLetivo)。

$boletim = $suap->getMeuBoletim(2017, 1);

输出将是一个包含学生成绩单中找到的科目信息的数组。

只有高等教育学生将获得第1阶段和第2阶段的成绩。

虚拟班级列表

要查看虚拟班级列表（包括id、时间表和上课地点），请使用方法getTurmasVirtuais($anoLetivo, $periodoLetivo)。

$turmasVirtuais = $suap->getTurmasVirtuais(2017, 1);

该方法将返回一个包含当前学期科目列表和其他相关信息的数组。

Array
(
    [0] => Array
        (
            [id] => 20118
            [sigla] => TEC.0011
            [descricao] => Gestão de Tecnologia da Informação
            [observacao] =>
            [locais_de_aula] => Array
                (
                    [0] => Audio de Visual 03 - DIATINF - Prédio Anexo - 1º Andar (CNAT)
                )

            [horarios_de_aula] => 2V34 / 3V56
        )

    [1] => Array
        (
            [id] => 20119
            [sigla] => TEC.0012
            [descricao] => Computador e Sociedade
            [observacao] =>
            [locais_de_aula] => Array
                (
                    [0] => Audio de Visual 03 - DIATINF - Prédio Anexo - 1º Andar (CNAT)
                )

            [horarios_de_aula] => 3V34
        )

    [2] => Array
        (
            [id] => 20120
            [sigla] => TEC.0036
            [descricao] => Seminário de Orientação para Trabalho de Conclusão de Curso
            [observacao] =>
            [locais_de_aula] => Array
                (
                    [0] => Audio de Visual 03 - DIATINF - Prédio Anexo - 1º Andar (CNAT)
                )

            [horarios_de_aula] => 4V34
        )

    [3] => Array
        (
            [id] => 20102
            [sigla] => TEC.0004
            [descricao] => Epistemologia da Ciência
            [observacao] =>
            [locais_de_aula] => Array
                (
                    [0] => Audio de Visual 02 - DIATINF - Informática (CNAT)
                )

            [horarios_de_aula] => 3M56
        )

    [4] => Array
        (
            [id] => 23115
            [sigla] => TEC.0075
            [descricao] => Aplicações com Interfaces Ricas
            [observacao] =>
            [locais_de_aula] => Array
                (
                    [0] => Laboratório 06 - DIATINF - Informática (CNAT)
                )

            [horarios_de_aula] => 2M56 / 4M56
        )

)

虚拟班级详情

要查看虚拟班级的详细信息，请使用方法getTurmaVirtual($idDaTurma)。

$course = $suap->getTurmaVirtual(23115);

返回将是一个包含班级详细信息（包括参与者、课程、教学材料、教师等）的数组。

上课时间表

要获取上课时间表（以数组形式），请使用方法getHorarios($anoLetivo, $periodoLetivo)。

$horarios = $suap->getHorarios(2017, 1);

这将返回一个关联数组，使用星期几作为键（1：星期日，2：星期一，3：星期二...），学期作为子键（M：上午，V：下午，N：晚上）和课程时段作为第二个子键（1-6）。

例如，获取周二下午的第四节课

print_r($schedule[3]['V'][4]);

方法返回的结果如下（省略了一些部分，使用 ... 表示）。

如果在请求过程中发生错误怎么办？

如果在请求过程中发生错误，HTTP 客户端将抛出异常。这包括登录失败、404、500 等...

您应该在每次使用 API 方法时使用 try-catch 块来处理应用程序中可能发生的错误。

开发（如何贡献）

为了帮助开发，请克隆仓库，安装依赖项，并使用位于 tests 文件夹中的 test.php 文件。

$ git clone git@github.com:ivmelo/suap-api-php.git
$ cd suap-api-php
$ composer install
$ cd tests
$ php test.php <matricula> <chave>

根据您的喜好修改 test.php 文件，但除非您为库添加了新功能，否则请避免提交更改。

最新开发代码位于分支 master。

待办事项

查看问题部分，了解还有哪些工作要做或是否有需要关注的错误。

早期版本

要查看库的早期版本（包括进行网络爬取的版本），请查看项目的标签。

许可证

MIT 许可证 (MIT)

特此授予任何人免费获得此软件及其相关文档文件（“软件”）副本的权限，不受限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许向软件提供副本的个人执行上述操作，前提是遵守以下条件

本软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、适用于特定目的和不侵犯他人权利的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论此类责任是基于合同、侵权或其他原因，不论此类责任是否因软件或软件的使用或其他方式而产生。

ivmelo / suap-api-php

维护者

详细信息