PHP

Il exige PHP 8.2 ou une version ultérieure et n’importe quel client HTTP PSR-18.

Installation

composer require stockshift/sdk-php

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

composer require guzzlehttp/guzzle

Démarrage rapide

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

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 :

$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.

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 :

$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 :

$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 :

/** @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 :

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.

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 :

$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é :

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.

SDK

Cadriciels

Installation

Démarrage rapide

Authentification

Faire des appels

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions

​Installation

​Démarrage rapide

​Authentification

​Faire des appels

​Pagination

​Erreurs

​Nouvelles tentatives et clés d’idempotence

​Webhooks

​Versions

Installation

Démarrage rapide

Authentification

Faire des appels

Pagination

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions