Go - StockShift Developers

Il nécessite Go 1.26 ou plus récent. Il n’a aucune dépendance hors de la bibliothèque standard.

Installation

go get github.com/StockShift/go-sdk

import stockshift "github.com/StockShift/go-sdk"

Démarrage rapide

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

client := stockshift.NewClient(stockshift.WithToken(os.Getenv("STOCKSHIFT_TOKEN")))

item, err := client.Catalog.CreateItem(ctx, &stockshift.CreateItemRequest{
	SKU:       "BOLT-M4",
	Name:      "M4 hex bolt",
	Type:      stockshift.ItemTypeStocked,
	MakeOrBuy: stockshift.MakeOrBuyBuy,
})
if err != nil {
	return err
}

for row, err := range client.Inventory.ListStockOnHandAll(ctx, nil) {
	if err != nil {
		return err
	}
	fmt.Println(row.SKU, row.LocationCode, row.AvailableToPromise)
}

Authentification

Passez une clé d’API ou un jeton d’accès OAuth avec WithToken. 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 fonction avec WithTokenFunc. Le client l’appelle avant chaque requête, et une erreur qu’elle renvoie devient l’erreur de l’appel :

client := stockshift.NewClient(stockshift.WithTokenFunc(func(ctx context.Context) (string, error) {
	return tokens.Current(ctx)
}))

Autres options :

Option	Valeur par défaut	Signification
`WithBaseURL`	`https://app.stockshift.io/api/v1`	L’adresse de l’API.
`WithHTTPClient`	un `http.Client` avec un délai d’expiration de 60 secondes	Le client qui envoie les requêtes. Son `Timeout` limite chaque tentative.
`WithMaxRetries`	`2`	Nombre de nouvelles tentatives pour un appel qui peut être répété.
`WithMaxRetryAfter`	une minute	Le plus long `Retry-After` qui vaut la peine d’attendre.
`WithHeader`	aucun	Un en-tête envoyé avec chaque appel.

Un Client peut être utilisé sans risque par plusieurs goroutines. Créez-en un et partagez-le.

Faire des appels

Chaque domaine de l’API est un champ du client, comme Catalog ou Inventory, avec une méthode pour chaque opération. Chaque méthode prend d’abord un context.Context, puis les paramètres de chemin, puis le corps, puis les paramètres de requête :

item, err := client.Catalog.GetItem(ctx, "01J8QZ4M...")

page, err := client.Catalog.ListItems(ctx, &stockshift.CatalogListItemsParams{
	Search: stockshift.Ptr("bolt"),
	Status: stockshift.Ptr(stockshift.ItemStatusActive),
})

Le commentaire de documentation de chaque méthode nomme son chemin, comme GET /catalog/items/{item}. Une méthode renvoie les data de la réponse sous forme de type généré. Une réponse vide ne renvoie qu’une erreur, un export CSV ses octets et un fichier la *http.Response, dont vous devez fermer le corps. Annulez le contexte pour arrêter un appel, nouvelles tentatives et attentes comprises.

Champs facultatifs

Un paramètre de requête que vous pouvez omettre est un pointeur. stockshift.Ptr en crée un à partir d’une valeur. Un champ du corps de la requête que vous pouvez omettre est un Opt. Sa valeur zéro omet le champ, stockshift.Value(v) envoie v et stockshift.Null[T]() envoie null, ce qui efface le champ là où l’API le permet :

_, err := client.Catalog.UpdateItem(ctx, id, &stockshift.ItemFieldsRequest{
	SKU:       "BOLT-M4",
	Name:      "M4 hex bolt",
	Type:      stockshift.ItemTypeStocked,
	MakeOrBuy: stockshift.MakeOrBuyBuy,
	Brand:     stockshift.Null[string](),
})

Autres points de terminaison

client.Do appelle n’importe quel chemin et décode la réponse JSON dans une valeur que vous passez. Utilisez-le pour un point de terminaison ajouté à l’API après cette version du paquet :

var out struct {
	Data stockshift.ItemResource `json:"data"`
}
err := client.Do(ctx, http.MethodGet, "/catalog/items/"+id, nil, nil, &out)

Pagination

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

for item, err := range client.Catalog.ListItemsAll(ctx, &stockshift.CatalogListItemsParams{Search: stockshift.Ptr("bolt")}) {
	if err != nil {
		return err
	}
	fmt.Println(item.SKU)
}

