Commerce 360

Use this read-only tool to learn which Commerce 360 companies and shops this authenticated connection can currently access and which read capabilities are available for each company. It takes no arguments and needs no business scope. Use it before company-scoped stock, sales or replenishment questions when the company or shop ID is unknown. If several companies are returned, ask the user to choose; do not pick the first. If a capability is false, do not treat that business read as available. A true capability is only an informational snapshot, not a grant or proof that any record exists; each later API call checks rights again. No pagination, stock totals, sales amounts or historical authorization are returned. Example 1: User asks 'Which shops can I analyze?' -> call with {} and present the company and shop IDs. Example 2: User asks 'Why can't I see sales for Lyon?' -> call with {}, inspect that company's salesRead/statisticsSalesRead and shops, then explain the observed scope or assignment; do not change permissions.

get_connection_context

Use before filtering by metal, stone, size or another characteristic: resolve the configured ID, form and type rather than guessing a free-text code. A definition's presence does not prove any article has a value. Example: 'Which item characteristics represent size?' -> {form:'item'}; 'List ring characteristics and their values' -> {category_id:'CAT-RINGS',include:['values']}.

list_characteristics

Use directory mode for a bounded customer list filtered by name/text, home shops, company, type, guest state, update time, recorded consents, contact presence and observed purchases. Purchase criteria or include=purchaseStats need sales:read and every company history shop including closed shops; guest=true cannot be combined with purchase criteria, purchaseStats, from/to or amount_mode because native purchase readers exclude guests. Last purchase before is exclusive, after inclusive. purchaseStats includes signed Statistics net spend at business movement dates; from/to is a paired inclusive amount window, otherwise observed history through as_of. Presence filters need customers:pii:read. Metadata records the effective scope and unknown history; no implicit 24-month rule. Use export_customers for a complete private extraction. Use identity mode only with a specific identity criterion and customers:pii:read. Directory without a filter is refused to avoid a broad extraction. Rows are candidate records, not a fuzzy cross-company merge; never select the first namesake silently. Directory contact coordinates are withheld even when the token has PII rights; use an exact profile lookup if authorized. Example: 'Customers named Martin' -> {mode:'directory',search:'Martin',page:1,limit:20}; 'Find customer number C-123 exactly' -> {mode:'identity',customer_number:'C-123',match_mode:'exact'}. Ask for disambiguation if several IDs match; reuse the selected uuid for get_customer_profile or get_customer_purchase_summary if authorized.

search_customers

Use to locate sale documents by exact or partial number, creation instant, authorized customer ID, seller_id, current status/action or shop before reading a document. seller_id selects the seller recorded on the current/history document before count and pagination; it is not the native Statistics sale/order/SAV attribution used by inspect_sales_activity grain=line. Pagination covers documents only; it is not signed turnover and creation dates are not sales business dates. Customer contact fields are not requested. Example: 'Find V-2026-00184' -> {number:'V-2026-00184',page:1,limit:20} and check the public ID before detail; 'Documents recorded for seller SELLER-1 in Paris' -> {seller_id:'SELLER-1',shop_id:'SHOP-1',page:1,limit:25} and continue pages with the same filters, not as a period turnover total. Use get_sales_summary for turnover or inspect_sales_activity for signed facts and Statistics seller attribution.

search_sales

Direct read-only GET /v1/products/{productId}. Returns one product reference by public product id, with optional characteristics, media, prices, stock and items. Use after list_products_v1 when the user needs full product detail.

get_product_v1

Direct read-only GET /v1/product-items/{itemId}. Returns one physical item by public item id with price, promotion, availability and optional product, characteristics, media, shop, category or supplier relations.

get_product_item_v1

Direct read-only GET /v1/sales/{saleId}. Returns one sale with requested non-customer relations such as items, payments, discounts, shop, seller, invoice, or origins. Customer identity and contact details are intentionally redacted.

get_sale_v1

Get full read-only details for one HBJO reference using reference, reference_uuid, reference_id, or article_code. Returns catalogue fields, supplier, stock status, and all articles.

get_reference_details

Get stock availability for one HBJO reference or article, optionally filtered to one shop. Use this for direct questions like 'combien reste-t-il de cette référence ?'.

get_reference_stock

Compute finite stock value for one HBJO reference or article, optionally filtered to one shop. Uses article price times stockAvailable.

get_reference_stock_value

Direct read-only GET /v1/sales/{saleId}/invoice. Returns official invoice metadata, totals, issue date, status, number, and whether the PDF is available. It does not download the binary PDF.

get_sale_invoice_v1

Return an operational stock dashboard: reference/article counts, recent entries, stale stock, stock statuses, and anomaly counts. Use this for broad questions like 'fais un état du stock'.

get_stock_operations_summary

