Aux propriétaires qui vendent en magasin et sur leur boutique DZBuild. Seul le propriétaire de la boutique peut relier une caisse ; les membres de l'équipe ne le peuvent pas.

À tous les plans. Une caisse n'est pas une clé API : elle ne demande pas de plan Enterprise et ne prend aucune place de clé.

Dès que la première caisse s'enregistre, l'extension DZBuild POS apparaît dans le tableau de bord avec les caisses reliées, un bouton de déconnexion et les dernières ventes, retours et clôtures Z. https://dzbuild.com/dashboard/connected-devices ouvre cette page.

Découverte : GET https://dzbuild.com/.well-known/oauth-authorization-server (RFC 8414).

La caisse est un client OAuth 2.0 public, dzbuild-pos-windows, sans secret. Seul PKCE S256 est accepté, et la redirection est http://127.0.0.1:PORT/oauth/callback sur n'importe quel port.

Le propriétaire se connecte dans le navigateur du système et choisit les boutiques que la caisse peut utiliser, jusqu'à 10. Une caisse peut aussi se relier avec un code : elle en affiche un, et le propriétaire le saisit sur https://dzbuild.com/device depuis un téléphone.

Le jeton d'accès commence par dzpos_ et dure 15 minutes. Le jeton de rafraîchissement est remplacé à chaque utilisation et expire après 30 jours sans usage ou 180 jours au total. Renvoyer un ancien jeton de rafraîchissement met fin à la liaison.

Chaque appel porte X-DZ-Store avec l'id de la boutique, sauf GET /v1/me. Une boutique que le propriétaire n'a pas choisie répond 403.

Chaque POST, PATCH et DELETE porte une Idempotency-Key, avec les règles de Idempotence.

Limites : 120 requêtes par minute par caisse et 600 par boutique. Le quota API mensuel ne s'applique pas aux caisses.

Déconnecter la caisse dans le tableau de bord met fin à la liaison : le rafraîchissement suivant répond 400 invalid_grant et le heartbeat suivant 410 device_revoked.

Un élément modifie le produit déjà relié à son external_id. Sinon, il reprend un produit sans variantes qui a le même sku et aucune liaison. Sinon, il crée un produit avec 0 en stock.

Une catégorie est retrouvée par son external_id, ou créée à partir de son nom.

La réponse liste chaque élément : external_id, id, status (created ou updated) et error: null. Un élément refusé porte un objet error et ni id ni status.

Plafond du plan : quand la boutique a déjà autant de produits actifs que son plan le permet, un lot qui créerait un produit, brouillon ou non, répond 402 product_limit_reached. Les éléments placés avant restent écrits. Passer un produit existant en active au-delà du plafond est une erreur sur cet élément seulement.

Le lot ne fixe jamais le stock. Le stock passe par l'appel d'ajustements.

Seuls les produits qui suivent le stock au niveau du produit peuvent être ajustés. Un produit avec un stock par variante répond l'erreur d'élément variant_product, un produit sans suivi de stock not_tracked, un produit qui n'existe plus unknown_product.

La réponse liste chaque élément par ref avec status ok ou error.

Les changements de stock de la caisse n'apparaissent jamais dans l'historique des modifications du tableau de bord et ne proposent jamais d'annulation.

Les documents sont gardés tels qu'envoyés et ne changent jamais : il n'existe aucun chemin de modification ou de suppression.

Une vente répond 201 avec {"id": 99120, "stock_applied": false}. Le stock passe par l'appel d'ajustements, jamais par un document.

Les documents POS sont séparés des commandes. Ils ne comptent pas dans la limite mensuelle de commandes de la boutique, ne notifient personne et n'atteignent jamais Google Sheets ni les webhooks.

Les montants sont des chaînes à deux décimales, les quantités des nombres à 3 décimales au plus, avec jusqu'à 500 lignes et 20 paiements par document.

Envoyer un document dont le external_id est déjà enregistré répond 409 already_exists avec l'id enregistré dans error.details.id. La caisse le lit comme un succès.

Un retour sur une vente d'une autre boutique répond 404 not_found.

GET /v1/orders?updated_since=... et GET /v1/orders/{id} donnent les commandes de la boutique au format de la caisse, avec leurs articles. order_number est le numéro court de la boutique quand il existe.

POST /v1/orders/{id}/claim avec device_id et terminal : la première caisse l'emporte. La même caisse qui la reprend reçoit 200 ; une autre caisse reçoit 409 order_claimed.

PATCH /v1/orders/{id} avec status demande la prise (409 claim_required sinon). Passages permis : de pending ou confirmed vers processing, shipped ou delivered, de processing vers shipped ou delivered, et de shipped vers delivered. Tout autre passage répond 409 transition_not_allowed.

POST /v1/orders/{id}/cancel prend reason (out_of_stock, customer_unreachable, duplicate ou other) et une note facultative de 500 caractères au plus. Le stock revient selon les règles de stock de la boutique. Si une autre caisse tient la prise, l'annulation répond 409 order_claimed.

Un changement de statut depuis la caisse déclenche les mêmes suites qu'un changement fait dans le tableau de bord, notifications et mise à jour Google Sheets comprises.

La périphérie garde l'appel jusqu'à 25 secondes et répond dès qu'un changement arrive.

Le premier appel, sans curseur, commence par un order.updated pour chaque commande pending, confirmed et processing.

Types : order.created, order.updated, product.updated, product.deleted, inventory.level_changed, customer.updated et device.revoked. Chaque événement a un id stable, ce qui permet à la caisse d'ignorer les doublons.

inventory.level_changed porte old, new, delta et une source : order quand une commande a fait bouger le stock (avec le numéro de commande), dashboard pour tout autre changement fait hors de la caisse, et pos quand une autre caisse de la même boutique l'a changé (la caisse ignore cette source).

Les écritures de produits et de stock de la caisse elle-même ne lui sont pas renvoyées.

device.revoked porte device_id en chaîne, une seule fois, après la déconnexion de la caisse.

Un curseur que cette API n'a pas émis répond 400 bad_request.