redrodrigo/ixc-sdk

SDK PHP não-oficial para a API REST do IXC Soft, com adapter opcional para Laravel.

v0.1.0 2026-07-10 15:51 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.8
• psr/simple-cache: ^2.0|^3.0

Requires (Dev)

• illuminate/support: ^10.0|^11.0|^12.0
• phpunit/phpunit: ^10.5

Suggests

• illuminate/support: Necessário para usar o adapter Laravel (RedRodrigo\IxcSdk\Laravel\IxcServiceProvider).

MIT

• Rodrigo Castro

• sdk
• API-Client
• isp
• ixc
• ixcsoft

Published on Packagist.org on 2026-07-10 15:53 UTC

README

SDK PHP não-oficial para a API REST do IXC Soft (ERP de provedores de internet).

Núcleo sem dependência de framework (guzzlehttp/guzzle + psr/simple-cache apenas), com um adapter opcional para Laravel.

Instalação

Disponível no Packagist — instale via Composer:

composer require redrodrigo/ixc-sdk

Uso standalone (fora do Laravel)

use RedRodrigo\IxcSdk\IxcClient;

$ixc = IxcClient::make(
    baseUrl: 'https://central.suaoperadora.com.br/webservice/v1',
    userId: '129',
    token: 'seu-token-de-api',
);

$clientes = $ixc->cliente()->searchCliente('João');
$contratos = $ixc->cliente()->getInfoContrato(10827);
$vendedor = $ixc->comercial()->getVendedorById('5');
$os = $ixc->os()->getOsAbertasByTecnico('15');

Uso no Laravel

O provider é descoberto automaticamente via composer.json extra.laravel.providers.

1. Publique o config (opcional):

   php artisan vendor:publish --tag=ixc-config

2. Configure o .env:

   IXC_BASE_URL=https://central.suaoperadora.com.br/webservice/v1
   IXC_USER_ID=129
   IXC_API_TOKEN=seu-token-de-api
   
   # Opcional — cacheia respostas via o cache store padrão do Laravel
   IXC_CACHE_ENABLED=false
   IXC_CACHE_STORE=
   IXC_CACHE_TTL=300

3. Injete RedRodrigo\IxcSdk\IxcClient (singleton) onde precisar:

   use RedRodrigo\IxcSdk\IxcClient;
   
   class ClienteController
   {
       public function __construct(private IxcClient $ixc) {}
   
       public function show(string $termo)
       {
           return $this->ixc->cliente()->searchCliente($termo);
       }
   }

   Ou injete um resource específico diretamente (também resolvido pelo container):

   use RedRodrigo\IxcSdk\Resources\ComercialResource;
   
   public function __construct(private ComercialResource $comercial) {}

Resources disponíveis

Resource	Domínio	Endpoints IXC
cliente()	Clientes, contratos, login PPPoE	/cliente, /cliente_contrato, /radusuarios
comercial()	Contratos por período, vendedores, equipes, OS por tipo	/cliente_contrato, /vd_contratos, /vendedor, /usuarios, /su_oss_chamado
contrato()	Planos de venda, TV	/vd_contratos, /tv_usuarios
estoque()	Almoxarifado, saldo, produtos	/almox_usuario, /view_prod_estoque_almox, /produtos
financeiro()	Pagamentos, faturas, desbloqueio de confiança	/fn_areceber, /desbloqueio_confianca
os()	Ordens de serviço, assuntos, diagnósticos, materiais	/su_oss_chamado, /su_oss_assunto, /su_diagnostico, /movimento_produtos, /produtos, /radpop_radio
veiculo()	Frota e despesas	/veiculos, /veiculos_despesas

Cada método é documentado com PHPDoc (campos relevantes de retorno, exemplo de uso) diretamente na classe do resource correspondente em src/Resources/.

QueryBuilder

Todos os resources usam RedRodrigo\IxcSdk\Query\QueryBuilder internamente para montar o protocolo de listagem do IXC (qtype/query/oper/page/rp/sortname/sortorder/grid_param). Ele também está disponível publicamente para consultas ad-hoc:

use RedRodrigo\IxcSdk\Query\QueryBuilder;

$query = QueryBuilder::for('cliente_contrato.id_vendedor')
    ->perPage(400)
    ->filter('cliente_contrato.status', '=', 'A')
    ->filter('cliente_contrato.data_ativacao', '>=', '2024-07-01')
    ->filter('cliente_contrato.data_ativacao', '<=', '2024-07-31')
    ->toArray();

Cache

O núcleo não depende de nenhum cache específico. RedRodrigo\IxcSdk\Http\CachingHttpClient é um decorator PSR-16 que pode envolver qualquer HttpClientInterface:

use RedRodrigo\IxcSdk\Http\CachingHttpClient;
use RedRodrigo\IxcSdk\Http\GuzzleHttpClient;
use RedRodrigo\IxcSdk\IxcClient;

$http = new CachingHttpClient(
    inner: new GuzzleHttpClient($baseUrl, $userId, $token),
    cache: $psr16Cache, // qualquer implementação de Psr\SimpleCache\CacheInterface
    ttl: 300,
);

$ixc = new IxcClient($http);

No Laravel, isso é habilitado automaticamente via IXC_CACHE_ENABLED=true (usa Cache::store(), que já implementa PSR-16).

Erros

Toda falha de transporte (timeout, DNS, HTTP de erro) lança RedRodrigo\IxcSdk\Exceptions\IxcRequestException. Uma resposta com corpo que não é JSON válido lança IxcResponseException. Ambas estendem IxcException — capture essa classe se quiser tratar qualquer erro da SDK de forma genérica.

use RedRodrigo\IxcSdk\Exceptions\IxcException;

try {
    $ixc->cliente()->searchCliente('123');
} catch (IxcException $e) {
    // logar, notificar, etc.
}

Decisões de design

• Sem swallow de erros: falhas de transporte e respostas inválidas lançam exceptions tipadas (IxcRequestException, IxcResponseException) em vez de retornar []/null silenciosamente. Quem chama decide como tratar.
• Cache centralizado: em vez de cada método decidir se e como cachear (TTLs diferentes, chaves manuais), o cache é um único decorator plugável (CachingHttpClient) que pode envolver qualquer implementação de HttpClientInterface.
• JSON-decode centralizado: a decodificação da resposta HTTP acontece em um único lugar (GuzzleHttpClient::get()), não repetida em cada método de resource.
• Retornos pragmáticos por padrão: cada método de resource retorna o formato mais natural para aquele endpoint (array, lista, só o primeiro registro, ou a estrutura bruta {total, registros} do IXC) em vez de forçar um único formato genérico. Para um formato normalizado e tipado, use RedRodrigo\IxcSdk\Support\ListResponse (usado internamente, também exposto publicamente).

Testes

composer install
vendor/bin/phpunit