Use this for a bounded current-stock material breakdown of one to ten resolved products, not a metal valuation or historical inventory. Resolve material definition/value IDs with list_characteristics and list_characteristic_values; material_filter optionally pushes an exact typed filter to stock/articles before item enrichment. At most three 100-row pages from start_page are read, then item IDs in 50-row batches. Material groups may overlap. Weight requires item-level material, numeric per-unit weight and unit in the same characteristic group plus explicit merchant-confirmed field semantics; the MCP cannot independently certify that convention. No theoretical product weight, metal-fineness conversion or price feed. Example: 'Group ring stock by configured metal' -> {product_ids:['PROD-1'],characteristic_code:'METAL'}; 'Inspect one proven material value from page two' -> {product_ids:['PROD-1'],characteristic_code:'METAL',material_filter:{characteristic_id:'CHAR-1',value_id:'VALUE-1'},start_page:2}. Only observations from returned pages are grouped; use nextStockPage with unchanged filters if present.

analyze_stock_materials

Use for a known product/item or bounded page of current physical stock, allocations, raw balance, floored availability, operational flags and native anomalies. state:active hides terminal rows, not zero availability. positive_available_only=true selects known finite availability > 0 before totals/pagination; false removes that filter, not its inverse. Unknown finite physical quantity is natively treated as zero and flagged; unlimited quantity is null. Availability is not historical inventory and first entry is not current-shop arrival. Example: 'How many ITEM-1 remain?' -> {item_id:'ITEM-1'}; 'Positive finite stock of PROD-1 in Paris' -> {product_id:'PROD-1',shop_ids:['SHOP-1'],positive_available_only:true,page:1,limit:20}. Continue native pages; summary is the full filtered population. Use list_stock_anomalies for proven source anomalies and get_stock_value_summary for valuation/productShop grouping. High quantity alone is not proof of incorrect stock.

get_stock_availability

Use for an identified sale's items, payments, discounts, shop, seller, invoice or origins, not for a period aggregate. Request only necessary relations. paymentsEvidence=historical_unknown is not proof of an unpaid balance; a similar item label is not a proven historical product join. Customer-credit details in payments are withheld without customer-credits:read; no customer contact relation is requested. Example: 'Show SALE-1' -> {sale_id:'SALE-1'} and read its document status/amounts; 'Explain its lines and payments' -> {sale_id:'SALE-1',include:['items','payments','discounts']} and check IDs and payment evidence. For signed period facts use inspect_sales_activity; for the official invoice use get_sale_invoice.

get_sale_details

Use for traceable signed sales facts over inclusive company-local business dates, including articles sold by an identified seller without scanning sale documents. grain='movement' returns entire movement amounts; grain='line' returns line amounts, persisted product/article IDs and current proven reference code/name. For a seller name first use analyze_sales_breakdown with dimension='seller', same company/shops/period, continue its group pages and confirm the exact seller ID; never silently choose a homonym. Then pass seller_id with grain='line', usually line_type='product'. Both filters are applied natively before counting/pagination. Attribution follows the same sale/order/SAV rules as seller breakdown, not the cashier's name. Product lines retain signed returns/cancellations; do not call gross positive lines net sales or sum only the first page. Unknown amounts/quantities remain null; labels are current, not historical. A product-filtered movement still carries the entire movement amount, never that product's share. A line's payment component is not a payment allocated to a product. nextCursor expires after 15 minutes, is bound to principal, rights, company, shops, all filters and limit; corrections can affect later pages. Example: 'Movements for SALE-1' -> {grain:'movement',from:'2026-09-01',to:'2026-09-30',sale_id:'SALE-1'}; 'Articles sold by the confirmed seller SELLER-1 this year' -> {grain:'line',from:'2026-01-01',to:'2026-10-06',seller_id:'SELLER-1',line_type:'product',limit:100}. Continue every cursor page with unchanged arguments; report incomplete coverage if stopped. Use get_sales_summary for whole-period totals, search_product_items for explicit bounded article enrichment, and list_payment_entries for settlement dates.

inspect_sales_activity

Direct read-only GET /v1/catalog/changes. Returns incremental catalogue changes since an ISO date-time for products, product-items, categories, characteristics, or shops. Use this for questions about what changed since a date.

list_catalog_changes_v1

Direct read-only GET /v1/catalog/products. Returns the complete e-commerce catalogue feed with products, product items, prices, media, stock, shops, suppliers, updatedAt and pagination. Use this for native V1 catalogue fields or catalogue synchronization questions.

list_catalog_products_v1

Direct read-only GET /v1/categories. Returns catalogue categories, optionally filtered by parent, product type, online display or second-hand status, and can include child categories. Use for category filtering and navigation questions.

list_categories_v1

Direct read-only GET /v1/characteristics/{characteristicId}/values. Returns allowed or used values for one characteristic, optionally scoped to product type, category or available stock.

list_characteristic_values_v1

Direct read-only GET /v1/characteristics. Returns product and item characteristic definitions, optionally filtered by product type, category, display flag or form context, and can include referential values.

list_characteristics_v1

Direct read-only GET /v1/product-items. Searches physical items globally with stock availability, price range, promotion, second-hand, product, shop, supplier, product type, category, updatedSince and include filters. Use this for article-level questions across the stock.

list_product_items_v1

Direct read-only GET /v1/products/{productId}/items. Returns physical items attached to one product, with availability, shop, promotion, updatedSince and optional characteristics/media/shop relations. Use when the user asks for item-level stock for one known product.

