README

Laravel 包用于与 开发者 Hub API 集成，允许简单高效地进行 CPF、CNPJ、CEP、邮政信息以及其他功能查询。此包简化了与 API 的交互，包括预先验证以避免不必要的调用。

安装

您可以通过 Composer 安装此包

composer require paulorlima9/laravel-sdk-hubdodesenvolvedor

发布配置文件

要发布配置文件，请执行

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

这将会创建 config/hubdodesenvolvedor.php 文件，您可以在其中定义 API 令牌和其他配置。

配置令牌

在您的 Laravel 应用 .env 文件中，添加以下内容

HUBDODESENVOLVEDOR_TOKEN=seu_token_aqui
HUBDODESENVOLVEDOR_TIMEOUT=600
HUBDODESENVOLVEDOR_TIPO_RETORNO=json

将 seu_token_aqui 替换为开发者 Hub 提供的令牌。

使用方法

使用 Facade

该包提供了一个 Facade 以简化使用。请确保 Facade HubDoDesenvolvedor 已注册（如果您使用的是 Laravel 5.5 或更高版本，它应该会自动注册）。

示例：查询 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);
        }
    }
}

注入依赖

您也可以直接在控制器或服务中注入 HubDevApiClient 类

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);
        }
    }
}

使用示例

查询 CNPJ

可用方法

• getCNPJ($cnpj, $tipoRetorno = 'json'): 查询 CNPJ（模式 1）。
• getCNPJModalidade2($cnpj, $tipoRetorno = 'json'): 查询 CNPJ（模式 2 - 忽略缓存）。
• getCNPJLastUpdate($cnpj, $tipoRetorno = 'json'): 查询 CNPJ 的最后更新。
• getCNPJInscricoesEstaduais($cnpj, $ie = 3, $tipoRetorno = 'json'): 查询 CNPJ 的州注册。

使用示例

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();
}

查询 CPF

可用方法

• getCPF($cpf, $dataNascimento, $tipoRetorno = 'json'): 查询 CPF（模式 1）。
• getCPFModalidade2($cpf, $dataNascimento, $tipoRetorno = 'json'): 查询 CPF（模式 2 - 忽略缓存）。
• getCPFLastUpdate($cpf, $dataNascimento, $tipoRetorno = 'json'): 查询 CPF 的最后更新。
• getNomeDataNascimentoCPF($cpf, $tipoRetorno = 'json'): 通过 CPF 查询姓名和出生日期。

使用示例

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();
}

查询 CEP

可用方法

• getCEP($cep, $tipoRetorno = 'json'): 查询 CEP。

使用示例

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();
}

查询邮政快递费用

可用方法

• getCorreiosFrete(array $params, $tipoRetorno = 'json'): 查询邮政快递费用。

$params 中的必填参数

• servico: 服务代码（例如：'40010' 用于 SEDEX）。
• cepOrigem: 起始 CEP。
• cepDestino: 目标 CEP。
• altura: 包裹高度（厘米）。
• largura: 包裹宽度（厘米）。
• peso: 包裹重量（千克）。
• comprimento: 包裹长度（厘米）。
• formato: 包裹格式（1 为盒子/包裹）。
• tipoServico: 服务类型。

使用示例

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();
}

查询余额

可用方法

• getSaldo($tipoRetorno = 'json'): 查询 API 中可用的余额。

使用示例

use PauloRLima\HubDoDesenvolvedor\Facades\HubDoDesenvolvedor;

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

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

注意事项

• 验证：在向 API 发出请求之前，该包会对文档（CPF、CNPJ、CEP）进行验证，以避免不必要的信用消耗。
• 异常处理：抛出的异常可以被捕获以进行适当的处理，例如向用户显示友好的错误消息。
• 超时：可以通过配置文件设置请求的超时时间。

附加配置

配置文件 config/hubdodesenvolvedor.php 允许调整其他选项

<?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'),

];

请确保令牌被正确设置，以便API调用可以正常工作。

测试

要运行测试，请使用

composer test

更新日志

请参阅更新日志以获取有关最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全问题

有关报告安全漏洞的详细信息，请参阅我们的安全策略。

致谢

• Paulo R. Lima
• 所有贡献者

许可证

MIT许可证（MIT）。请参阅许可文件以获取更多信息。

我们希望这个包能简化您在Laravel项目中与开发者Hub API的集成。如有任何疑问或建议，请随时创建一个issue或发送一个pull request。