Votre agent. Vos boutiques. Vos règles.

Consultez et gérez vos données avec les permissions accordées par le propriétaire. Gardez le contrôle sur chaque boutique et chaque opération.

API et agents IA

Connecter un agent par OAuth

Dans votre agent compatible MCP HTTP et OAuth, renseignez https://api.suite241.com/mcp/commerce.
Connectez-vous à Commerce avec le compte propriétaire.
Vérifiez le nom de l’application et son adresse de retour. Sélectionnez les boutiques et les opérations autorisées.
Confirmez. L’agent reçoit son propre accès, révocable depuis Commerce.

OAuth utilise un code à usage unique, PKCE S256 et la ressource canonique du serveur MCP. Les jetons d’accès durent une heure. Les jetons de renouvellement sont renouvelés avec rotation. Les clés API et jetons de connexion Commerce ne sont pas utilisables pour cette connexion.

Découverte : /.well-known/oauth-authorization-server et /.well-known/oauth-protected-resource/mcp/commerce. L’enregistrement préalable ou dynamique du client utilise POST /oauth/register avec client_name et redirect_uris. Une adresse HTTPS exacte est requise ; HTTP est accepté pour une boucle locale.

Le consentement doit être effectué dans le navigateur qui a commencé la connexion. Commerce et l’API doivent être servis sur le même site (par exemple app.suite241.com et api.suite241.com). Chaque outil correspond à une opération ci-dessous ; le point devient __, par exemple products__list. Les arguments sont shop_id, éventuellement resource_id, input et, pour une écriture, idempotency_key.

Choisissez précisément les accès

Chaque opération possède sa permission. Autoriser une lecture n’autorise aucune écriture. Choisir « Toutes les boutiques » inclut les nouvelles boutiques ; une sélection fixe n’en inclut aucune automatiquement.

Les transferts exigent l’accès aux deux boutiques. Les modules, quotas, règles de stock et restrictions d’abonnement restent applicables. La révocation est immédiate ; un transfert de propriété révoque les autorisations de l’ancien propriétaire.

Les utilisateurs, les permissions, les abonnements et les secrets techniques ne sont pas exposés. Aucune suppression n’est disponible.

Des écritures maîtrisées

Fournissez Idempotency-Key pour chaque écriture : réutilisez la même clé avec le même contenu après une interruption. Un autre contenu avec cette clé reçoit une erreur 409.

curl -X POST 'https://api.suite241.com/api/external/v1/shops/1/clients' \
  -H 'Authorization: Bearer VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: creation-client-001' \
  -d '{"name":"Client exemple","email":"client@example.test"}'

Les paiements, remboursements et mouvements de portefeuille répondent 202 — en attente. Une personne autorisée doit ouvrir « Demandes des intégrations » dans Commerce, vérifier le contenu puis accepter ou refuser. La demande ne vaut pas preuve de paiement. Les droits, stocks, montants et sessions de caisse sont revérifiés à la validation.

Vous pouvez consulter l’état de vos demandes via GET /shops/{shop}/requests, avec la permission correspondante.

Pagination, limites et erreurs

Les listes acceptent search, page, per_page, updated_since, date_from et date_to. Le tri utilise l’identifiant décroissant. La pagination retourne 20 lignes par défaut et au maximum 100.

Limites initiales : 60 lectures et 10 écritures par minute et par accès. Une tentative refusée ne doit pas être répétée sans attendre ou corriger sa cause.

401: Accès invalide, expiré ou révoqué.
403 / 404: Permission refusée ou ressource inaccessible dans ce périmètre.
409: Conflit d’état ou d’idempotence ; vérifiez la demande.
422: Champs invalides, indiqués dans errors.
429: Limite atteinte ; réessayez après une minute.

Opérations disponibles

Les noms ci-dessous sont les permissions à accorder. Les champs non documentés sont refusés.

products 8 opérations

`products.list`

GET /shops/{shop}/products

Champs retournés : id, shop_id, name, sku, barcode, description, category_id, rayon_id, purchase_price, sale_price, stock_quantity, min_stock_quantity, is_active, product_type, created_at, updated_at

`products.get`

GET /shops/{shop}/products/{id}

`products.create`

POST /shops/{shop}/products

Champs acceptés : name, sku, barcode, description, category_id, rayon_id, purchase_price, sale_price, min_stock_quantity, is_tva_applicable, is_css_applicable

Champs obligatoires : name, sku, purchase_price, sale_price. La spécification OpenAPI décrit aussi les lignes items.

