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

The client auto-loads a .env file (if present) and reads configuration from environment variables, or you can call the corresponding setters on PuigApiClient.

Credentials: API_USERNAME and API_PASSWORD (or use setUsername() / setPassword()).
Locale / host: API_LANGUAGE (default es) and API_BASE_URL (default https://api.puighitechparts.es).
Token management:
- API_PERSIST_TOKEN=1 enables disk persistence using Symfony Cache. Accepts typical boolean values (1/true/on/yes to enable; 0/false/off/no to disable).
- API_TOKEN_CACHE_DIR customizes the cache folder (defaults to var/cache).
- API_TOKEN seeds the runtime token without touching disk.
Debugging: API_DEBUG=1 makes the client log HTTP requests/responses.

Example .env snippet:

API_USERNAME=your-user
API_PASSWORD=your-password
API_LANGUAGE=en
API_PERSIST_TOKEN=1
API_TOKEN_CACHE_DIR=/path/to/cache
API_DEBUG=1

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.

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