DOCUMENTAÇÃO DA API DO GESPROV 1.0

ACESSANDO VIA PHP

Esta documentação tem como objetivo apresentar com acessar a API do Gesprov versão 1.0 utilizando o PHP. A versão recomendada do PHP é a 7.2. Também é possível baixar o pacote com todos os exemplos Clicando aqui

INFORMAÇÕES INICIAS:

Para iniciar a utilização dessa API, é necessário obter três informações com o Administrador do sistema:

  1. URL de acesso ao Sistema
  2. Usuário utilizado na API
  3. Senha do usuário utilizado na API

*Obs: Deverá ser criado um usuário específico dentro do sistema apenas para que possa ser utilizando com a API. Também deverá ser verificado o nível de permissão necessário para este usuário, além das filiais que ele terá permissão de acesso.

EXEMPLO DE UTILIZAÇÃO DA API:

Antes de efetuar a chamada de qualquer um dos endpoits, é necessário efetuar a autenticação dentro da nossa API. Utilizando a Classe ApiClient, Disponível no nosso pacote de exemplos, é possível executar essa etapa da seguinte forma: 

                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

OBTENDO DADOS DE UM CLIENTE:

Para obter os dados de um cliente específico, é necessário informar três parâmetros:

  1. cpf_cnpj: Número do CPF ou CNPJ do cliente que deseja consultar. esse parâmetro pode ser informado com ou sem formatação
  2. enviar_contratos: Situações do contrato devem ser consultadas, nesse parâmetro, é possível informar os seguintes valores: 'Todos', 'Ativos', 'Cancelados'
  3. enviar_servicos: Situações do serviço devem ser consultadas, nesse parâmetro, é possível informar os seguintes valores: 'Todos', 'Ativos/Bloqueados', 'Ativos', 'Bloqueados', 'Suspensos', 'Em negociação', 'Negativados', 'Cancelados'
                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);
$cpf_cnpj = "14265417752"; //CPF para testes

$parametros = array(
    "cpf_cnpj" => $cpf_cnpj,
    "enviar_contratos" => "Ativos",
    "enviar_servicos" => "Ativos/Bloqueados",
);

$dados_cliente = $apiClientObj->consultarClientePorCpfCnpj($parametros);

var_dump($dados_cliente);
                
            
                
object{
  ["cliente"]=>
  object {
    ["id"] => int(1)
    ["tipo"] => string(3) "cpf"
    ["nome_razao_social"] => string(26) "NOME COMPLETO DO CLIENTE"
    ["apelido"] => string(9) "APELIDO DO CLIENTE"
    ["cpf_cnpj"] => string(11) "14265417752" //CPF para testes
    ["rg_ie"] => string(13) "000000000000"
    ["nome_fantasia"] => string(0) ""
    ["id_endereco"] => int(220)
    ["numero"] => string(1) "0"
    ["complemento"] => string(0) ""
    ["referencia"] => string(0) ""
    ["telefone1"] => string(11) "00000000000"
    ["telefone2"] => string(11) "00000000000"
    ["telefone3"] => string(11) "00000000000"
    ["telefone4"] => string(11) "00000000000"
    ["email"] => string(21) "email@cliente.com.br"
    ["login_central"] => string(11) "login_central_cliente"
    ["senha_central"] => string(4) "senha_central_cliente"
    ["dt_nascimento"] => string(10) "1990-01-01"
    ["dt_cadastro"] => datetime "2021-01-01 12:00:00"
    ["pai"] => string(0) ""
    ["mae"] => string(0) ""
    ["observacoes"] => string(0) ""
    ["status"] => "Ativo"
    ["rua_cliente"] => string(26) "RUA DO CLIENTE"
    ["bairro_cliente"] => string(10) "CENTRO"
    ["cep_cliente"] => string(8) "61700000"
    ["cidade_cliente"] => string(13) "Aquiraz"
    ["estado_cliente"] => string(9) "Ceará"
    ["uf_cliente"] => string(2) "CE"
    ["contratos"] => array{
      [0] =>
      object{
        ["id"] => int(1)
        ["dt_cadastro"] => datetime "2021-01-01 12:00:00"
        ["status"] => string(5) "Ativo"
        ["filial"] => string(33) "NOME DO PROVEDOR"
        ["servicos"] => array{
          [0] => object{
            ["id"] => int(1)
            ["dt_contratacao"] => datetime "2021-01-01 12:00:00"
            ["fidelidade"] => string(3) "Sim"
            ["boleto_email"] => string(4) "Não"
            ["gerar_nf"] => string(4) "Não"
            ["id_endereco"] => int(316)
            ["numero"] => int(488)
            ["complemento"] => string(0) ""
            ["referencia"] => string(0) ""
            ["valor_servico"] => float "119.90"
            ["acrescimo_servico"] => float "0.00"
            ["desconto_servico"] => float "0.00"
            ["vencimento"] => int(5)
            ["data_fim_vigencia"] => datetime "2022-01-01 12:00:00"
            ["valor_instalacao"]=> string(4) "0.00"
            ["desconto_instalacao"] => string(4) "0.00"
            ["aceite_eletronico"] => string(3) "Sim"
            ["situacao"]=> string(5) "Ativo"
            ["agregador_servicos"] => string(4) "Não"
            ["cortesia"]=> string(4) "Não"
            ["plano"] => string(13) "PLANO 200M"
            ["conta_bancaria_servico"] => string(15) "BANCO DO BRASIL"
          }
        }
      }
    }
  }
}
                
            
                        
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "O campo enviar_contratos deve ser preenchido com uma das opções: 
    'Todos', 'Ativos', 'Cancelados'"
];