`products.update`

PATCH /shops/{shop}/products/{id}

Champs acceptés : name, sku, barcode, description, category_id, rayon_id, purchase_price, sale_price, min_stock_quantity, is_tva_applicable, is_css_applicable

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`categories.list`

GET /shops/{shop}/categories

Champs retournés : id, shop_id, name, code, type, global_key, is_active, created_at, updated_at

`categories.get`

GET /shops/{shop}/categories/{id}

Champs retournés : id, shop_id, name, code, type, global_key, is_active, created_at, updated_at

`categories.create`

POST /shops/{shop}/categories

Champs acceptés : name, code, description, position

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

`categories.update`

PATCH /shops/{shop}/categories/{id}

Champs acceptés : name, code, is_active, description, position

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

clients 5 opérations

`clients.list`

GET /shops/{shop}/clients

Champs retournés : id, shop_id, name, phone, email, city, address, notes, debt_limit, current_debt, available_credit, created_at, updated_at

`clients.get`

GET /shops/{shop}/clients/{id}

Champs retournés : id, shop_id, name, phone, email, city, address, notes, debt_limit, current_debt, available_credit, created_at, updated_at

`clients.create`

POST /shops/{shop}/clients

Champs acceptés : name, phone, whatsapp_phone, email, city, address, notes, debt_limit

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

`clients.update`

PATCH /shops/{shop}/clients/{id}

Champs acceptés : name, phone, whatsapp_phone, email, city, address, notes, debt_limit

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

`clients.payment`

POST /shops/{shop}/clients/{id}/payment

Validation humaine requise — réponse 202.

Champs acceptés : amount, payment_date, method, reference, notes, sale_id

Champs obligatoires : amount. La spécification OpenAPI décrit aussi les lignes items.

suppliers 4 opérations

`suppliers.list`

GET /shops/{shop}/suppliers

Champs retournés : id, shop_id, name, contact_name, phone, email, address, city, is_active, type, created_at, updated_at

`suppliers.get`

GET /shops/{shop}/suppliers/{id}

Champs retournés : id, shop_id, name, contact_name, phone, email, address, city, is_active, type, created_at, updated_at

`suppliers.create`

POST /shops/{shop}/suppliers

Champs acceptés : name, contact_name, phone, email, address, city, notes, tax_number

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

`suppliers.update`

PATCH /shops/{shop}/suppliers/{id}

Champs acceptés : name, contact_name, phone, email, address, is_active, city, notes, tax_number

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

purchases 6 opérations

`purchases.list`

GET /shops/{shop}/purchases

Champs retournés : id, shop_id, reference, supplier_id, supplier_name, purchase_date, status, total_amount, paid_amount, due_amount, comment, created_at, updated_at

`purchases.get`

GET /shops/{shop}/purchases/{id}

Champs retournés : id, shop_id, reference, supplier_id, supplier_name, purchase_date, status, total_amount, paid_amount, due_amount, comment, created_at, updated_at

`purchases.create`

POST /shops/{shop}/purchases

Champs acceptés : reference, supplier_id, purchase_date, comment, items, supplier_name

Champs obligatoires : purchase_date. La spécification OpenAPI décrit aussi les lignes items.

`purchases.update`

PATCH /shops/{shop}/purchases/{id}

Champs acceptés : reference, supplier_id, purchase_date, comment, items, supplier_name

Champs obligatoires : purchase_date, items. La spécification OpenAPI décrit aussi les lignes items.

`purchases.validate`

POST /shops/{shop}/purchases/{id}/validate

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`purchases.payment`

POST /shops/{shop}/purchases/{id}/payment

Validation humaine requise — réponse 202.

Champs acceptés : amount, method, payment_date, reference, notes

Champs obligatoires : amount. La spécification OpenAPI décrit aussi les lignes items.

sales 6 opérations

`sales.list`

GET /shops/{shop}/sales

Champs retournés : id, shop_id, reference, client_id, customer_name, status, subtotal_amount, discount_amount, total_amount, payment_method, paid_at, cash_register_id, cash_register_session_id, created_at, updated_at

`sales.get`

GET /shops/{shop}/sales/{id}

`sales.create`

POST /shops/{shop}/sales

Champs acceptés : items, customer_name, client_id, external_ref, discount_type, discount_value

Champs obligatoires : items. La spécification OpenAPI décrit aussi les lignes items.

`sales.update`

PATCH /shops/{shop}/sales/{id}