Elle récupère la page suivante seulement quand la boucle en a besoin, donc un break l’arrête. Une erreur met fin à la boucle. Pour paginer vous-même, réglez After sur le NextCursor de chaque page jusqu’à ce qu’il soit nil.

Erreurs

Un appel que l’API refuse renvoie une *APIError qui contient le corps des détails du problème RFC 9457. Basez votre logique sur Code, qui est stable. Problem.Detail est rédigé pour des humains et peut changer.

_, err := client.Catalog.CreateItem(ctx, body)

var apiErr *stockshift.APIError
if errors.As(err, &apiErr) && apiErr.Code == "validation_failed" {
	fmt.Println(apiErr.Problem.Errors) // map[sku:[Another item already has the SKU BOLT-M4.]]
}

APIError a aussi StatusCode et Header. Un appel qui n’obtient aucune réponse, parce que le réseau a fait défaut ou que la tentative a expiré, renvoie une *ConnectionError qui enveloppe la cause. Quand le contexte prend fin, l’appel renvoie l’erreur du contexte.

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 WithMaxRetryAfter, il renvoie plutôt l’erreur. Un 5xx ou une défaillance réseau est réessayé pour GET, PUT et DELETE, avec un court délai 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 :

run, err := client.Integrations.PushStockNow(ctx, connectionID, stockshift.IdempotencyKey(rand.Text()))

Utilisez une nouvelle clé pour chaque modification que vous voulez faire. Les points de terminaison qui tiennent compte de la clé l’indiquent dans la référence de l’API. CallMaxRetries et CallHeader modifient un seul appel de la même façon.

Webhooks

Vérifiez l’en-tête StockShift-Signature avant de faire confiance à une livraison. WebhookVerifier.Verify a besoin du corps brut, exactement tel qu’il est arrivé :

verifier := stockshift.WebhookVerifier{Secret: os.Getenv("STOCKSHIFT_WEBHOOK_SECRET")}

http.HandleFunc("POST /webhooks/stockshift", func(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "", http.StatusBadRequest)
		return
	}
	event, err := verifier.Verify(body, r.Header.Get(stockshift.SignatureHeader))
	if err != nil {
		http.Error(w, "", http.StatusBadRequest)
		return
	}
	if event.Type == stockshift.EventInventoryStockAdjusted {
		var data stockshift.InventoryStockAdjustedData
		if err := json.Unmarshal(event.Data, &data); err != nil {
			http.Error(w, "", http.StatusBadRequest)
			return
		}
		fmt.Println(data.ItemID, data.Quantity)
	}
	w.WriteHeader(http.StatusNoContent)
})

Elle refuse une livraison de plus de cinq minutes. Réglez Tolerance pour changer ce délai. Les nouvelles tentatives d’un événement gardent son ID : conservez-le et ignorez les événements que vous avez déjà traités. Chaque type d’événement a une constante, comme EventInventoryStockAdjusted, dont le commentaire de documentation nomme le type dans lequel ses Data se décodent. Pour tester votre propre récepteur, SignWebhook signe une charge utile de la même façon que StockShift.

Versions

Le module suit la gestion sémantique de version. La version majeure change quand l’API évolue d’une façon qui peut briser votre code, comme un champ retiré ou un nouveau paramètre obligatoire. En Go, une nouvelle version majeure change aussi le chemin d’importation, par exemple github.com/StockShift/go-sdk/v2. Les nouveaux points de terminaison et champs arrivent dans des versions mineures. APIVersion contient la version de la référence de l’API à partir de laquelle le module a été construit. Les deux versions les plus récentes de Go sont prises en charge, comme le fait l’équipe Go.

SDK

Cadriciels

Go

Installation

Démarrage rapide

Authentification

Faire des appels

Champs facultatifs

Autres points de terminaison

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions

​Installation

​Démarrage rapide

​Authentification

​Faire des appels

​Champs facultatifs

​Autres points de terminaison

​Pagination

​Erreurs

​Nouvelles tentatives et clés d’idempotence

​Webhooks

​Versions

Installation

Démarrage rapide

Authentification

Faire des appels

Champs facultatifs

Autres points de terminaison

Pagination

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions