PHPackages pardalsalcap/puig-api-client - 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. pardalsalcap/puig-api-client ActiveLibrary[API Development](/categories/api) pardalsalcap/puig-api-client ============================ A PHP client library for the PuigTechParts API v1.1.1(3mo ago)05MITPHPPHP ^8.2 Since Dec 17Pushed 3mo agoCompare [ Source](https://github.com/Anfibic/puig-api-client)[ Packagist](https://packagist.org/packages/pardalsalcap/puig-api-client)[ RSS](/packages/pardalsalcap-puig-api-client/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (13)Versions (3)Used By (0) Puig API Client =============== [](#puig-api-client) Framework-agnostic PHP client for the PuigTechParts API. This library provides a clean, typed interface to interact with the API endpoints, making it easy to access bikes, products, references, colors and business data. Private API (Motoplastic, S.A. customers only) This API is private and is available exclusively to Motoplastic, S.A. customers. If you need access, please contact your account manager to request activation. *Support* Puig does not provide support for this API client. This repository/client is provided only as a testing example for integration and validation purposes. Requirements ------------ [](#requirements) - PHP 8.2+ - Composer - PHP cURL extension Installation ------------ [](#installation) Install via Composer: ``` composer require pardalsalcap/puig-api-client ``` Configuration ------------- [](#configuration) This library reads configuration from the environment, but it does not auto-load `.env` files. Choose one of the following: - Env-based (recommended): Ensure your app loads environment variables (via your framework or `vlucas/phpdotenv`), then instantiate `new PuigApiClient()` or use `PuigApiClient::fromEnv()`. - Explicit setters: Instantiate the client and set configuration via setters (`setUsername`, `setPassword`, `setBaseUrl`, `setLanguage`) and optional token storage. Environment variables: - **Credentials**: `API_USERNAME`, `API_PASSWORD`. - **Locale/host**: `API_LANGUAGE` (default `es`), `API_BASE_URL` (default `https://api.puighitechparts.es`). - **Token management**: - `API_PERSIST_TOKEN` enables disk persistence using Symfony Cache (boolean-like values supported). - `API_TOKEN_CACHE_DIR` customizes the cache folder (default `var/cache`). - `API_TOKEN` seeds an in-memory token (no disk writes). - **Debugging**: `API_DEBUG=1` prints debug output. Example `.env` snippet: ``` API_USERNAME=your-user API_PASSWORD=your-password API_LANGUAGE=en API_PERSIST_TOKEN=0 API_TOKEN_CACHE_DIR=var/cache API_DEBUG=0 ``` Laravel/Symfony: These frameworks already load environment variables by default — just configure your `.env` and do `new PuigApiClient()` or `PuigApiClient::fromEnv()`. Plain PHP with `vlucas/phpdotenv`: ``` use Dotenv\Dotenv; use Pardalsalcap\PuigApiClient\PuigApiClient; require __DIR__.'/vendor/autoload.php'; Dotenv::createImmutable(__DIR__)->safeLoad(); $client = PuigApiClient::fromEnv(); ``` Basic Usage ----------- [](#basic-usage) ### Initialization [](#initialization) The client aims to be as simple as possible to use: ``` use Pardalsalcap\PuigApiClient\PuigApiClient; $client = new PuigApiClient(); // Provide credentials via env vars or setters $client->setUsername('your-user'); $client->setPassword('your-password'); // Optional: override language or base URL $client->setLanguage('en'); // Authenticate (uses the stored credentials) $client->login(); ``` ### Available Services [](#available-services) The client exposes a service-oriented architecture to keep usage simple and organized: #### ColorService [](#colorservice) ``` use Pardalsalcap\PuigApiClient\Service\Articles\ColorService; $colorService = new ColorService($client); // Fetch all colors $colors = $colorService->getAll(); foreach ($colors as $color) { echo $color->code . ': ' . $color->description; } ``` #### Summary of Services [](#summary-of-services) - Bikes (`Pardalsalcap\PuigApiClient\Service\Bikes`): - `BikesService`: List `/bikes`, search `/bikes/search` (GET), detail `/bikes/{id}`. - `BrandsService`: List brands `/bikes/brands`. - `ModelsService`: Models by brand via `getByCode(brandId)` → `/bikes/brands/{brandId}`. - `BikeArticlesService`: Compatible references for a bike `/v1.1/bikes/{id}/references`. - `BikeMultimediaService`: Multimedia for a bike `/v1.1/bikes/{id}/multimedia`. - Products (`Pardalsalcap\PuigApiClient\Service\Products`): - `CategoriesService`: List categories `/v1.1/categories`. - `ProductService`: List `/v1.1/products`; per product: `references`, `multimedia`, `bikes`. - Articles (`Pardalsalcap\PuigApiClient\Service\Articles`): - `ReferenceService`: List/search references. - `StockService`: Quick stock `/references/stock/quick` (GET; supports query + JSON body for codes). - `ColorService`: List colors `/colors`. - `ReferencesUpdatedService`: Updated references `/references/updated` (paginated). - `ReferenceBikesService`: Bikes by reference `/references/{code}/bikes`. - `ReferenceMultimediaService`: Multimedia by reference `/references/{code}/multimedia`. - Business (`Pardalsalcap\PuigApiClient\Service\Business`): - `BillsService`: List bills `/bills` (paginated) and download bill PDF `/bills/{id}.pdf`. - `OrdersService`: List orders `/orders` (paginated), order detail `/orders/{id}`, download order PDF `/orders/{id}.pdf`. - `PendingArticlesService`: List pending articles `/pending-articles` (paginated). - `ProformasService`: List proformas `/proformas` (paginated) and download proforma PDF `/proformas/{id}.pdf`. - `ShipmentsService`: List shipments `/shipments` (paginated), shipment detail `/shipments/{id}`, download shipment PDF `/shipments/{id}.pdf`. - `TransportAgenciesService`: List available transport agencies `/transport-agencies`. `getByCode()` is not supported (returns null); use `findByCode()` helper to match a single code from the list. Examples -------- [](#examples) Practical scripts that demonstrate how to use each service of the PuigTechParts API client can be found in the `examples/` directory. Examples load `.env` via a lightweight `_bootstrap.php` so they work both inside this repo and when copied into another project. Note: If you copy these scripts to your project, ensure your `.env` lives at your project root or export the variables in your shell before running them. ### Quick Index [](#quick-index) - **Bikes**: - List bikes: `examples/bikes/bikes.php` - Search bikes: `examples/bikes/search.php` - Bike brands: `examples/bikes/brands.php` - Models by brand: `examples/bikes/models.php` - Bike references: `examples/bikes/references.php` - Bike multimedia: `examples/bikes/multimedia.php` - **Products**: - Categories: `examples/products/categories.php` - Products: `examples/products/products.php` - Product references: `examples/products/product_references.php` - Product multimedia: `examples/products/product_multimedia.php` - Product bikes: `examples/products/product_bikes.php` - **References & Articles**: - Colors: `examples/articles/colors.php` - Quick Stock: `examples/articles/stock.php` - Updated references: `examples/articles/references_updated.php` - Bikes by reference: `examples/articles/reference_bikes.php` - Multimedia by reference: `examples/articles/reference_multimedia.php` - **Business**: - Bills: `examples/business/bills.php` - Bill PDF: `examples/business/bill_pdf.php` - Orders: `examples/business/orders.php` - Order detail: `examples/business/order_detail.php` - Order PDF: `examples/business/order_pdf.php` - Current order: `examples/business/order_current.php` - Add to order: `examples/business/order_add.php` - Delete order line: `examples/business/order_delete_line.php` - Empty order: `examples/business/order_empty.php` - Send order: `examples/business/order_send.php` - Pending articles: `examples/business/pending_articles.php` - Proformas: `examples/business/proformas.php` - Proforma PDF: `examples/business/proforma_pdf.php` - Shipments: `examples/business/shipments.php` - Shipment detail: `examples/business/shipment_detail.php` - Shipment PDF: `examples/business/shipment_pdf.php` - Transport agencies: `examples/business/transport_agencies.php` ### Usage Details [](#usage-details) Most examples accept either an argument or an environment variable. #### Bikes [](#bikes) **List bikes:** ``` php examples/bikes/bikes.php ``` **Search bikes:** ``` php examples/bikes/search.php "MT-09" ``` **Bike references** (GET /v1.1/bikes/{id}/references): ``` # Using argument php examples/bikes/references.php 11405 # Or using env var export BIKES_BIKE_ID=11405 php examples/bikes/references.php ``` #### Products [](#products) **Products** (GET /v1.1/products): ``` php examples/products/products.php ``` **Categories** (GET /v1.1/categories): ``` php examples/products/categories.php ``` #### Business [](#business) **Orders list** (GET /orders): ``` php examples/business/orders.php php examples/business/orders.php 2 # Specific page ``` **Order PDF** (GET /orders/{id}.pdf): ``` php examples/business/order_pdf.php 20162327 ``` Token Management ---------------- [](#token-management) The client automatically handles: - Initial authentication - Token refresh on 401/403 - Token persistence (configurable) - Automatic retry after token expiry Error Handling -------------- [](#error-handling) Errors are handled consistently through exceptions: ``` try { $colors = $colorService->getAll(); } catch (\Exception $e) { // Errors include descriptive messages echo $e->getMessage(); } ``` DTOs ---- [](#dtos) Data is returned as immutable, strongly typed objects. DTOs are updated to match the latest API response structures (e.g., `Product` includes `zones` and `functionalities`). ``` // Example with the Color DTO $color = Color::fromArray([ 'code' => 'BK', 'description' => 'Black' ]); echo $color->code; // 'BK' echo $color->description; // 'Black' // Convert back to array for serialization $data = $color->toArray(); ``` Features -------- [](#features) - ✨ Framework-agnostic - 🔒 Automatic authentication management - 🏷️ Typed, immutable DTOs - 🎯 Simple, clear interface - 🔄 Automatic retry on token expiration - 📝 Configurable logging - 💾 Configurable token persistence Development ----------- [](#development) ### Tests [](#tests) This project uses Pest for testing: ``` ./vendor/bin/pest ``` ### Static Analysis [](#static-analysis) Psalm is used for static analysis: ``` ./vendor/bin/psalm ``` License ------- [](#license) This project is licensed under the MIT License — see [LICENSE](LICENSE) for details. ### Health Score 36 — LowBetter than 82% of packages Maintenance78 Regular maintenance activity Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record 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 Every ~29 days Total 2 Last Release 114d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/73c7deb72893167ce8d32a4a7f56fa960d1d329d6f3f057197d5e9d91d65de8a?d=identicon)[pardalsalcap](/maintainers/pardalsalcap) --- Top Contributors [![pardalsalcap](https://avatars.githubusercontent.com/u/264531?v=4)](https://github.com/pardalsalcap "pardalsalcap (35 commits)") ### Code Quality TestsPest Static AnalysisPsalm Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/pardalsalcap-puig-api-client/health.svg) ``` [![Health](https://phpackages.com/badges/pardalsalcap-puig-api-client/health.svg)](https://phpackages.com/packages/pardalsalcap-puig-api-client) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M648](/packages/sylius-sylius)[craftcms/cms Craft CMS 3.6k3.6M2.6k](/packages/craftcms-cms)[shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.0k15.4k](/packages/prestashop-prestashop)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[ec-cube/ec-cube EC-CUBE EC open platform. 78527.0k1](/packages/ec-cube-ec-cube) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)