> Index de la documentation : https://stilldeeppos.com/fr/llms.txt

# Bâtir un écran de caisse sur StillDeep

> Des fichiers .proto de stilldeep.v1 à une première vente : générer le client, ouvrir un quart, remplir un panier, encaisser, écouter les événements.

Source: https://stilldeeppos.com/fr/docs/creer-un-client

## Avec un agent de code

Claude Code, Codex, Cursor et les autres agents lisent cette documentation telle quelle :

- [llms.txt](/fr/llms.txt) liste chaque page en Markdown ; ajoutez `.md` à toute adresse pour sa version Markdown.
- Le serveur MCP en lecture seule, à `/mcp`, cherche et lit la documentation et le contrat (`search_docs`, `read_page`, `list_pages`, `get_contract`). Claude Code : `claude mcp add --transport http stilldeep <site>/mcp`.
- La compétence `/.well-known/agent-skills/stilldeep-pos-screen/SKILL.md` donne à l'agent les étapes ci-dessous.
- Chaque fichier `.proto` est servi en texte brut à `/contracts/<fichier>.proto`.

Décrivez votre commerce et l'écran voulu ; l'agent suit les étapes ci-dessous et le moteur vérifie chaque vente.

## Obtenir le contrat

Les fichiers `.proto` du paquet `stilldeep.v1` décrivent chaque service du poste : ventes, catalogue, membres, cartes, périphériques, événements, reçus, réservations, rendez-vous, location, inventaire, quarts et configuration. Les clients .NET utilisent le paquet `StillDeep.Intelligence.Contracts` ; les autres langages génèrent leur code à partir des mêmes fichiers.

## Générer le client

Utilisez les outils gRPC de votre langage :

- **TypeScript et Node.js :** `@grpc/grpc-js` avec `ts-proto` ou `protoc-gen-ts`.
- **Python :** `grpcio-tools`.
- **Go :** `protoc-gen-go` et `protoc-gen-go-grpc`.
- **.NET, Java, Kotlin, Rust, C++ :** les générateurs gRPC officiels.

Les guides pas à pas avec les commandes sont dans la référence : [générer un client](/fr/docs/reference/sdk), [client TypeScript](/fr/docs/reference/sdk/typescript), [client Python](/fr/docs/reference/sdk/python), [client Go](/fr/docs/reference/sdk/go).

## Se brancher au poste

Le moteur du poste écoute sur le poste lui-même (HTTP/2, port 50051 par défaut). L'écran ne parle jamais au serveur du commerce : le poste s'occupe pour lui du proxy, de la file d'envoi et du mode hors ligne.

## Faire une première vente
### Ouvrir un quart
Connectez l'employé par badge ou mot de passe et ouvrez un quart. Chaque appel suivant porte l'identifiant du quart.

### Ouvrir un panier et ajouter des articles
Ajoutez des articles par scan de code-barres ou recherche au catalogue, avec leurs quantités (décimales pour la vente au poids). Rattachez un client si la vente en exige un.

### Encaisser
Listez les modes de paiement actifs, choisissez-en un, encaissez le montant. Plusieurs paiements peuvent se partager une vente.

### Finaliser
Finalisez la vente : le moteur l'écrit localement, l'envoie par la file d'envoi et rend le reçu à imprimer.

## Gérer les refus

Chaque refus arrive en `google.rpc.Status` avec un code stable (par exemple `shift_paused` ou `stock_short`). Affichez au caissier un message tiré du code ; ne réessayez jamais à l'aveugle. Le serveur revérifie chaque vente : un refus peut arriver alors que l'écran croyait tout correct.

## Écouter les événements

Le service d'événements diffuse ce qui se passe sur le poste : disponibilité des ressources limitées, messages du chat, décisions du serveur. Un écran s'abonne une fois et se met à jour lui-même.

## Partir d'un exemple

Les clients exemples couvrent un commerce simple, une boutique, un cinéma, une billetterie, une borne libre-service, une animalerie avec toilettage, et des clients web en Node.js et en Go. Partez de celui qui ressemble le plus à votre commerce et remplacez son écran.

## Règles du contrat

- La version 1 ne reçoit jamais de changement incompatible ; une version 2 serait un paquet distinct.
- Argent en cents `int64`, pourcentages en points de base, quantités en millièmes.
- Horodatages en UTC.
- Ne croyez jamais l'écran : le moteur et le serveur valident tout, alors gardez les règles d'affaires hors du client.