Champs acceptés : items, customer_name, client_id, external_ref, discount_type, discount_value

Champs obligatoires : items. La spécification OpenAPI décrit aussi les lignes items.

`sales.payment`

POST /shops/{shop}/sales/{id}/payment

Validation humaine requise — réponse 202.

Champs acceptés : payment_method, payment_reference, amount_received, amount_returned

Champs obligatoires : payment_method. La spécification OpenAPI décrit aussi les lignes items.

`sales.refund`

POST /shops/{shop}/sales/{id}/refund

Validation humaine requise — réponse 202.

Champs acceptés : reason

Champs obligatoires : reason. La spécification OpenAPI décrit aussi les lignes items.

inventories 7 opérations

`inventories.list`

GET /shops/{shop}/inventories

Champs retournés : id, shop_id, reference, status, type, description, total_items, total_difference, created_at, updated_at

`inventories.get`

GET /shops/{shop}/inventories/{id}

Champs retournés : id, shop_id, reference, status, type, description, total_items, total_difference, created_at, updated_at

`inventories.create`

POST /shops/{shop}/inventories

Champs acceptés : type, description, rayon_ids

Champs obligatoires : type. La spécification OpenAPI décrit aussi les lignes items.

`inventories.update`

PATCH /shops/{shop}/inventories/{id}

Champs acceptés : type, description, rayon_ids

Champs obligatoires : type. La spécification OpenAPI décrit aussi les lignes items.

`inventories.count`

POST /shops/{shop}/inventories/{id}/count

Champs acceptés : item_id, real_quantity

Champs obligatoires : item_id, real_quantity. La spécification OpenAPI décrit aussi les lignes items.

`inventories.close`

POST /shops/{shop}/inventories/{id}/close

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`inventories.validate`

POST /shops/{shop}/inventories/{id}/validate

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

stock_transfers 7 opérations

`transfers.list`

GET /shops/{shop}/transfers

Champs retournés : id, source_shop_id, destination_shop_id, reference, status, notes, sent_at, received_at, created_at, updated_at

`transfers.get`

GET /shops/{shop}/transfers/{id}

Champs retournés : id, source_shop_id, destination_shop_id, reference, status, notes, sent_at, received_at, created_at, updated_at

`transfers.create`

POST /shops/{shop}/transfers

Champs acceptés : destination_shop_id, items, notes

Champs obligatoires : destination_shop_id, items. La spécification OpenAPI décrit aussi les lignes items.

`transfers.update`

PATCH /shops/{shop}/transfers/{id}

Champs acceptés : destination_shop_id, items, notes

Champs obligatoires : destination_shop_id, items. La spécification OpenAPI décrit aussi les lignes items.

`transfers.send`

POST /shops/{shop}/transfers/{id}/send

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`transfers.receive`

POST /shops/{shop}/transfers/{id}/receive

Champs acceptés : items

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`transfers.cancel`

POST /shops/{shop}/transfers/{id}/cancel

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

stock_movements 5 opérations

`stock_movements.list`

GET /shops/{shop}/stock-movements

Champs retournés : id, shop_id, product_id, type, quantity, stock_before, stock_after, unit_price, notes, created_at, updated_at

`stock_movements.get`

GET /shops/{shop}/stock-movements/{id}

Champs retournés : id, shop_id, product_id, type, quantity, stock_before, stock_after, unit_price, notes, created_at, updated_at

`stock_movements.create`

POST /shops/{shop}/stock-movements

Champs acceptés : product_id, stock_movement_reason_id, quantity, unit_price, lot_number, expiry_date, occurred_at, notes

Champs obligatoires : product_id, stock_movement_reason_id, quantity. La spécification OpenAPI décrit aussi les lignes items.

`stock_reasons.list`

GET /shops/{shop}/stock-reasons

Champs retournés : id, shop_id, code, label, type, impact, is_active

`stock_reasons.get`

GET /shops/{shop}/stock-reasons/{id}

Champs retournés : id, shop_id, code, label, type, impact, is_active

promotions 4 opérations

`promotions.list`

GET /shops/{shop}/promotions

Champs retournés : id, shop_id, product_id, promotion_price, starts_at, ends_at, is_active, notes, created_at, updated_at

`promotions.get`

GET /shops/{shop}/promotions/{id}

Champs retournés : id, shop_id, product_id, promotion_price, starts_at, ends_at, is_active, notes, created_at, updated_at

`promotions.create`

