> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockshift.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

> Un client PHP pour l'API StockShift. Il a une méthode pour chaque opération de la référence de l'API, générée à partir du document OpenAPI de l'API, avec des types PHPStan pour chaque requête et chaque réponse.

Il exige PHP 8.2 ou une version ultérieure et n'importe quel client HTTP [PSR-18](https://www.php-fig.org/psr/psr-18/).

## Installation

```bash theme={null}
composer require stockshift/sdk-php
```

Si votre projet n'a pas encore de client PSR-18, ajoutez-en un, comme Guzzle :

```bash theme={null}
composer require guzzlehttp/guzzle
```

## Démarrage rapide

Créez un article, puis listez le stock en main :

```php theme={null}
use StockShift\Sdk\StockShift;

$stockshift = new StockShift(getenv('STOCKSHIFT_TOKEN'));

$stockshift->catalog()->createItem(['sku' => 'BOLT-M4', 'name' => 'M4 hex bolt', 'type' => 'stocked', 'make_or_buy' => 'buy']);

foreach ($stockshift->inventory()->listStockOnHandAll() as $row) {
    echo $row['sku'], ' ', $row['location_code'], ' ', $row['available_to_promise'], "\n";
}
```

## Authentification

Passez une clé d'API ou un jeton d'accès OAuth comme premier argument. Créez une clé d'API dans l'application sous Paramètres > Accès > Clés d'API. La clé agit au nom du membre qui l'a créée, et un appel exige à la fois l'autorisation du membre et l'une des portées de la clé.

Pour un jeton OAuth qui expire, passez une fermeture (closure). Le client l'appelle avant chaque requête :

```php theme={null}
$stockshift = new StockShift(fn (): string => $tokens->current());
```

Autres arguments, tous nommés :

| Argument | Valeur par défaut | Signification |
| - | - | - |
| `baseUrl` | `https://app.stockshift.io/api/v1` | L'adresse de l'API. |
| `maxRetries` | `2` | Nombre de nouvelles tentatives pour un appel qui peut être répété. |
| `maxRetryAfter` | `60` | Le plus long `Retry-After`, en secondes, qui vaut la peine d'attendre. |
| `headers` | aucun | En-têtes envoyés avec chaque appel. |
| `httpClient` | trouvé pour vous | Le client PSR-18. Définissez-y les délais d'expiration. |
| `requestFactory`, `streamFactory` | trouvées pour vous | Fabriques PSR-17. |

