PHPackages                             quantumtecnology/falcon-datahub-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. quantumtecnology/falcon-datahub-sdk

ActiveLibrary[API Development](/categories/api)

quantumtecnology/falcon-datahub-sdk
===================================

PHP SDK for the Falcon DataHub API — CEP, CNPJ, NCM, FIPE, BCB, and more Brazilian data services

1.0.0(3mo ago)059MITPHPPHP ^8.0

Since Mar 26Pushed 1mo agoCompare

[ Source](https://github.com/Quantum-Tecnology/falcon-datahub-sdk-php)[ Packagist](https://packagist.org/packages/quantumtecnology/falcon-datahub-sdk)[ Docs](https://github.com/Quantum-Tecnology/falcon-datahub-sdk-php)[ RSS](/packages/quantumtecnology-falcon-datahub-sdk/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (2)Used By (0)

Falcon DataHub SDK for PHP
==========================

[](#falcon-datahub-sdk-for-php)

SDK PHP para a API do Falcon DataHub. Consulte CEPs, CNPJs, NCMs, tabela FIPE, taxas BCB, e muito mais com uma interface fluida e zero dependencias de framework.

Requisitos
----------

[](#requisitos)

- PHP >= 8.0
- ext-curl
- ext-json

Instalacao
----------

[](#instalacao)

```
composer require quantumtecnology/falcon-datahub-sdk
```

Configuracao
------------

[](#configuracao)

### Com token direto

[](#com-token-direto)

```
use QuantumTecnology\FalconDataHub\Falcon;
use QuantumTecnology\FalconDataHub\FalconConfig;

Falcon::configure(new FalconConfig(
    baseUrl: 'https://datahub.falcon-server.com.br',
    token: 'seu-token-bearer',
));
```

### Com login automatico

[](#com-login-automatico)

```
Falcon::configure(FalconConfig::withCredentials(
    baseUrl: 'https://datahub.falcon-server.com.br',
    email: 'usuario@exemplo.com',
    password: 'sua-senha',
));
```

O SDK faz login automaticamente e cacheia o token em memoria. Se o token expirar (401), ele re-autentica e retenta a requisicao.

### Configuracoes opcionais

[](#configuracoes-opcionais)

```
Falcon::configure(new FalconConfig(
    baseUrl: 'https://datahub.falcon-server.com.br',
    token: 'seu-token',
    timeout: 30,          // Timeout da requisicao em segundos
    connectTimeout: 10,   // Timeout de conexao em segundos
    retries: 3,           // Tentativas em caso de falha (5xx/timeout)
    retryDelay: 2000,     // Delay entre tentativas em ms
    cache: $psrCache,     // PSR-16 CacheInterface (persistir token)
    logger: $psrLogger,   // PSR-3 LoggerInterface (debug)
));
```

### Uso com injecao de dependencia

[](#uso-com-injecao-de-dependencia)

```
use QuantumTecnology\FalconDataHub\FalconClient;

$client = new FalconClient(new FalconConfig(
    baseUrl: 'https://datahub.falcon-server.com.br',
    token: 'seu-token',
));

$result = $client->cep()->search('13472360');
```

Uso
---

[](#uso)

### CEP (Codigo Postal)

[](#cep-codigo-postal)

```
$result = Falcon::cep()->search('13472360');
// $result->success    // bool
// $result->data       // array com dados do CEP
// $result->message    // string
```

### CNPJ (Cadastro de Pessoa Juridica)

[](#cnpj-cadastro-de-pessoa-juridica)

```
$result = Falcon::cnpj()->search('11.222.333/0001-44');
// Aceita com ou sem mascara — caracteres nao-numericos sao removidos automaticamente
```

### CNAE (Atividade Economica)

[](#cnae-atividade-economica)

```
$result = Falcon::cnae()->search('6201-5');
```

### NCM (Nomenclatura Comum do Mercosul)

[](#ncm-nomenclatura-comum-do-mercosul)

```
$result = Falcon::ncm()->search('84713012');
```

### IP (Geolocalizacao)

[](#ip-geolocalizacao)

```
$result = Falcon::ip()->search('8.8.8.8');
$result = Falcon::ip()->search('8.8.8.8', databaseId: 1);
```

### Acoes / Simbolos (Bolsa)

[](#acoes--simbolos-bolsa)

```
$result = Falcon::action()->search('PETR4');
```

### Cidades e Estados

[](#cidades-e-estados)

```
$states = Falcon::states()->list();
$state  = Falcon::states()->show(35); // Sao Paulo

$cities = Falcon::cities()->list(stateId: 35);
$city   = Falcon::cities()->show(3550308); // Sao Paulo capital
```

### Validacao (CPF, CNPJ, PIX)

[](#validacao-cpf-cnpj-pix)

```
$result = Falcon::validate()->cpf('123.456.789-09');
$result = Falcon::validate()->cnpj('11222333000144');
$result = Falcon::validate()->pix('email@exemplo.com');

// Gerar documentos validos (para testes)
$cpf  = Falcon::validate()->generateCpf();
$cnpj = Falcon::validate()->generateCnpj();
```

### Brasil (DDD, Bancos, Feriados)

[](#brasil-ddd-bancos-feriados)

```
$result = Falcon::brasil()->ddd('11');        // DDD de Sao Paulo
$banks  = Falcon::brasil()->banks();          // Todos os bancos
$bank   = Falcon::brasil()->bank('001');      // Banco do Brasil
$fds    = Falcon::brasil()->holidays(2026);   // Feriados de 2026
```

### BCB (Banco Central — Indicadores)

[](#bcb-banco-central--indicadores)

```
$selic    = Falcon::bcb()->selic();
$cdi      = Falcon::bcb()->cdi();
$ipca     = Falcon::bcb()->ipca(2026);
$cambio   = Falcon::bcb()->currency('USD', 'BRL');
```

### FIPE (Tabela de Veiculos)

[](#fipe-tabela-de-veiculos)

```
$brands = Falcon::fipe()->brands('carros');
$models = Falcon::fipe()->models('carros', '59');
$years  = Falcon::fipe()->years('carros', '59', '5940');
$price  = Falcon::fipe()->price('carros', '59', '5940', '2024-1');
```

### Fiscal (CFOP, CST, Lista de Serviço Nacional)

[](#fiscal-cfop-cst-lista-de-serviço-nacional)

```
$cfops = Falcon::fiscal()->cfopList();
$cfop  = Falcon::fiscal()->cfop('5102');
$csts  = Falcon::fiscal()->cstList('ICMS');
$cst   = Falcon::fiscal()->cst('ICMS', '00');

// Lista de Serviço Nacional (cTribNac) — NFS-e Padrão Nacional
$servicos = Falcon::fiscal()->serviceCodesList('software');       // busca paginada
$servicos = Falcon::fiscal()->serviceCodesList(item: 1, page: 2); // filtra item da LC 116
$servico  = Falcon::fiscal()->serviceCode(42);                    // por id
```

### Produtos (Inteligencia de Precos)

[](#produtos-inteligencia-de-precos)

```
$product = Falcon::products()->findByEan('7891234567890', region: 'SP');
$prices  = Falcon::products()->prices(1, region: 'SP');
$results = Falcon::products()->search('arroz');
```

### Delivery (Rotas e Distancias)

[](#delivery-rotas-e-distancias)

```
$route    = Falcon::delivery()->bestRoute([...]);
$distance = Falcon::delivery()->calculateDistance([...]);
```

### XML (NFe)

[](#xml-nfe)

```
$xmls   = Falcon::xml()->list();
$search = Falcon::xml()->search('11222333000144');
$xml    = Falcon::xml()->show(1);
$upload = Falcon::xml()->upload(['xml' => '...']);
$del    = Falcon::xml()->destroy(1);
```

### Cartoes de Credito

[](#cartoes-de-credito)

```
$cards  = Falcon::creditCards()->list();
$create = Falcon::creditCards()->create([...]);
$delete = Falcon::creditCards()->destroy(1);
```

### Planos e Assinaturas

[](#planos-e-assinaturas)

```
$plans  = Falcon::plans()->list();
$plan   = Falcon::plans()->show(1);

$subs   = Falcon::subscriptions()->list();
$active = Falcon::subscriptions()->active();
$create = Falcon::subscriptions()->create(['plan_id' => 1, 'credit_card_id' => 1]);
$change = Falcon::subscriptions()->changePlan(['plan_id' => 2, 'credit_card_id' => 1]);
$cancel = Falcon::subscriptions()->cancel();
```

### API Keys

[](#api-keys)

```
$keys   = Falcon::apiKeys()->list();
$create = Falcon::apiKeys()->create(['expires_in' => 30]);
$delete = Falcon::apiKeys()->destroy(1);
```

### Sessoes de Acesso

[](#sessoes-de-acesso)

```
$recent  = Falcon::accessSessions()->recent();
$blocked = Falcon::accessSessions()->blocked();
$block   = Falcon::accessSessions()->block(['ip' => '1.2.3.4', 'reason' => 'Suspeito']);
$unblock = Falcon::accessSessions()->unblock(1);
```

### Autenticacao

[](#autenticacao)

```
$login    = Falcon::auth()->login('email@ex.com', 'senha');
$register = Falcon::auth()->register([
    'name'     => 'Nome',
    'email'    => 'email@ex.com',
    'password' => 'senha',
    'password_confirmation' => 'senha',
]);
$forgot   = Falcon::auth()->forgotPassword('email@ex.com');
```

Tratamento de Erros
-------------------

[](#tratamento-de-erros)

O SDK lanca exceptions tipadas para cada cenario:

```
use QuantumTecnology\FalconDataHub\Exceptions\AuthException;
use QuantumTecnology\FalconDataHub\Exceptions\NotFoundException;
use QuantumTecnology\FalconDataHub\Exceptions\RateLimitException;
use QuantumTecnology\FalconDataHub\Exceptions\ServerException;
use QuantumTecnology\FalconDataHub\Exceptions\TimeoutException;
use QuantumTecnology\FalconDataHub\Exceptions\ValidationException;

try {
    $result = Falcon::cnpj()->search('00000000000000');
} catch (NotFoundException $e) {
    // CNPJ nao encontrado
    echo $e->getMessage();
} catch (ValidationException $e) {
    // Dados invalidos
    print_r($e->getErrors());
} catch (RateLimitException $e) {
    // Limite de requisicoes excedido
    echo "Tente novamente em {$e->getRetryAfter()} segundos";
} catch (AuthException $e) {
    // Token invalido ou expirado
} catch (ServerException $e) {
    // Erro no servidor (5xx)
} catch (TimeoutException $e) {
    // Timeout na requisicao
}
```

Todas as exceptions extendem `FalconException` e carregam o `ApiResponse` original:

```
try {
    $result = Falcon::cep()->search('00000000');
} catch (FalconException $e) {
    $response = $e->getResponse(); // ApiResponse|null
    echo $e->getCode();            // HTTP status code
}
```

Cache de Token com PSR-16
-------------------------

[](#cache-de-token-com-psr-16)

Para persistir o token entre requisicoes (ex: Redis, arquivo):

```
// Qualquer implementacao PSR-16 (Symfony Cache, Laravel Cache, etc.)
$cache = new \Symfony\Component\Cache\Psr16Cache(
    new \Symfony\Component\Cache\Adapter\RedisAdapter($redis),
);

Falcon::configure(new FalconConfig(
    baseUrl: 'https://datahub.falcon-server.com.br',
    email: 'usuario@exemplo.com',
    password: 'senha',
    cache: $cache,
));
```

Resposta (ApiResponse)
----------------------

[](#resposta-apiresponse)

Todos os metodos retornam um `ApiResponse` com propriedades `readonly`:

```
$result = Falcon::cep()->search('13472360');

$result->success;    // bool
$result->statusCode; // int (200, 201, etc.)
$result->message;    // string
$result->data;       // array
$result->errors;     // array (vazio em sucesso)
$result->meta;       // array (paginacao quando aplicavel)

$result->toArray();  // array completo
```

Licenca
-------

[](#licenca)

MIT

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance88

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

93d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/60905574?v=4)[Luis Gustavo Santarosa Pinto](/maintainers/GustavoSantarosa)[@GustavoSantarosa](https://github.com/GustavoSantarosa)

---

Top Contributors

[![GustavoSantarosa](https://avatars.githubusercontent.com/u/60905574?v=4)](https://github.com/GustavoSantarosa "GustavoSantarosa (3 commits)")

---

Tags

apisdkcepcnpjbrasilncmdatahubfipefalcon

### Embed Badge

![Health badge](/badges/quantumtecnology-falcon-datahub-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/quantumtecnology-falcon-datahub-sdk/health.svg)](https://phpackages.com/packages/quantumtecnology-falcon-datahub-sdk)
```

###  Alternatives

[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

46784.5k5](/packages/deepseek-php-deepseek-php-client)[jhowbhz/apigratis-sdk-php

This package is free and can be used for API Brazil website functions

184.1k](/packages/jhowbhz-apigratis-sdk-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)