[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Para listar os serviços, é necessário solicitar os contratos"
];

[
    "erro" => "cpf_cnpj_sem_contrato",
    "descricao_erro" => "Não existe contratos " . ($dados['enviar_contratos'] == 'Ativos' ? 'ativos' : 'cancelados') . " para este CPF / CNPJ"
];

[
    "erro" => "cpf_cnpj_nao_localizado",
    "descricao_erro" => "CPF / CNPJ não localizado no sistema"
];

OBTENDO AS FATURAS DE UM CLIENTE:

Para obter as faturas de um cliente específico, é necessário informar três parâmetros:

  1. cpf_cnpj: Número do CPF ou CNPJ do cliente que deseja consultar. esse parâmetro pode ser informado com ou sem formatação
  2. numero_contrato: Caso queira especificar as faturas de um contrato específico do cliente, é possível informar o número do contrato
  3. numero_servico: Caso queira especificar as faturas de um serviço específico do cliente, é possível informar o número do serviço
  4. situacao_titulo: Situações das faturas que devem ser consultadas, nesse parâmetro, é possível informar os seguintes valores: 'Em abertos', 'Vencidos', 'A vencer', 'Pagos'
                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);
$cpf_cnpj = "14265417752";

$parametros = array(
    "cpf_cnpj" => $cpf_cnpj,
    "situacao_titulo" => "Pagos",
    "numero_servico" => "1",
);

$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$dados_faturas = $apiClientObj->consultarTitulosPorCliente($parametros);

var_dump($dados_faturas);

                
            
                
object{
  ["titulos"] => 
  object{
    ["id"] => int(5335)
    ["id_servico"] => int(1)
    ["nrdoc"] => int(5335)
    ["nosso_numero"] => int(3644)
    ["descricao"]=>
    string(57) "Referente ao periodo de 14/07/2021 a 09/08/2021 (27 dias)"
    ["tipo"] => string(11) "MENSALIDADE"
    ["data_processamento"] => datetime "2021-07-14 16:00:38"
    ["vencimento"] => datetime "2021-08-10 00:00:00"
    ["valor"] => float "75.40"
    ["desconto"] => float "0.00"
    ["motivo_desconto"] => string(0) ""
    ["tarifa"] => float "0.00"
    ["impresso"] => int(0)
    ["situacao"] => string(7) "Vencido"
    ["usuario_criacao_conta"] => string(7) "Usuário"
    ["conta_bancaria"] => string(15) "BANCO DO BRASIL"
    ["linha_digitavel"] => string(51) "0019000000 00000000000 00000000000 9 87080000007540"
  }
}
                
            
                        
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Informe o CPF / CNPJ para efetuar a busca dos titulos do cliente"
];

[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "O parametro situacao_titulo deve ter um dos seguintes valores: 'Em abertos', 'Vencidos', 'A vencer', 'Pagos'"
];

[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Para listar os titulos, é necessário informar o parametro situacao_titulo"
];

SOLICITAR DESBLOQUEIO EM CONFIANÇA:

Através deste endpoint, é possível solicitar um desbloqueio em confiança. É possível solicitar um desbloqueio em confiança para serviços que estão com a situação 'Bloqueado'. Neste endpoint, é necessário informar um parâmetro de entrada:

  1. numero_servico: Número do serviço que deseja solicitar o desbloqueio em confiança
                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$parametros = array(
    "numero_servico" => 567
);

$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$dados_faturas = $apiClientObj->solicitarDesbloqueioEmConfianca($parametros);

var_dump($dados_faturas);

                
            
                
object {
  ["status"]=> string(7) "sucesso"
  ["mensagem"]=> string(46) "Desbloqueio em confiança efetuado com sucesso"
}
                
            
                        
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Número do serviço não informado"
];
[
    "status" => "falha",
    "mensagem" => "Serviço não localizado"
];
[
    "status" => "falha",
    "mensagem" => "Não foi possível efetuar o desbloqueio em confiança, pois já foi efetuado um desbloqueio dentro do período de 30 dias"
];
[
    "status" => "falha",
    "mensagem" => "Não é possível efetuar o desbloqueio em confiança, pois este serviço já está ativo"
];

VERIFICAR FORMAS DE ENVIO HABILITADAS:

Através deste endpoint, é possível verificar as formas de envio habilitadas dentro do sistema. é possível ter até quatro formas de envio habilitada:

  1. email
  2. sms
  3. push
  4. whatsapp

                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$categorias_chamados = $apiClientObj->consultarFormasEnvioHabilitas();

