ispbox2/sdk

SDK para acessar recursos da API Duobox

v1.0.5 2023-06-05 00:33 UTC

Requires

• php: >=7.4

Requires (Dev)

• squizlabs/php_codesniffer: 3.*

GPL-3.0-or-later

• Yan Tavares

README

Esta biblioteca prover aos desenvolvedores se comunicar de forma simples e rápida! reduzindo o tempo de integração aos recursos da API do Ispbox. Lembrando que esta SDK foi desenvolvida utilzando como base a API ispbox-ajax-requests API

🗒️ Sumário

• Instalação
• Configurando SDK
• Busca de cliente
  • Principais propriedades do objeto Cliente
  • ▷ Método findOne
• Busca de contratos / Planos contratados
  • Principais propriedades do objeto Contrato
  • ▷ Método Take
  • ▷ Método takeAny
  • ▷ Método toList
    • Buscando todos os contratos do cliente por Tipo
    • Buscando todos os contratos do cliente por Status
• Busca de Boletos
  • Principais propriedades do objeto Boleto
  • ▷ Método takeAll
    • Buscando todos os boletos do cliente por Tipo
    • Buscando todos os boletos do cliente por Status

💡 Requisitos

• PHP 7.4 ou superior
• URL ou IP do sistema (ex: https://demo2.ispbox.com.br)
• Usuário de acesso do sistema

💻 Instalação

1. Realize o download do Composer caso não tenha instalado.

2. No diretório raiz do seu projeto, execute em linha de comando

$ composer require ispbox2/sdk

✅ É isso! O SDK do Ispbox2 foi instalado com sucesso.

🌟 Codando

⚙️ Configurando SDK

  <?php
    require_once("vendor/autoload.php");
    
    Ispbox2\SDK::configure(URL, USER, PASS);
  ?>

Parâmetro	Tipo	Requisito	Descrição	Exemplo
URL	string	obrigatório	URL Base utilizado no seu ERP Ispbox	https://demo.ispbox.com.br
USER	string	obrigatório	Login de conta ispbox	admin
PASS	string	obrigatório	Senha de conta Ispbox	password

Note O método Configure() internamente faz um teste de conexão validando a URL e as credenciais. Caso não obtenha êxito no teste, é lançado uma exceção.

🔎 Busca de Cliente

▷ Método findOne()

  <?php
    require_once("vendor/autoload.php");
    use Ispbox2\Clientes;
    use Ispbox2\Enums\Clientes\Sidx;

    Ispbox2\SDK::configure('https://demo.ispbox.com.br','admin','password');

    $cliente = Clientes::findOne(Sidx::CPF, 61200456067);
    if($cliente->exists)
        echo $cliente->nome;
    else
      //Mensagem / Notificação / Ação
  ?>

Note O método findOne() é um método estático de busca que retora um objeto do tipo Cliente se houver registros encontrados, caso contrario retorna um objeto Cliente vazio. Para validar se a busca foi realizada com sucesso, utilize a propriedade exists em caso de true a busca obteve resultado!, para false a busca retornou vazia, logo o cliente não foi encontrado.

Parâmetro	Tipo	Requisito	Descrição	Exemplo
Sidx	Enum	obrigatório	Chave de referencia, parâmetro que a SDK usará como filtro de busca, podendo ser variados tipos como:	ID, CPF, CNPJ
Valor	mixed	obrigatório	Valor a ser buscado, com base na Sidx definida

Principais propriedades do objeto Cliente

Em caso de Pessoa Física as propriedades são:

Propriedade	Tipo	Descrição
id	string	ID referente ao cadastro do cliente no sistema
nome	string	retorna nome completo do cliente
dataCadastro	string	data em que foi cadastrado
telefone	string	contato de telefone
celular	string	contato de celular
email	string	email principal
emailSecundario	string	email secundario
exists	bool	retorna se o cadastro existe ou não
Endereco	object	Contém todos os dados de endereço do cadastro como, logradouro, numero, bairro, cep e etc...
nomePai	string	retorna nome do Pai
nomeMae	string	retorna nome do Mãe
profissao	string	retorna profissão do cliente
rg	string	retorna a numerção do documento RG
cpf	string	retorna a numerção do documento CPF

Em caso de Pessoa Jurídica as propriedades são:

Propriedade	Tipo	Descrição
id	string	ID referente ao cadastro do cliente no sistema
nomeFantasia	string	retorna nome completo da empresa
dataCadastro	string	data em que foi cadastrado
telefone	string	contato de telefone
celular	string	contato de celular
email	string	email principal
emailSecundario	string	email secundario
exists	bool	retorna se o cadastro existe ou não
Endereco	object	Contém todos os dados de endereço do cadastro como, logradouro, numero, bairro, cep e etc...
responsavel	string	retorna nome da pessoa responsável / proprietario(a) da empresa
inscricaoEstadual	string	retorna numeração da inscrição no estado
cnpj	string	retorna a numerção do documento CNPJ

📝 Busca de Contratos / Planos contratados

  <?php
    require_once("vendor/autoload.php");
    use Ispbox2\Clientes;
    use Ispbox2\Contratos;
    use Ispbox2\Enums\Clientes\Sidx;

    Ispbox2\SDK::configure('https://demo.ispbox.com.br','admin','password');

    $cliente   = Clientes::findOne(Sidx::CPF, '61200456067');
    if(!$cliente->exists)
          //Messagem de erro caso o cliente não seja valido

    $contratos = new Contratos($cliente);

Note A Classe Contratos é um objeto de busca que retora contratos (sejam eles de TELEFONIA ou de INTERNET) aderidos por determinado cliente válido, que é requisitado como parametro obrigatório do método Construtor da classe. Para filtrar informações do contrato utilize os métodos em seguida....

Principais propriedades do objeto Contrato

Propriedade	Tipo	Descrição
id	int	ID do contrato
clienteId	int	ID do cliente que contém o contrato
plano	string	Plano contratatado
valor	float	Valor mensal do contrato
dataInstalacao	string	data em que o serviço foi ativado
planoStatus	string	Status do plano... Liberado, bloqueado, susp..
planoStatusEnum	enum	Enum para comparação
active	bool	retorna se serviço está ativo (true), ou aguardando ativação (false)

▷ Método Take()

  <?php
    ...
    use Ispbox2\Enums\Contratos\Tipo;
    ...
    $contratos = new Contratos($cliente);
    $contratos->Take(Tipo::Internet);

Note O método Take() é um método de busca que retora um objeto do tipo Contrato se houver registros encontrados, caso contrario retorna um objeto Contrato vazio. O método Take() retorna somente um unico registro, por padrão se o segundo paramtro id não for passado... ele sempre retornara o primeiro contrato do cliente de acordo com o tipo escolhido. Porém caso queira retornar um contrato especifico é necessário passar o id do contrato como segundo parametro da função.

Parâmetro	Tipo	Requisito	Descrição	Exemplo
Tipo de contrato	Enum	obrigatório	Identificador que indicara o tipo de contrato a ser solicitado podendo ser:	Tipo::Internet ou Tipo::Telefonia
id	int	opcional	Refere-se a um contrato especifico do cliente, com base no Tipo de contrato definido	Por padrão é 0

▷ Método takeAny()

    <?php
      ...
      use Ispbox2\Enums\Contratos\Tipo;
      ...
      $contratos = new Contratos($cliente);
      $contratos->takeAny(35);

Note O método takeAny() é um método de busca que retorna um objeto do tipo Contrato somente com base no id informado.

Parâmetro	Tipo	Requisito	Descrição	Exemplo
id	int	obrigatório	Refere-se a ao id de contrato especifico do cliente

▷ Método toList()

    <?php
      ...
      use Ispbox2\Enums\Contratos\Tipo;
      ...
      $contratos = new Contratos($cliente);
      $contratos->toList();

Note O método toList() é um método de busca que retorna um array contendo todos os Contratos do cliente

Parâmetro	Tipo	Requisito	Descrição	Exemplo
Tipo	Enum	opcional	Refere-se ao tipo de contrato (INTERNET ou TELEFONIA)
Status	Enum	opcional	Refere-se ao status do do serviço

▷ Buscando todos os contratos do cliente por Tipo

Note Retorna array com todos os contratos sem distinção de status, apenas filtrando pelo tipo do contrato.

    <?php
      ...
      use Ispbox2\Enums\Contratos\Tipo;
      ...
      $contratos = new Contratos($cliente);

      $contratos->toList(Tipo::Internet); // Retorna array com todos os contratos de internet do cliente
      $contratos->toList(Tipo::Telefonia); // Retorna array com todos os contratos de internet do cliente

▷ Buscando todos os contratos do cliente por Status

Note Retorna array com todos os contratos sem distinção de tipo, apenas filtrando pelo status do contrato.

    <?php
      ...
      use Ispbox2\Enums\Contratos\Tipo;
      ...
      $contratos = new Contratos($cliente);

      $contratos->toList(null, Status::Liberado); // Retorna array com todos os contratos liberado do cliente
      $contratos->toList(null, Tipo::Bloqueado); // Retorna array com todos os contratos Bloqueado do cliente
      $contratos->toList(null, Tipo::ContratoSuspenso); // Retorna array com todos os contratos suspensos do cliente
      $contratos->toList(null, Tipo::SuspensoParcial); // Retorna array com todos os contratos suspensos parcialemnte do cliente

💲 Busca de Boletos

  <?php
    require_once("vendor/autoload.php");
    use Ispbox2\Clientes;
    use Ispbox2\Contratos;
    use Ispbox2\Enums\Clientes\Sidx;
    use Ispbox2\Boletos;

    Ispbox2\SDK::configure('https://demo.ispbox.com.br','admin','password');

    $cliente   = Clientes::findOne(Sidx::CPF, '61200456067');
    if(!$cliente->exists)
          //Messagem de erro caso o cliente não seja valido

    $contratos = new Contratos($cliente);
    $contratoInternet = $contratos->Take(Tipo::Internet);

    $boletos = new Boletos($contratoInternet);

Note A Classe Boletos é um objeto de busca que retora boletos (sejam eles de Mensalidades ou Avulsos) vinculado á um serviço do cliente, que é requisitado como parametro obrigatório do método Construtor da classe.

Principais propriedades do objeto Boleto

Propriedade	Tipo	Descrição
documentoId	int	Id do boleto no sistema
clienteId	int	Id do cliente que contém o boleto
contratoId	int	Id do contrato que contém o boleto
tipoContrato	Enum	Tipo do contrato que contem o boleto (Internet ou Telefonia)
descricao	string	descrição do boleto
vencimento	string	vencimento do boleto
dataGeracao	enum	data de criação
valor	string	valor em formato de Real R$ (para fins de renderização
valorFloat	float	valor em formato de decimal (para fins de calculo)
valorPago	string	valor pago em formato de Real R$ (para fins de renderização)
status	enum	retorna se o boleto está pago ou aberto
atrasado	bool	retorna (true) se o boleto estiver em aberto e atrasado, e (false) para aberto e em dias
dataPagamento	string	data da liquidação

▷ Método takeAll()

    <?php
      ...
      use Ispbox2\Boletos;
      ...
      $boletos = new Boletos($contratoInternet);
      $ListaBoletos = $boletos->takeAll();

Note O método takeAll() é um método de busca que retorna um array contendo todos os Boletos do cliente

Parâmetro	Tipo	Requisito	Descrição	Exemplo
DocTipo	Enum	opcional	Refere-se ao tipo de boleto (Mensalidade ou Avulso)
DocStatus	Enum	opcional	Refere-se ao status do boleto (Aberto) ou (Pago)

▷ Buscando todos os boletos do cliente por Tipo

Note Retorna array com todos os boletos sem distinção de status, apenas filtrando pelo tipo do boleto.

    <?php
      ...
      use Ispbox2\Boletos;
      ...
      $boletos      = new Boletos($contratoInternet);
      $Mensalidades = $boletos->takeAll(DocTipo::Mensalidade); // Retorna array com todos os boletos de mensalidade
      $Avulsos      = $boletos->takeAll(DocTipo::Avulso);// Retorna array com todos os boletos avulsos

▷ Buscando todos os boletos do cliente por Status

Note Retorna array com todos os boletos sem distinção de tipo, apenas filtrando pelo status do boleto.

    <?php
      ...
      use Ispbox2\Boletos;
      ...
      $boletos  = new Boletos($contratoInternet);
      $EmAbeto  = $boletos->takeAll(null, DocStatus::Aberto); // Retorna array com todos os boletos abertos
      $Pagos    = $boletos->takeAll(null, DocStatus::Pago); // Retorna array com todos os boletos pagos

Projeto em Desenvolvimento

🏻 License

Apache License 2.0
Para mais informações, veja o arquivo de LICENÇA.