PHPackages ometra/heimdal-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. ometra/heimdal-sdk ActiveLibrary[API Development](/categories/api) ometra/heimdal-sdk ================== Laravel SDK for consuming Heimdal API v2. v0.1.0(3w ago)09↓50%MITPHPPHP ^8.1 Since May 14Pushed 3w agoCompare [ Source](https://github.com/Ometra-Hela/mx.ometra.hela.heimdal-sdk)[ Packagist](https://packagist.org/packages/ometra/heimdal-sdk)[ RSS](/packages/ometra-heimdal-sdk/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (5)Versions (2)Used By (0) Heimdal SDK Para Laravel ======================== [](#heimdal-sdk-para-laravel) SDK Composer/Laravel para consumir Heimdal `/api/v2` desde otros modulos HELA. El paquete encapsula autenticacion bearer, `X-Correlation-ID`, envelopes normalizados, excepciones tipadas y clientes por dominio. Instalacion ----------- [](#instalacion) ``` composer require ometra/heimdal-sdk ``` Laravel descubre automaticamente el service provider y el facade. Configuracion ------------- [](#configuracion) Publica el archivo de configuracion: ``` php artisan vendor:publish --tag=heimdal-sdk-config ``` Variables disponibles: ``` HEIMDAL_SDK_BASE_URL=https://heimdal.example.test HEIMDAL_SDK_TOKEN= HEIMDAL_SDK_SOURCE_APP=auster HEIMDAL_SDK_TIMEOUT=30 HEIMDAL_SDK_RETRY_TIMES=0 HEIMDAL_SDK_RETRY_SLEEP=100 HEIMDAL_SDK_THROW=true ``` `HEIMDAL_SDK_BASE_URL` debe apuntar al host de Heimdal sin `/api`. El SDK agrega `/api/v2` automaticamente. Dos Niveles De Uso ------------------ [](#dos-niveles-de-uso) El SDK expone dos superficies: - **Raw clients**: `HeimdalSdk::subscribers()`, `HeimdalSdk::imei()`, `HeimdalSdk::batch()`, etc. Devuelven el envelope `HeimdalResponseDto` tal como lo responde Heimdal v2. - **Contracts**: `HeimdalSdk::contracts()`. Devuelven DTOs de dominio estables y son la superficie recomendada para nuevos consumidores. Uso Rapido Con Contratos ------------------------ [](#uso-rapido-con-contratos) ``` use Ometra\HeimdalSdk\Facades\HeimdalSdk; $profile = HeimdalSdk::contracts() ->subscribers() ->profile('525512345678'); $profile->subStatus; $profile->primaryOfferingId; $profile->freeUnits; ``` Uso Raw ------- [](#uso-raw) ``` use Ometra\HeimdalSdk\Facades\HeimdalSdk; $profile = HeimdalSdk::subscribers()->profile('525512345678'); if ($profile->success) { $data = $profile->data; } ``` Tambien se puede resolver desde el contenedor: ``` use Ometra\HeimdalSdk\HeimdalSdk; $sdk = app(HeimdalSdk::class); $sdk->heimdal()->imei()->status('123456789012345'); ``` Correlation ID -------------- [](#correlation-id) El SDK genera `X-Correlation-ID` automaticamente. Para usar uno propio: ``` $response = HeimdalSdk::heimdal() ->withCorrelationId('order-1001-activate') ->subscribers() ->activate('525512345678', 'OFFER-1'); ``` Para usar un token distinto en una llamada: ``` $response = HeimdalSdk::heimdal() ->withToken($token) ->monitoring() ->health(); ``` Data Objects ------------ [](#data-objects) Los payloads criticos tienen objetos tipados: ``` use Ometra\HeimdalSdk\Data\PurchaseProductData; use Ometra\HeimdalSdk\Facades\HeimdalSdk; $response = HeimdalSdk::products()->purchase( new PurchaseProductData( msisdn: '525512345678', offerings: ['OFFER-1'], scheduleDate: '2026-05-13T10:00:00', ) ); ``` Cambio de SIM: ``` use Ometra\HeimdalSdk\Data\ChangeSimData; HeimdalSdk::subscribers()->changeSim( '525512345678', new ChangeSimData('8952000000000000000') ); // Remueve el ultimo caracter, util cuando el sistema conserva ICCID completo con digito/F final. ChangeSimData::fromFullIccid('895200000000000000F'); // Envia exactamente el ICCID esperado por Altan. ChangeSimData::fromAltanIccid('8952000000000000000'); ``` Contratos Estables ------------------ [](#contratos-estables) Los contratos normalizan respuestas comunes de Altan sin perder el payload original en `raw`. ``` use Ometra\HeimdalSdk\Data\DateRangeQuery; use Ometra\HeimdalSdk\Facades\HeimdalSdk; $imei = HeimdalSdk::contracts() ->imeis() ->compatibility('12345678901234'); if ($imei->compatible) { $status = $imei->shortStatus; } $history = HeimdalSdk::contracts() ->history() ->sim('525512345678', new DateRangeQuery('2026-05-01', '2026-05-13', limit: 500)); $topup = HeimdalSdk::contracts() ->products() ->topup('525512345678', 'OFFER-1'); ``` DTOs principales: - `OperationResultDto` - `SubscriberProfileDto` - `SubscriberMsisdnChangeResultDto` - `ImeiCompatibilityDto` - `HistoryCollectionDto` - `View360SearchResultDto` - `DeviceInfoDto` - `CoverageCheckResultDto` - `NumberValidationResultDto` - `BatchSubmissionDto` - `MonitoringHealthDto` Batch Con Records ----------------- [](#batch-con-records) ``` HeimdalSdk::batch()->subscriberSuspends([ [ 'msisdn' => '525512345678', 'scheduleDate' => '2026-05-13T10:00:00', ], ]); ``` Batch Con CSV ------------- [](#batch-con-csv) ``` HeimdalSdk::batch()->subscriberBarrings(storage_path('app/barrings.csv')); ``` Tambien acepta `resource` y `Illuminate\Http\UploadedFile`. Monitoreo --------- [](#monitoreo) ``` $health = HeimdalSdk::monitoring()->health(minutes: 15); $metrics = HeimdalSdk::monitoring()->metrics(minutes: 60); $trace = HeimdalSdk::monitoring()->transaction('order-1001-activate'); ``` Manejo De Errores ----------------- [](#manejo-de-errores) Por default, el SDK lanza excepciones tipadas cuando Heimdal responde `success=false` o HTTP no exitoso: ``` use Ometra\HeimdalSdk\Exceptions\HeimdalProviderException; use Ometra\HeimdalSdk\Facades\HeimdalSdk; try { HeimdalSdk::products()->purchase($payload); } catch (HeimdalProviderException $e) { report([ 'correlation_id' => $e->correlationId, 'operation' => $e->operation, 'status' => $e->status, 'code' => $e->errorCode, ]); } ``` Excepciones disponibles: - `HeimdalRequestException` - `HeimdalValidationException` - `HeimdalUnauthorizedException` - `HeimdalForbiddenException` - `HeimdalProviderException` - `HeimdalTransportException` - `HeimdalSubscriberNotFoundException` - `HeimdalIncompatibleImeiException` Para desactivar throws en una cadena: ``` $response = HeimdalSdk::heimdal() ->withoutThrowing() ->products() ->remove($payload); if (! $response->success) { $error = $response->error; } ``` Clientes Disponibles -------------------- [](#clientes-disponibles) - `imei()` - `subscribers()` - `products()` - `orders()` - `landline()` - `view360()` - `msisdns()` - `batch()` - `monitoring()` - `validation()` - `contracts()` Cliente Raw ----------- [](#cliente-raw) Para endpoints v2 que aun no tengan helper: ``` $response = HeimdalSdk::heimdal()->post('custom/path', [ 'field' => 'value', ]); $response = HeimdalSdk::heimdal()->raw('PATCH', 'custom/path', [ 'field' => 'value', ]); ``` El cliente raw sigue usando `/api/v2`, bearer token, correlation id, normalizacion y excepciones. Migrating Auster ---------------- [](#migrating-auster) No es necesario cambiar Auster en la primera adopcion. El mapeo recomendado para reemplazar gradualmente `App\Domain\Vendor\Ometra\Hela\HeimdalAdapter` es: HeimdalAdapter actualContrato SDK recomendado`getProfile()``HeimdalSdk::contracts()->subscribers()->profile($msisdn)``topup($offerId)``HeimdalSdk::contracts()->products()->topup($msisdn, $offerId)``changeSimCard($iccid)``HeimdalSdk::contracts()->subscribers()->changeSim($msisdn, ChangeSimData::fromFullIccid($iccid))``requestNewMsisdn($zone)``HeimdalSdk::contracts()->subscribers()->changeMsisdn($msisdn, new ChangeMsisdnData($zone, '1'))``checkImei($imei)``HeimdalSdk::contracts()->imeis()->compatibility($imei)``search($type, $value)``HeimdalSdk::contracts()->view360()->search($type, $value)``simHistory(...)``HeimdalSdk::contracts()->history()->sim($msisdn, new DateRangeQuery(...))``operationHistory(...)``HeimdalSdk::contracts()->history()->operation($msisdn, new DateRangeQuery(...))`La excepcion `HeimdalSubscriberNotFoundException` reemplaza el parseo manual de `errorCode=1211000305` y mensajes `The subscriber does not exist`. Pruebas ------- [](#pruebas) ``` composer test ``` ### Health Score 36 — LowBetter than 79% of packages Maintenance94 Actively maintained with recent releases Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity32 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 26d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/984800?v=4)[gruelas](/maintainers/gruelas)[@gruelas](https://github.com/gruelas) --- Top Contributors [![gruelasjr](https://avatars.githubusercontent.com/u/40619710?v=4)](https://github.com/gruelasjr "gruelasjr (3 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ometra-heimdal-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/ometra-heimdal-sdk/health.svg)](https://phpackages.com/packages/ometra-heimdal-sdk) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[defstudio/telegraph A laravel facade to interact with Telegram Bots 815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client)[jasara/php-amzn-selling-partner-api A fluent interface for Amazon's Selling Partner API in PHP 1348.1k1](/packages/jasara-php-amzn-selling-partner-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)