var_dump($categorias_chamados);

                
            
                
object{
  ["formas_envio"] => array(3) {
    [0]=> string(5) "email"
    [1]=> string(3) "sms"
    [2]=> string(4) "push"
    [3]=> string(8) "whatsapp"
  }
}

ENVIAR FATURAS PARA O CLIENTE:

Através deste endpoint, é possível enviar as faturas diretamente ao cliente. Para efetuar o envio, é necessário informar dois parametros:

  1. id_fatura: Identificador da fatura que será enviada. Para consultar as faturas de um cliente, utilize o endpoint 'consultar-titulos'
  2. formas_envio: Este parametro é uma array e deve conter as formas que deseja enviar a fatura ao cliente. Para verificar as formas de envio habilitadas, utilize o endpoint 'verificar-formas-de-envio-habilitadas'
                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$parametros = array(
    "id_fatura" => 9991,
    "formas_envio" => ['email']
);

$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$dados_envio = $apiClientObj->enviarFatura($parametros);

var_dump($dados_envio);

                
            
                
object{
  ["status"] => string(7) "sucesso"
  ["descricao"] => string(26) "Fatura enviada com sucesso"
}
                
            
                        
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Número da fatura não informado"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Você deve informar as formas de envio da fatura para o cliente"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Forma de envio não disponível. Por favor, verifique as formas de envio disponível e teste novamente"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Nenhuma fatura localizada para o número informado"
];

BUSCAR CATEGORIAS DE CHAMADOS:

Através deste endpoint, é possível buscar as categorias de chamados cadastros no servidor do Gesprov. Isso é necessário para a abertura de chamados: 

                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$categorias_chamados = $apiClientObj->consultarCategoriasChamados();

var_dump($categorias_chamados);

                
            
                
object(stdClass)#9 (1) {
  ["categorias"]=>
  array(7) {
    [0]=>
    object{
      ["id"] => int(1)
      ["nome"] => string(10) "SEM CONEXÃO"
      ["status"] => int(1)
      ["apenas_clientes"] = int(1)
      ["departamento"] => string(7) "SUPORTE"
    }
    [1]=>
    object {
      ["id"]=> int(2)
      ["nome"] => string(22) "DIFICULDADES NA CONEXÃO"
      ["status"] => int(1)
      ["apenas_clientes"] => int(1)
      ["departamento"] => string(7) "SUPORTE"
    }
    [2]=>
    object{
      ["id"] => int(3)
      ["nome"] => string(20) "ASSUNTOS FINANCEIROS"
      ["status"] => int(1)
      ["apenas_clientes"] => int(1)
      ["departamento"] => string(10) "FINANCEIRO"
    }
    [3]=>
    object{
      ["id"] => int(5)
      ["nome"] => string(20) "INFORMAÇÕES COMERCIAIS"
      ["status"] => int(1)
      ["apenas_clientes"] => int(0)
      ["departamento"] => string(9) "COMERCIAL"
    }
    [4]=>
    object{
      ["id"] => int(6)
      ["nome"] => string(11) "VIABILIDADE"
      ["status"] => int(1)
      ["apenas_clientes"] => int(0)
      ["departamento"] => string(9) "COMERCIAL"
    }
  }
}

ABRIR CHAMADO:

Através deste endpoint, abrir um novo chamado / atendimento para um cliente. Para abrir chamado / atendimento, é necessário informar cinco parametros:

  1. numero_contrato: Número do contrato do cliente em que será aberto o chamado / atendimento.
  2. descricao: Descrição inicial do chamado
  3. relato_cliente: Informar o problema relatado pelo cliente para a abertura do chamado
  4. url_arquivo_gravacao: URL do arquivo de gravação da chamada realizada pelo cliente
  5. categoria_chamado: Categoria do chamado que será aberto, para consultar as categorias de chamados cadastradas dentro do Gesprov, utilize o endpoint 'categorias-chamados'
                
<?php
include_once("ApiClient.php");

$url = "https://sandbox.gesprov.com.br";
$client_id = "nome_usuario";
$client_secret = "senha_usuario";
$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$parametros = array(
    "numero_contrato" => "321",
    "descricao" => "Descrição da abertura dos chamados",
    "relato_cliente" => "Relato do cliente na abertura de atendimentos",
    "url_arquivo_gravacao" => "url_arquivo_gravacao",
    "categoria_chamado" => "2",
);

$apiClientObj = new Gesprov\ApiClient($url, $client_id, $client_secret, false);

$dados_atendimento = $apiClientObj->abrirChamado($parametros);

var_dump($dados_atendimento);

                
            
                
object {
  ["status"] => string(7) "sucesso"
  ["descricao"] => string(26) "Chamado aberto com sucesso"
  ["protocolo"] => string(12) "202112221196"
}
                
            
                        
[
    "erro" => "usuario_invalido",
    "descricao_erro" => "O token informado não é valido. Verfique o seu token e tente novamente"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Número de contrato não informado"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Descrição do chamado não informada"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Você deve informar o relato do cliente para abrir o chamado"
];
[
    "erro" => "parametros_incorretos",
    "descricao_erro" => "Você deve informar a subcategoria para abrir o chamado"
];