POST /shops/{shop}/promotions

Champs acceptés : product_id, promotion_price, starts_at, ends_at, is_active, notes

Champs obligatoires : product_id, promotion_price, starts_at, ends_at. La spécification OpenAPI décrit aussi les lignes items.

`promotions.update`

PATCH /shops/{shop}/promotions/{id}

Champs acceptés : product_id, promotion_price, starts_at, ends_at, is_active, notes

Champs obligatoires : product_id, promotion_price, starts_at, ends_at. La spécification OpenAPI décrit aussi les lignes items.

deliveries 6 opérations

`deliveries.list`

GET /shops/{shop}/deliveries

Champs retournés : id, shop_id, sale_id, deliverer_id, delivery_zone_id, zone_name_snapshot, deliverer_name_snapshot, status, delivery_fee, delivered_at, notes, created_at, updated_at

`deliveries.get`

GET /shops/{shop}/deliveries/{id}

Champs retournés : id, shop_id, sale_id, deliverer_id, delivery_zone_id, zone_name_snapshot, deliverer_name_snapshot, status, delivery_fee, delivered_at, notes, created_at, updated_at

`deliveries.create`

POST /shops/{shop}/deliveries

Champs acceptés : sale_id, deliverer_id, delivery_zone_id, zone_name_custom, deliverer_name, deliverer_phone, notes

Champs obligatoires : sale_id. La spécification OpenAPI décrit aussi les lignes items.

`deliveries.update`

PATCH /shops/{shop}/deliveries/{id}

Champs acceptés : deliverer_id, status, notes

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`delivery_zones.list`

GET /shops/{shop}/delivery-zones

Champs retournés : id, shop_id, name, fee, is_active, created_at, updated_at

`delivery_zones.get`

GET /shops/{shop}/delivery-zones/{id}

Champs retournés : id, shop_id, name, fee, is_active, created_at, updated_at

expenses 9 opérations

`expenses.list`

GET /shops/{shop}/expenses

Champs retournés : id, shop_id, reference, label, expense_type_id, supplier_id, amount, paid_amount, due_amount, currency_code, expense_date, due_date, status, beneficiary, notes, created_at, updated_at

`expenses.get`

GET /shops/{shop}/expenses/{id}

`expenses.create`

POST /shops/{shop}/expenses

Champs acceptés : expense_type_id, supplier_id, reference, label, amount, expense_date, due_date, beneficiary, notes

Champs obligatoires : expense_type_id, label, amount, expense_date. La spécification OpenAPI décrit aussi les lignes items.

`expenses.update`

PATCH /shops/{shop}/expenses/{id}

Champs acceptés : expense_type_id, supplier_id, reference, label, amount, expense_date, due_date, beneficiary, notes

Champs obligatoires : expense_type_id, label, amount, expense_date. La spécification OpenAPI décrit aussi les lignes items.

`expenses.validate`

POST /shops/{shop}/expenses/{id}/validate

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

`expenses.payment`

POST /shops/{shop}/expenses/{id}/payment

Validation humaine requise — réponse 202.

Champs acceptés : amount, payment_method, payment_date, notes, reference

Champs obligatoires : amount, payment_method. La spécification OpenAPI décrit aussi les lignes items.

`expenses.refund`

POST /shops/{shop}/expenses/{id}/refund

Validation humaine requise — réponse 202.

Champs acceptés : reason

Champs obligatoires : reason. La spécification OpenAPI décrit aussi les lignes items.

`expense_types.list`

GET /shops/{shop}/expense-types

Champs retournés : id, shop_id, name, code, is_active

`expense_types.get`

GET /shops/{shop}/expense-types/{id}

Champs retournés : id, shop_id, name, code, is_active

wallet 9 opérations

`wallets.list`

GET /shops/{shop}/wallets

Champs retournés : id, shop_id, name, code, current_balance, profit_percentage, is_active, notes, created_at, updated_at

`wallets.get`

GET /shops/{shop}/wallets/{id}

Champs retournés : id, shop_id, name, code, current_balance, profit_percentage, is_active, notes, created_at, updated_at

`wallets.create`

POST /shops/{shop}/wallets

Champs acceptés : name, code, profit_percentage, notes

Champs obligatoires : name. La spécification OpenAPI décrit aussi les lignes items.

`wallets.update`

PATCH /shops/{shop}/wallets/{id}

Champs acceptés : name, code, profit_percentage, notes, is_active

Champs obligatoires : name, code, is_active. La spécification OpenAPI décrit aussi les lignes items.