Si vous les omettez, le client et les fabriques sont trouvés avec [php-http/discovery](https://github.com/php-http/discovery).

## Faire des appels

Chaque domaine de l'API a une méthode, comme `catalog()` ou `inventory()`, et chaque opération a une méthode sur celle-ci. Les paramètres de chemin viennent d'abord, puis le corps, puis la chaîne de requête :

```php theme={null}
$item = $stockshift->catalog()->getItem('01J8QZ4M...');
echo $item['data']['sku'];

$page = $stockshift->catalog()->listItems(['search' => 'bolt', 'status' => 'active']);
```

Le commentaire de documentation de chaque méthode nomme son chemin, comme `GET /catalog/items/{item}`. Vous pouvez aussi appeler un chemin directement :

```php theme={null}
$item = $stockshift->get('/catalog/items/{item}', ['path' => ['item' => '01J8QZ4M...']]);
```

Un appel renvoie le corps JSON décodé sous forme de tableau. Une réponse vide renvoie `null`, une exportation CSV son texte et un fichier la réponse PSR-7.

Pour vérifier votre propre code par rapport aux types, importez-les depuis `Schemas` dans un commentaire de documentation PHPStan :

```php theme={null}
/** @phpstan-import-type ItemResource from \StockShift\Sdk\Generated\Schemas */
```

## Pagination

Une liste qui peut grandir renvoie une page à la fois. Chaque liste paginée a une deuxième méthode qui se termine par `All`, qui suit les curseurs et produit chaque enregistrement :

```php theme={null}
foreach ($stockshift->catalog()->listItemsAll(['search' => 'bolt']) as $item) {
    echo $item['sku'], "\n";
}
```

`$stockshift->paginate('/catalog/items')` fait la même chose à partir d'un chemin. Pour paginer à la main, renvoyez le `next_cursor` de chaque page dans le paramètre de requête `after` jusqu'à ce qu'il soit `null`.

## Erreurs

Un appel qui échoue lève une `ApiException` qui contient le corps des détails du problème RFC 9457. Basez votre logique sur `errorCode`, qui est stable. Le détail est rédigé pour des personnes et peut changer.

```php theme={null}
use StockShift\Sdk\Exception\ApiException;

try {
    $stockshift->catalog()->createItem($item);
} catch (ApiException $error) {
    if ($error->errorCode === 'validation_failed') {
        print_r($error->errors()); // ['sku' => ['Another item already has the SKU BOLT-M4.']]
    }
}
```

`ApiException` a aussi `status`, `problem` et `response`. Un appel qui ne reçoit aucune réponse, parce que le réseau a échoué, lève une `ConnectionException`. Les deux étendent `StockShiftException`.

## Nouvelles tentatives et clés d'idempotence

Le client réessaie un `429` après le délai indiqué dans `Retry-After`. Il le fait pour toutes les méthodes, parce que l'API n'a pas exécuté l'appel. Si `Retry-After` dépasse `maxRetryAfter`, il lève plutôt une exception.

Un `5xx` ou une défaillance réseau est réessayé pour `GET`, `PUT` et `DELETE`, avec un court délai d'attente progressif. Un `POST` ou un `PATCH` n'est réessayé que si vous lui donnez une clé d'idempotence, pour qu'une nouvelle tentative ne puisse pas appliquer la modification deux fois :

```php theme={null}
$stockshift->integrations()->pushStockNow($connectionId, ['idempotencyKey' => bin2hex(random_bytes(16))]);
```

Utilisez une nouvelle clé pour chaque modification que vous voulez faire. Les points de terminaison qui respectent la clé l'indiquent dans la référence de l'API.

## Webhooks

Vérifiez l'en-tête `StockShift-Signature` avant de faire confiance à une livraison. `Webhook::verify()` a besoin du corps brut, exactement tel qu'il est arrivé :

```php theme={null}
use StockShift\Sdk\Exception\WebhookVerificationException;
use StockShift\Sdk\Webhook;

try {
    $event = Webhook::verify(
        file_get_contents('php://input'),
        $_SERVER['HTTP_STOCKSHIFT_SIGNATURE'] ?? null,
        getenv('STOCKSHIFT_WEBHOOK_SECRET'),
    );
} catch (WebhookVerificationException) {
    http_response_code(400);
    exit;
}

if ($event['type'] === 'inventory.stock.adjusted') {
    echo $event['data']['item_id'], ' ', $event['data']['quantity'], "\n";
}
http_response_code(204);
```

Elle refuse une livraison de plus de cinq minutes. Passez `tolerance`, en secondes, pour changer ce délai. Les nouvelles tentatives d'un événement gardent son `id` : conservez-le et ignorez les événements déjà traités.

Chaque événement a un type PHPStan dans `Schemas`, comme `InventoryStockAdjustedEvent`. Pour tester votre propre récepteur, `Webhook::sign()` signe une charge utile de la même façon que StockShift.

## Versions

La version majeure change quand l'API change d'une façon qui peut briser votre code, comme un champ retiré ou un nouveau paramètre obligatoire. Les nouveaux points de terminaison et champs arrivent dans des versions mineures. `StockShift\Sdk\Generated\Api::VERSION` contient la version de la référence de l'API à partir de laquelle le paquet a été construit.


## Related topics

- [Laravel](https://docs.stockshift.io/fr-ca/sdks/laravel.md)
- [SDK](https://docs.stockshift.io/fr-ca/sdks/index.md)
- [StockShift pour les développeurs](https://docs.stockshift.io/fr-ca/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.