list_product_items_for_product_v1

Direct read-only GET /v1/product-types. Returns product types, optionally with categories and characteristics. Use this to discover product families before filtering products or characteristics.

list_product_types_v1

Direct read-only GET /v1/products. Searches and filters product references by text, online display, availability, updatedSince, supplier, product type, category, shop and optional include relations. Use this to find product IDs before requesting full product or item details.

list_products_v1

Direct read-only GET /v1/sales. Use to find documents by creation date, shop, status, action, number, customer public ID or seller_id. The seller is recorded on the current/history document, not the native Statistics sale/order/SAV attribution used by inspect_sales_activity grain=line. It filters before count and pagination, not signed turnover. Customer names and contact details are intentionally redacted. Example: 'Documents recorded for seller SELLER-1' -> {seller_id:'SELLER-1',page:1,limit:25}; 'Their next Paris page' -> {seller_id:'SELLER-1',shop_id:'SHOP-1',page:2,limit:25}, keeping all filters unchanged. Prefer search_sales for the canonical reader and dedicated sales analysis tools for totals.

list_sales_v1

Direct read-only GET /v1/shops. Returns Commerce 360 shop referential data. Use this when the user needs official shop IDs or wants to choose a shop filter.

list_referential_shops_v1

List suppliers found in HBJO references, optionally filtered by supplier name, short name, or UUID. Use this before supplier-specific catalogue searches.

list_suppliers

Use to discover the actual hierarchy and category IDs before filtering products or stock. Do not derive an authoritative category from a product label. Example: 'Which categories are under rings?' -> {parent_id:'CAT-RINGS'}; 'Which second-hand categories exist?' -> {is_second_hand:true,include:['children']}.

list_categories

Use to find configured product-type IDs and optional categories/characteristics. Types vary by jeweler and should not be inferred from generic jewelry terms. Example: 'List types' -> {}; 'Show online types and their characteristics' -> {displayed_online:true,include:['characteristics']}.

list_product_types

Use for dated signed settlement entries, optionally linked to one sale, when aggregated payment-method totals are insufficient. Business dates are settlement dates, not sale creation dates; values are incl. tax and credit/gift-card/deposit use is not new cash. Neither product_id nor payment-method filter exists, and payments must never be attributed to a product. Cursor pages are not complete totals; keep principal, rights, shops, filters, scope and limit unchanged across continuation, and restart after expiry (15 minutes). Example: 'Payments for SALE-1' -> {from:'2026-09-01',to:'2026-09-30',sale_id:'SALE-1'} and inspect known settlement entries; 'Known Paris payments this month' -> {from:'2026-09-01',to:'2026-09-30',shop_ids:['SHOP-1'],limit:50} and continue while nextCursor exists. For native payment mix totals use analyze_payment_methods; this is not turnover or a bank reconciliation.

list_payment_entries

Use to inspect native source anomalies: negative physical quantity, over-allocation, terminal stock, allocated terminal items, missing finite physical quantity or missing cost. One item may have several anomaly categories; do not add category counts as distinct items. Zero cost is known, not missing. This is not an online-publication audit and never fixes data. Example: 'Find overallocated items' -> {category:'over_allocated'}; 'Anomalies for PROD-1' -> {product_id:'PROD-1',page:1,limit:20}. Keep the summary's full filtered population separate from the page and inspect a matching item with get_stock_availability if needed.

list_stock_anomalies

Use this read-only official shop referential to find shop IDs, names, short names and cities, including shops with no current stock. A shop in this referential is not necessarily accessible for every business call; use get_connection_context to check the authenticated assignment. Example: 'Which shops are active?' -> {active_only:true}; 'List also inactive shops' -> {active_only:false}. Homonyms require disambiguation by ID.

list_shops

Use after resolving a characteristic ID to learn configured or used values and IDs for a typed stock filter. A possible value is not evidence that it is present in current stock. Example: 'Which sizes are configured?' -> {characteristic_id:'CHAR-SIZE'}; 'Which sizes occur in available rings?' -> {characteristic_id:'CHAR-SIZE',category_id:'CAT-RINGS',used_only:true,available_only:true}.

list_characteristic_values

List articles whose inStockDate is in a date range. Use this for questions like 'articles entered in stock in the last 3 months'. If the user says last 3 months, use last_days=90.

list_recent_stock_entries

List HBJO references by computed stock status: available, out_of_stock, or unlimited. Use this for questions about ruptures, available stock, or unlimited references.

list_references_by_stock_status

List available articles whose inStockDate is older than a threshold. Use this for dormant/old stock questions, for example stock older than 12 months.

list_stale_stock

Break down finite stock value by HBJO shop. Use this for questions about stock value per boutique or store.

list_stock_value_by_shop

Break down finite stock value by HBJO supplier. Use this for supplier valuation, vendor exposure, or stock value ranking by supplier.

list_stock_value_by_supplier

List HBJO references ranked by finite stock value, highest first. Use this to identify the most valuable references in stock.

list_top_stock_value_references