README

Pacote Laravel para integração com a API do Hub do Desenvolvedor, permitindo consultas de CPF, CNPJ, CEP, informações dos Correios, e outras funcionalidades de forma simples e eficiente. Este pacote facilita a interação com a API, incluindo validações prévias para evitar chamadas desnecessárias.

Instalação

Você pode instalar o pacote via Composer:

composer require paulorlima9/laravel-sdk-hubdodesenvolvedor

Publicação da Configuração

Para publicar o arquivo de configuração, execute:

php artisan vendor:publish --provider="PauloRLima\HubDoDesenvolvedor\HubDoDesenvolvedorServiceProvider" --tag="hubdodesenvolvedor-config"

Isso irá criar o arquivo config/hubdodesenvolvedor.php, onde você pode definir o token da API e outras configurações.

Configuração do Token

No arquivo .env da sua aplicação Laravel, adicione o seguinte:

HUBDODESENVOLVEDOR_TOKEN=seu_token_aqui
HUBDODESENVOLVEDOR_TIMEOUT=600
HUBDODESENVOLVEDOR_TIPO_RETORNO=json

Substitua seu_token_aqui pelo token fornecido pelo Hub do Desenvolvedor.

Uso

Utilizando a Facade

O pacote disponibiliza uma Facade para facilitar o uso. Certifique-se de que a Facade HubDoDesenvolvedor está registrada (deve estar automaticamente se você usa o Laravel 5.5 ou superior).

Exemplo: Consulta de CNPJ

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

