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

# Go

> Un client Go pour l'API StockShift. Il a une méthode pour chaque opération de la référence de l'API et un type Go pour chaque requête et réponse, le tout généré à partir du document OpenAPI de l'API.

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

## Installation

```bash theme={null}
go get github.com/StockShift/go-sdk
```

```go theme={null}
import stockshift "github.com/StockShift/go-sdk"
```

## Démarrage rapide

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

```go theme={null}
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 :

```go theme={null}
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 :

```go theme={null}
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 :

```go theme={null}
_, 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 :

```go theme={null}
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 :

```go theme={null}
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.

```go theme={null}
_, 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 :

```go theme={null}
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é :

```go theme={null}
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.


## Related topics

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