`wallets.adjust`

POST /shops/{shop}/wallets/{id}/adjust

Validation humaine requise — réponse 202.

Champs acceptés : amount, note

Champs obligatoires : amount, note. La spécification OpenAPI décrit aussi les lignes items.

`wallet_transactions.list`

GET /shops/{shop}/wallet-transactions

Champs retournés : id, shop_id, wallet_id, product_id, type, amount, balance_before, balance_after, cash_impact, reference, status, customer_phone, operator_reference, created_at, updated_at

`wallet_transactions.get`

GET /shops/{shop}/wallet-transactions/{id}

Champs retournés : id, shop_id, wallet_id, product_id, type, amount, balance_before, balance_after, cash_impact, reference, status, customer_phone, operator_reference, created_at, updated_at

`wallet_transactions.operate`

POST /shops/{shop}/wallet-transactions/operate

Validation humaine requise — réponse 202.

Champs acceptés : product_id, amount, note, customer_phone, operator_reference

Champs obligatoires : product_id, amount. La spécification OpenAPI décrit aussi les lignes items.

`wallet_transactions.cancel`

POST /shops/{shop}/wallet-transactions/{id}/cancel

Validation humaine requise — réponse 202.

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

supplier_returns 5 opérations

`supplier_returns.list`

GET /shops/{shop}/supplier-returns

Champs retournés : id, shop_id, reference, supplier_id, purchase_id, status, total_amount, comment, return_date, created_at, updated_at

`supplier_returns.get`

GET /shops/{shop}/supplier-returns/{id}

Champs retournés : id, shop_id, reference, supplier_id, purchase_id, status, total_amount, comment, return_date, created_at, updated_at

`supplier_returns.create`

POST /shops/{shop}/supplier-returns

Champs acceptés : reference, purchase_id, return_date, comment, items

Champs obligatoires : purchase_id, return_date, items. La spécification OpenAPI décrit aussi les lignes items.

`supplier_returns.update`

PATCH /shops/{shop}/supplier-returns/{id}

Champs acceptés : reference, purchase_id, return_date, comment, items

Champs obligatoires : purchase_id, return_date, items. La spécification OpenAPI décrit aussi les lignes items.

`supplier_returns.validate`

POST /shops/{shop}/supplier-returns/{id}/validate

Champs acceptés : Aucun champ métier.

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

shops 3 opérations

`shops.list`

GET /shops/{shop}/shops

Champs retournés : id, name, code, site_type, phone, email, address, city, country, timezone, currency_code, tva_rate, css_rate, is_active, created_at, updated_at

`shops.get`

GET /shops/{shop}/shops/{id}

Champs retournés : id, name, code, site_type, phone, email, address, city, country, timezone, currency_code, tva_rate, css_rate, is_active, created_at, updated_at

`shops.update`

PATCH /shops/{shop}/shops/{id}

Champs acceptés : name, phone, email, address, city, country, timezone, tva_rate, css_rate

Champs obligatoires : Aucun.. La spécification OpenAPI décrit aussi les lignes items.

cash_registers 4 opérations

`cash_registers.list`

GET /shops/{shop}/cash-registers

Champs retournés : id, shop_id, name, code, type, is_active, created_at, updated_at

`cash_registers.get`

GET /shops/{shop}/cash-registers/{id}

Champs retournés : id, shop_id, name, code, type, is_active, created_at, updated_at

`cash_sessions.list`

GET /shops/{shop}/cash-sessions

Champs retournés : id, shop_id, cash_register_id, user_id, status, opened_at, closed_at, operation_date, created_at, updated_at

`cash_sessions.get`

GET /shops/{shop}/cash-sessions/{id}

Champs retournés : id, shop_id, cash_register_id, user_id, status, opened_at, closed_at, operation_date, created_at, updated_at

settings 3 opérations

`requests.list`

GET /shops/{shop}/requests

Champs retournés : id, shop_id, integration_access_id, operation, status, reviewed_by, reviewed_at, reason, result, created_at, updated_at

`requests.get`

GET /shops/{shop}/requests/{id}

Champs retournés : id, shop_id, integration_access_id, operation, status, reviewed_by, reviewed_at, reason, result, created_at, updated_at

`context.get`

GET /context

Champs retournés : organization_uuid, shops, abilities

reports 1 opérations

`reports.summary`

GET /shops/{shop}/reports/summary

Champs retournés : sales_count, sales_total, currency