class EmpresaController extends Controller
{
    public function consultarCNPJ($cnpj)
    {
        try {
            $resultado = HubDoDesenvolvedor::getCNPJ($cnpj);

            // Faça algo com o resultado
            return response()->json($resultado);
        } catch (\Exception $e) {
            // Trate erros
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}

Injetando Dependência

Você também pode injetar a classe HubDevApiClient diretamente no seu controlador ou serviço:

use PauloRLima\HubDoDesenvolvedor\HubDevApiClient;

class EmpresaController extends Controller
{
    protected $hubDevApi;

    public function __construct(HubDevApiClient $hubDevApi)
    {
        $this->hubDevApi = $hubDevApi;
    }

    public function consultarCNPJ($cnpj)
    {
        try {
            $resultado = $this->hubDevApi->getCNPJ($cnpj);

            // Faça algo com o resultado
            return response()->json($resultado);
        } catch (\Exception $e) {
            // Trate erros
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}

Exemplos de Uso

Consulta de CNPJ

Métodos Disponíveis:

getCNPJ($cnpj, $tipoRetorno = 'json'): Consulta de CNPJ (modalidade 1).
getCNPJModalidade2($cnpj, $tipoRetorno = 'json'): Consulta de CNPJ (modalidade 2 - ignora cache).
getCNPJLastUpdate($cnpj, $tipoRetorno = 'json'): Consulta a última atualização do CNPJ.
getCNPJInscricoesEstaduais($cnpj, $ie = 3, $tipoRetorno = 'json'): Consulta as inscrições estaduais do CNPJ.

Exemplo de Uso:

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

$cnpj = '12.345.678/0001-90';

try {
    // Consulta básica de CNPJ
    $resultado = HubDoDesenvolvedor::getCNPJ($cnpj);

    // Consulta ignorando cache
    $resultadoModalidade2 = HubDoDesenvolvedor::getCNPJModalidade2($cnpj);

    // Consulta última atualização
    $ultimaAtualizacao = HubDoDesenvolvedor::getCNPJLastUpdate($cnpj);

    // Consulta inscrições estaduais
    $inscricoesEstaduais = HubDoDesenvolvedor::getCNPJInscricoesEstaduais($cnpj);

    // Manipule os resultados conforme necessário
} catch (\Exception $e) {
    // Trate erros
    echo 'Erro: ' . $e->getMessage();
}

Consulta de CPF

Métodos Disponíveis:

getCPF($cpf, $dataNascimento, $tipoRetorno = 'json'): Consulta de CPF (modalidade 1).
getCPFModalidade2($cpf, $dataNascimento, $tipoRetorno = 'json'): Consulta de CPF (modalidade 2 - ignora cache).
getCPFLastUpdate($cpf, $dataNascimento, $tipoRetorno = 'json'): Consulta a última atualização do CPF.
getNomeDataNascimentoCPF($cpf, $tipoRetorno = 'json'): Consulta nome e data de nascimento pelo CPF.

Exemplo de Uso:

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

$cpf = '123.456.789-09';
$dataNascimento = '01/01/1990';

try {
    // Consulta básica de CPF
    $resultado = HubDoDesenvolvedor::getCPF($cpf, $dataNascimento);

    // Consulta ignorando cache
    $resultadoModalidade2 = HubDoDesenvolvedor::getCPFModalidade2($cpf, $dataNascimento);

    // Consulta última atualização
    $ultimaAtualizacao = HubDoDesenvolvedor::getCPFLastUpdate($cpf, $dataNascimento);

    // Consulta nome e data de nascimento
    $nomeData = HubDoDesenvolvedor::getNomeDataNascimentoCPF($cpf);

    // Manipule os resultados conforme necessário
} catch (\Exception $e) {
    // Trate erros
    echo 'Erro: ' . $e->getMessage();
}

Consulta de CEP

Método Disponível:

getCEP($cep, $tipoRetorno = 'json'): Consulta de CEP.

Exemplo de Uso:

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

$cep = '01001-000';

try {
    $resultado = HubDoDesenvolvedor::getCEP($cep);

    // Manipule os resultados conforme necessário
} catch (\Exception $e) {
    // Trate erros
    echo 'Erro: ' . $e->getMessage();
}

Consulta de Frete dos Correios

Método Disponível:

getCorreiosFrete(array $params, $tipoRetorno = 'json'): Consulta de frete nos Correios.

Parâmetros obrigatórios em $params:

servico: Código do serviço (ex: '40010' para SEDEX).
cepOrigem: CEP de origem.
cepDestino: CEP de destino.
altura: Altura do pacote em centímetros.
largura: Largura do pacote em centímetros.
peso: Peso do pacote em quilogramas.
comprimento: Comprimento do pacote em centímetros.
formato: Formato do pacote (1 para caixa/pacote).
tipoServico: Tipo de serviço.

Exemplo de Uso:

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

$params = [
    'servico' => '40010', // SEDEX
    'cepOrigem' => '01001-000',
    'cepDestino' => '20040-000',
    'altura' => '20',
    'largura' => '20',
    'peso' => '1',
    'comprimento' => '20',
    'formato' => '1',
    'tipoServico' => '1',
];

try {
    $resultado = HubDoDesenvolvedor::getCorreiosFrete($params);

    // Manipule os resultados conforme necessário
} catch (\Exception $e) {
    // Trate erros
    echo 'Erro: ' . $e->getMessage();
}

Consulta de Saldo

Método Disponível:

getSaldo($tipoRetorno = 'json'): Consulta o saldo disponível na API.

Exemplo de Uso:

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

try {
    $saldo = HubDoDesenvolvedor::getSaldo();

    // Manipule o saldo conforme necessário
} catch (\Exception $e) {
    // Trate erros
    echo 'Erro: ' . $e->getMessage();
}

Observações

Validações: O pacote realiza validações dos documentos (CPF, CNPJ, CEP) antes de realizar as requisições à API, evitando o consumo desnecessário de créditos.
Tratamento de Exceções: As exceções lançadas podem ser capturadas para tratamento adequado, como exibir mensagens de erro amigáveis ao usuário.
Timeout: O tempo limite para as requisições pode ser configurado no arquivo de configuração.

Configurações Adicionais

O arquivo de configuração config/hubdodesenvolvedor.php permite ajustar outras opções:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Token da API
    |--------------------------------------------------------------------------
    |
    | Insira aqui o seu token da API do Hub do Desenvolvedor. Você pode definir
    | isso no arquivo .env usando a variável HUBDODESENVOLVEDOR_TOKEN.
    |
    */

    'token' => env('HUBDODESENVOLVEDOR_TOKEN', ''),

    /*
    |--------------------------------------------------------------------------
    | Timeout da API
    |--------------------------------------------------------------------------
    |
    | Define o tempo máximo de execução para requisições na API. Você pode
    | definir isso no arquivo .env usando a variável HUBDODESENVOLVEDOR_TIMEOUT.
    |
    */

    'timeout' => env('HUBDODESENVOLVEDOR_TIMEOUT', 600),

    /*
    |--------------------------------------------------------------------------
    | Tipo de Retorno da API
    |--------------------------------------------------------------------------
    |
    | Defina o formato de retorno da API: 'json' ou 'xml'. Você pode definir isso
    | no arquivo .env usando a variável HUBDODESENVOLVEDOR_TIPO_RETORNO.
    |
    */

    'tipoRetorno' => env('HUBDODESENVOLVEDOR_TIPO_RETORNO', 'json'),

];

Certifique-se de que o token está corretamente definido para que as chamadas à API funcionem.

Testes

Para executar os testes, utilize:

composer test

Changelog

Por favor, veja o CHANGELOG para mais informações sobre as alterações recentes.

Contribuindo

Por favor, veja o CONTRIBUTING para detalhes.

Vulnerabilidades de Segurança

Por favor, consulte a nossa política de segurança sobre como reportar vulnerabilidades de segurança.

Créditos

Licença

The MIT License (MIT). Por favor, veja o Arquivo de Licença para mais informações.

Esperamos que este pacote facilite a integração com a API do Hub do Desenvolvedor em seus projetos Laravel. Para qualquer dúvida ou sugestão, fique à vontade para abrir uma issue ou enviar uma pull request.

paulorlima9 / laravel-sdk-hubdodesenvolvedor

Maintainers

Details

README

Instalação

Publicação da Configuração

Configuração do Token

Uso

Utilizando a Facade

Exemplo: Consulta de CNPJ

Injetando Dependência

Exemplos de Uso

Consulta de CNPJ

Métodos Disponíveis:

Exemplo de Uso:

Consulta de CPF

Métodos Disponíveis:

Exemplo de Uso:

Consulta de CEP

Método Disponível:

Exemplo de Uso:

Consulta de Frete dos Correios

Método Disponível:

Exemplo de Uso:

Consulta de Saldo

Método Disponível:

Exemplo de Uso:

Observações

Configurações Adicionais

Testes

Changelog

Contribuindo

Vulnerabilidades de Segurança

Créditos

Licença