README

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

PHP 8.2+
Composer
PHP cURL extension

Installation

Install via Composer:

composer require pardalsalcap/puig-api-client

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

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

The client exposes a service-oriented architecture to keep usage simple and organized:

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

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

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

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

Most examples accept either an argument or an environment variable.

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 (GET /v1.1/products):

php examples/products/products.php

Categories (GET /v1.1/categories):

php examples/products/categories.php

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

The client automatically handles:

Initial authentication
Token refresh on 401/403
Token persistence (configurable)
Automatic retry after token expiry

Error Handling

Errors are handled consistently through exceptions:

try {
    $colors = $colorService->getAll();
} catch (\Exception $e) {
    // Errors include descriptive messages
    echo $e->getMessage();
}

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

✨ Framework-agnostic
🔒 Automatic authentication management
🏷️ Typed, immutable DTOs
🎯 Simple, clear interface
🔄 Automatic retry on token expiration
📝 Configurable logging
💾 Configurable token persistence

Development

Tests

This project uses Pest for testing:

./vendor/bin/pest

Static Analysis

Psalm is used for static analysis:

./vendor/bin/psalm

License

This project is licensed under the MIT License — see LICENSE for details.

pardalsalcap / puig-api-client

Maintainers

Details