diff --git a/CITATION.cff b/CITATION.cff
index e45b66336..68fdb594e 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -13,7 +13,7 @@ abstract: >
server that turns REST/OpenAPI, SOAP/WSDL and GraphQL APIs, SQL/NoSQL
databases and other MCP servers into tools for AI clients such as Claude,
ChatGPT, Google Gemini, GitHub Copilot and Cursor, without writing code.
- It ships 886 pre-built adapters, with a focus on ERP and e-commerce
+ It ships 901 pre-built adapters, with a focus on ERP and e-commerce
systems (SAP Business One, Odoo, Xentral, JTL-Wawi, weclapp, Shopware,
WooCommerce, Amazon Seller, Kaufland, OTTO, etc.), a per-workspace
knowledge graph served over MCP, File Search over company file servers
diff --git a/README.de.md b/README.de.md
index 272543612..fe5557d36 100644
--- a/README.de.md
+++ b/README.de.md
@@ -1,5 +1,5 @@
-
+
AnythingMCP: das Open-Source-MCP-Gateway, das zum Gehirn deines Unternehmens wird
@@ -54,7 +54,7 @@ Ein Gateway reicht Aufrufe weiter. Ein Firmengehirn weiß außerdem, wo deine Do
| | Was es macht | Edition |
|---|---|---|
-| **Jedes System, ein Endpunkt** | 886 Connectors aus dem Katalog oder deine eigene REST-/OpenAPI-, SOAP-, GraphQL-, OData-, SQL-, IMAP/SMTP- oder MCP-Quelle. Tools werden zur Laufzeit registriert. [Connectors](#connect-any-api-soap-service-or-database) | Alle |
+| **Jedes System, ein Endpunkt** | 901 Connectors aus dem Katalog oder deine eigene REST-/OpenAPI-, SOAP-, GraphQL-, OData-, SQL-, IMAP/SMTP- oder MCP-Quelle. Tools werden zur Laufzeit registriert. [Connectors](#connect-any-api-soap-service-or-database) | Alle |
| **File Search** | Indexiert SFTP, FTP/FTPS, WebDAV (Nextcloud, NAS), S3 oder eine Netzwerkfreigabe: jede PDF-Seite, Excel-Zeilen mit ihren Spaltennamen, Word, PowerPoint, Outlook-Mails mit Anhängen. Die KI antwortet mit Datei, Seite und Datum. [File Search](docs/connectors/file-search.md) | Cloud; selbst gehostet Enterprise |
| **File Share** | Befristete Download-Links für Dateien aus deinen Ordnern oder für Dateien, die die KI erstellt (einen CSV-Export, einen Bericht), intern oder öffentlich, mit Ablaufdatum und Widerruf. [File Share](docs/connectors/file-search.md) | Cloud; selbst gehostet Enterprise |
| **Firmengedächtnis** | Fakten und Vorlieben, in einem KI-Client gespeichert und in jedem anderen wiedergefunden: einmal in Claude gesagt, von Copilot genutzt. Persönlicher und firmenweiter Bereich, mit Ordnern und Rollengrenzen. [Gedächtnis](docs/memory.md) | Enterprise |
@@ -139,7 +139,7 @@ Tools werden zur Laufzeit registriert, ohne Neustart. `{{VAR}}`-Werte pro Connec
## Connector-Katalog
-886 Adapter mit über 12.000 Tools. Zu jedem gibt es eine Einrichtungsanleitung auf [anythingmcp.com/de/guides](https://anythingmcp.com/de/guides), in sieben Sprachen.
+901 Adapter mit über 12.000 Tools. Zu jedem gibt es eine Einrichtungsanleitung auf [anythingmcp.com/de/guides](https://anythingmcp.com/de/guides), in sieben Sprachen.
| Kategorie | Beispiele |
|---|---|
diff --git a/README.ja.md b/README.ja.md
index 564e70469..6c8d8ec82 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -1,5 +1,5 @@
AnythingMCP: the open-source MCP gateway that becomes your company brain
@@ -20,7 +20,7 @@
AnythingMCP is an open-source, self-hosted MCP gateway that connects Claude, ChatGPT, Copilot and Gemini to the software your company runs and to the documents on your file servers, without writing an MCP server.
On top of the gateway it keeps your company brain: a knowledge graph of how your systems connect, AI skills and company memory, shared by every AI client and limited by each user's role.
- 886 ready connectors with 12,000+ tools, among them SAP, Odoo, weclapp and Amazon Seller; 46 need no API key.
+ 901 ready connectors with 12,000+ tools, among them SAP, Odoo, weclapp and Amazon Seller; 46 need no API key.
@@ -130,7 +130,7 @@ Tools register at runtime, without a restart. Per-connector `{{VAR}}` values are
## Connector catalog
-886 adapters, exposing 12,000+ tools. Every one has a setup guide on [anythingmcp.com/guides](https://anythingmcp.com/guides), in seven languages. The [full catalog by category](docs/catalog/README.md) lists every Cloud connector with links to its guides for Claude, ChatGPT, Copilot, Cursor and Gemini, and the [connector marketplace](https://anythingmcp.com/marketplace) has a page for each one.
+901 adapters, exposing 12,000+ tools. Every one has a setup guide on [anythingmcp.com/guides](https://anythingmcp.com/guides), in seven languages. The [full catalog by category](docs/catalog/README.md) lists every Cloud connector with links to its guides for Claude, ChatGPT, Copilot, Cursor and Gemini, and the [connector marketplace](https://anythingmcp.com/marketplace) has a page for each one.
| Category | Examples |
|---|---|
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 9b6edce39..9fa851a7d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,5 +1,5 @@
@@ -139,7 +139,7 @@ docker compose up -d
## 连接器目录
-共 886 个适配器,提供 12,000 多个工具。每个适配器都在 [anythingmcp.com/zh/guides](https://anythingmcp.com/zh/guides) 上提供七种语言的配置指南。
+共 901 个适配器,提供 12,000 多个工具。每个适配器都在 [anythingmcp.com/zh/guides](https://anythingmcp.com/zh/guides) 上提供七种语言的配置指南。
| 类别 | 示例 |
|---|---|
diff --git a/glama.json b/glama.json
index 0b495edc9..82fba3f4b 100644
--- a/glama.json
+++ b/glama.json
@@ -3,5 +3,5 @@
"maintainers": [
"helpcodeai"
],
- "description": "Self-hosted MCP gateway and company brain for AI agents. Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code: 886 pre-built adapters for ERP and e-commerce (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, weclapp, Shopware, WooCommerce, Amazon Seller, Kaufland, OTTO\u2026) and more. File Search over SFTP/WebDAV/S3 file servers, company memory, AI skills and a knowledge graph shared by every AI client. Per-tool response mapping, OAuth2/RBAC/SSO/SCIM, audit log. Open source under AGPL-3.0."
+ "description": "Self-hosted MCP gateway and company brain for AI agents. Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code: 901 pre-built adapters for ERP and e-commerce (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, weclapp, Shopware, WooCommerce, Amazon Seller, Kaufland, OTTO\u2026) and more. File Search over SFTP/WebDAV/S3 file servers, company memory, AI skills and a knowledge graph shared by every AI client. Per-tool response mapping, OAuth2/RBAC/SSO/SCIM, audit log. Open source under AGPL-3.0."
}
diff --git a/llms-full.txt b/llms-full.txt
index c51f05b61..dbc488aac 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -1,6 +1,6 @@
# AnythingMCP
-> Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 886 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).
+> Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 901 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).
---
@@ -93,7 +93,7 @@ Tools register at runtime, without a restart. Per-connector `{{VAR}}` values are
## Connector catalog
-886 adapters, exposing 12,000+ tools. Every one has a setup guide on [anythingmcp.com/guides](), in seven languages. The [full catalog by category]() lists every Cloud connector with links to its guides for Claude, ChatGPT, Copilot, Cursor and Gemini, and the [connector marketplace]() has a page for each one.
+901 adapters, exposing 12,000+ tools. Every one has a setup guide on [anythingmcp.com/guides](), in seven languages. The [full catalog by category]() lists every Cloud connector with links to its guides for Claude, ChatGPT, Copilot, Cursor and Gemini, and the [connector marketplace]() has a page for each one.
| Category | Examples |
|---|---|
diff --git a/llms.txt b/llms.txt
index cc94fa26a..9a3fb8c98 100644
--- a/llms.txt
+++ b/llms.txt
@@ -1,6 +1,6 @@
# AnythingMCP
-> Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 886 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).
+> Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 901 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).
## Getting started
diff --git a/package.json b/package.json
index f638f12d8..7c27e03f6 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "anythingmcp",
"version": "0.55.4",
- "description": "Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 886 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).",
+ "description": "Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 901 pre-built adapters for ERP, e-commerce and more (SAP S/4HANA, SAP Business One, Odoo, Xentral, JTL-Wawi, Shopware, WooCommerce, Amazon Seller). Self-hosted, open source (AGPL-3.0).",
"private": true,
"license": "AGPL-3.0-only",
"engines": {
diff --git a/packages/backend/src/adapters/br/kabum.json b/packages/backend/src/adapters/br/kabum.json
new file mode 100644
index 000000000..1cc632ce0
--- /dev/null
+++ b/packages/backend/src/adapters/br/kabum.json
@@ -0,0 +1,2033 @@
+{
+ "slug": "kabum",
+ "name": "KaBuM! Marketplace",
+ "aliases": [
+ "Kabum marketplace",
+ "KaBuM seller API",
+ "KaBuM vendedor",
+ "Vender no KaBuM",
+ "KaBuM Mirakl",
+ "marketplace-kabum.mirakl.net"
+ ],
+ "description": "Run your shop on the KaBuM! marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Brazil; sign in with the shop API key from your KaBuM! seller back office.",
+ "instructions": "## KaBuM! Marketplace\nRun your shop on the KaBuM! marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and KaBuM!, returns, order documents, invoices and transactions. The connector calls the KaBuM! seller platform at `https://marketplace-kabum.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Brazil.\n\n**Who can sell**: KaBuM! reviews each seller after a pre-registration form, usually within one business day. Sellers need a Brazilian company registration (CNPJ) active for at least three months, must issue electronic invoices (NF-e) and sell new technology or gaming products from their own stock (no dropshipping). The commission is 18 % in all departments. The connector needs a seller account that KaBuM! has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the KaBuM! seller back office: `https://marketplace-kabum.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `KABUM_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `KABUM_SHOP_ID` empty. Only if your user manages several shops on KaBuM!, set `KABUM_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `kabum_get_account`). Without it your default shop is used.\n4. Install and run `kabum_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the KaBuM! seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `kabum_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `kabum_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `kabum_list_offers` for prices and stock and `kabum_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `kabum_get_products` looks products up in the KaBuM! catalog by EAN or another reference and returns the marketplace product SKU; `kabum_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `kabum_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `kabum_update_tracking` stores the carrier and tracking number (carrier codes come from `kabum_list_carriers`) and `kabum_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `kabum_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `kabum_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `kabum_list_order_documents`.\n\n**Writes: confirm first.** `kabum_accept_order`, `kabum_update_tracking`, `kabum_ship_order`, `kabum_resolve_incident`, `kabum_accept_return`, `kabum_receive_return`, `kabum_update_offers`, `kabum_reply_thread`, `kabum_create_order_thread` and `kabum_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `kabum_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `kabum_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`kabum_get_offer` or `kabum_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `kabum_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `kabum_list_offer_conditions`, logistic class codes from `kabum_list_logistic_classes`.\n\n**File imports**: `kabum_import_products` (P41) and `kabum_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format KaBuM! asks for; the connector downloads it and uploads it to KaBuM!. Track them with `kabum_list_product_imports` / `kabum_get_product_import` and `kabum_list_offer_imports` / `kabum_get_offer_import`.\n\n**Returns**: `kabum_list_returns` (RT11) lists return requests. Where KaBuM! lets the shop decide, `kabum_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `kabum_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `kabum_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `kabum_get_thread` reads one with its messages, `kabum_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is KaBuM!) and `kabum_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `kabum_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `kabum_list_invoices` (IV01) lists the accounting documents KaBuM! issues to the shop and `kabum_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If KaBuM! uses Enhanced Seller Invoicing, IV01 returns no new documents; use `kabum_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `kabum_export_offers`, poll `kabum_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `kabum_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `kabum_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `kabum_get_account` and the same `shop_id`. Without `shop_id` a call uses `KABUM_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `kabum_list_channels` (country sites), `kabum_list_carriers`, `kabum_list_shipping_zones`, `kabum_list_shipping_methods` and `kabum_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and KaBuM! can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `kabum_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "br",
+ "category": "e-commerce",
+ "icon": "kabum",
+ "docsUrl": "https://www.kabum.com.br/hotsite/marketplace",
+ "requiredEnvVars": [
+ "KABUM_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "KABUM_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with KaBuM! and access to its seller back office to generate the shop API key. KaBuM! reviews each seller after a pre-registration form, usually within one business day. Sellers need a Brazilian company registration (CNPJ) active for at least three months, must issue electronic invoices (NF-e) and sell new technology or gaming products from their own stock (no dropshipping). The commission is 18 % in all departments.",
+ "envVarMeta": {
+ "KABUM_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "KaBuM! seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://marketplace-kabum.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "KABUM_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on KaBuM!: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "KaBuM! refused the API key. Check that KABUM_API_KEY is the shop key from your KaBuM! seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set KABUM_SHOP_ID to a shop you manage.",
+ "404": "The KaBuM! seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://marketplace-kabum.mirakl.net: KaBuM! may have moved its seller back office.",
+ "rate_limited": "KaBuM! is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "kabum_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A KaBuM! seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your KaBuM! seller account",
+ "body": "Sign in to the KaBuM! seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the KaBuM! seller back office",
+ "url": "https://marketplace-kabum.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask KaBuM! (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "KaBuM! reviews each seller after a pre-registration form, usually within one business day. Sellers need a Brazilian company registration (CNPJ) active for at least three months, must issue electronic invoices (NF-e) and sell new technology or gaming products from their own stock (no dropshipping). The commission is 18 % in all departments. See [the KaBuM! seller page](https://www.kabum.com.br/hotsite/marketplace)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "KABUM_API_KEY",
+ "KABUM_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "KaBuM! refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "KaBuM! Marketplace",
+ "type": "REST",
+ "baseUrl": "https://marketplace-kabum.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{KABUM_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "kabum_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use kabum_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see kabum_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before kabum_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in kabum_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from kabum_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by kabum_update_offers or kabum_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by kabum_update_offers or kabum_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging kabum_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll kabum_get_offer_export_status about once a minute until COMPLETED, then read each file with kabum_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from kabum_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "kabum_get_offer_export_status",
+ "description": "Status of an offer export started with kabum_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to kabum_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by kabum_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by kabum_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by kabum_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references KaBuM! uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_threads",
+ "description": "List message threads (M11) with customers and KaBuM!: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with KaBuM!)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from kabum_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in kabum_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_invoices",
+ "description": "List the accounting documents KaBuM! issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_document_requests",
+ "description": "List accounting document requests (DR11), used when KaBuM! runs Enhanced Seller Invoicing: invoices and credit notes that KaBuM! or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by KaBuM! (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in kabum_list_orders and kabum_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in kabum_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "kabum_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from kabum_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from kabum_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from kabum_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in kabum_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in kabum_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with kabum_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with kabum_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from kabum_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or KaBuM!. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from kabum_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (KaBuM!) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "kabum_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, KaBuM! or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (KaBuM!) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from kabum_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "kabum_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from kabum_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in kabum_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from kabum_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when KaBuM! handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from kabum_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from kabum_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "kabum_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format KaBuM! asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with kabum_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format KaBuM! defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "kabum_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format KaBuM! asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with kabum_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by kabum_get_account, also shown in the back office). Leave it out to use KABUM_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "KABUM_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/br/kabum.live.spec.ts b/packages/backend/src/adapters/br/kabum.live.spec.ts
new file mode 100644
index 000000000..f1bc29860
--- /dev/null
+++ b/packages/backend/src/adapters/br/kabum.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './kabum.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_KABUM_LIVE=1 (GET /api/version needs no key; the shop reads need KABUM_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'kabum', hosts: ['marketplace-kabum.mirakl.net'] });
diff --git a/packages/backend/src/adapters/catalog.ts b/packages/backend/src/adapters/catalog.ts
index 6132b1803..c8256e044 100644
--- a/packages/backend/src/adapters/catalog.ts
+++ b/packages/backend/src/adapters/catalog.ts
@@ -1,6 +1,7 @@
// === AUTOGEN-IMPORTS-BEGIN === run scripts/regenerate-catalog.mjs ===
import * as aBoss from './de/a-boss.json';
import * as apaleo from './de/apaleo.json';
+import * as autodoc from './de/autodoc.json';
import * as billbee from './de/billbee.json';
import * as billomat from './de/billomat.json';
import * as buchhaltungsbutler from './de/buchhaltungsbutler.json';
@@ -82,6 +83,7 @@ import * as xovi from './de/xovi.json';
import * as zalandoZds from './de/zalando-zds.json';
import * as zammad from './de/zammad.json';
import * as znuny from './de/znuny.json';
+import * as zooplus from './de/zooplus.json';
import * as bAndQ from './gb/b-and-q.json';
import * as brandalley from './gb/brandalley.json';
import * as companiesHouse from './gb/companies-house.json';
@@ -576,6 +578,7 @@ import * as procore from './intl/procore.json';
import * as productboard from './intl/productboard.json';
import * as promUa from './intl/prom-ua.json';
import * as proxmox from './intl/proxmox.json';
+import * as publicGr from './intl/public-gr.json';
import * as qnapFileSearch from './intl/qnap-file-search.json';
import * as quaderno from './intl/quaderno.json';
import * as quickbooksOnline from './intl/quickbooks-online.json';
@@ -607,6 +610,7 @@ import * as rozetka from './intl/rozetka.json';
import * as rubrik from './intl/rubrik.json';
import * as s3FileSearch from './intl/s3-file-search.json';
import * as sageBusinessCloud from './intl/sage-business-cloud.json';
+import * as saks from './intl/saks.json';
import * as salesflare from './intl/salesflare.json';
import * as salesforce from './intl/salesforce.json';
import * as salesforceCommerceCloud from './intl/salesforce-commerce-cloud.json';
@@ -700,6 +704,7 @@ import * as telegramBot from './intl/telegram-bot.json';
import * as telnyx from './intl/telnyx.json';
import * as temu from './intl/temu.json';
import * as tezga from './intl/tezga.json';
+import * as theKnot from './intl/the-knot.json';
import * as theOddsApi from './intl/the-odds-api.json';
import * as threads from './intl/threads.json';
import * as ticktick from './intl/ticktick.json';
@@ -725,6 +730,7 @@ import * as ukrposhta from './intl/ukrposhta.json';
import * as untappd from './intl/untappd.json';
import * as ups from './intl/ups.json';
import * as uptimeRobot from './intl/uptime-robot.json';
+import * as urbn from './intl/urbn.json';
import * as usps from './intl/usps.json';
import * as uzumMarket from './intl/uzum-market.json';
import * as vapi from './intl/vapi.json';
@@ -788,6 +794,7 @@ import * as zoominfo from './intl/zoominfo.json';
import * as zuora from './intl/zuora.json';
import * as bling from './br/bling.json';
import * as digisac from './br/digisac.json';
+import * as kabum from './br/kabum.json';
import * as lojaIntegrada from './br/loja-integrada.json';
import * as magalu from './br/magalu.json';
import * as mercadoLibre from './br/mercado-libre.json';
@@ -825,8 +832,11 @@ import * as elCorteIngles from './es/el-corte-ingles.json';
import * as holded from './es/holded.json';
import * as miravia from './es/miravia.json';
import * as pccomponentes from './es/pccomponentes.json';
+import * as phoneHouse from './es/phone-house.json';
+import * as planetaHuerto from './es/planeta-huerto.json';
import * as quipu from './es/quipu.json';
import * as sprinter from './es/sprinter.json';
+import * as tiendanimal from './es/tiendanimal.json';
import * as atlasForMen from './fr/atlas-for-men.json';
import * as auchan from './fr/auchan.json';
import * as axonaut from './fr/axonaut.json';
@@ -845,19 +855,24 @@ import * as kiabi from './fr/kiabi.json';
import * as laPoste from './fr/la-poste.json';
import * as laRedoute from './fr/la-redoute.json';
import * as ldlc from './fr/ldlc.json';
+import * as macway from './fr/macway.json';
import * as manomano from './fr/manomano.json';
import * as natureEtDecouvertes from './fr/nature-et-decouvertes.json';
import * as octopia from './fr/octopia.json';
+import * as orangeMarketplace from './fr/orange-marketplace.json';
import * as pennylane from './fr/pennylane.json';
import * as pixmania from './fr/pixmania.json';
import * as placeDesTendances from './fr/place-des-tendances.json';
import * as printemps from './fr/printemps.json';
import * as privateSportShop from './fr/private-sport-shop.json';
import * as qonto from './fr/qonto.json';
+import * as retif from './fr/retif.json';
import * as rueDuCommerce from './fr/rue-du-commerce.json';
import * as sarenza from './fr/sarenza.json';
import * as sellsy from './fr/sellsy.json';
import * as ubaldi from './fr/ubaldi.json';
+import * as vertbaudet from './fr/vertbaudet.json';
+import * as yvesRocher from './fr/yves-rocher.json';
import * as afasProfit from './nl/afas-profit.json';
import * as anwb from './nl/anwb.json';
import * as bolCom from './nl/bol-com.json';
@@ -1204,6 +1219,7 @@ function withFileSearchBuiltins(adapter: AdapterDefinition): AdapterDefinition {
const RAW_ADAPTERS: AdapterDefinition[] = [
aBoss as unknown as AdapterDefinition,
apaleo as unknown as AdapterDefinition,
+ autodoc as unknown as AdapterDefinition,
billbee as unknown as AdapterDefinition,
billomat as unknown as AdapterDefinition,
buchhaltungsbutler as unknown as AdapterDefinition,
@@ -1285,6 +1301,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
zalandoZds as unknown as AdapterDefinition,
zammad as unknown as AdapterDefinition,
znuny as unknown as AdapterDefinition,
+ zooplus as unknown as AdapterDefinition,
bAndQ as unknown as AdapterDefinition,
brandalley as unknown as AdapterDefinition,
companiesHouse as unknown as AdapterDefinition,
@@ -1779,6 +1796,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
productboard as unknown as AdapterDefinition,
promUa as unknown as AdapterDefinition,
proxmox as unknown as AdapterDefinition,
+ publicGr as unknown as AdapterDefinition,
qnapFileSearch as unknown as AdapterDefinition,
quaderno as unknown as AdapterDefinition,
quickbooksOnline as unknown as AdapterDefinition,
@@ -1810,6 +1828,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
rubrik as unknown as AdapterDefinition,
s3FileSearch as unknown as AdapterDefinition,
sageBusinessCloud as unknown as AdapterDefinition,
+ saks as unknown as AdapterDefinition,
salesflare as unknown as AdapterDefinition,
salesforce as unknown as AdapterDefinition,
salesforceCommerceCloud as unknown as AdapterDefinition,
@@ -1903,6 +1922,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
telnyx as unknown as AdapterDefinition,
temu as unknown as AdapterDefinition,
tezga as unknown as AdapterDefinition,
+ theKnot as unknown as AdapterDefinition,
theOddsApi as unknown as AdapterDefinition,
threads as unknown as AdapterDefinition,
ticktick as unknown as AdapterDefinition,
@@ -1928,6 +1948,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
untappd as unknown as AdapterDefinition,
ups as unknown as AdapterDefinition,
uptimeRobot as unknown as AdapterDefinition,
+ urbn as unknown as AdapterDefinition,
usps as unknown as AdapterDefinition,
uzumMarket as unknown as AdapterDefinition,
vapi as unknown as AdapterDefinition,
@@ -1991,6 +2012,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
zuora as unknown as AdapterDefinition,
bling as unknown as AdapterDefinition,
digisac as unknown as AdapterDefinition,
+ kabum as unknown as AdapterDefinition,
lojaIntegrada as unknown as AdapterDefinition,
magalu as unknown as AdapterDefinition,
mercadoLibre as unknown as AdapterDefinition,
@@ -2028,8 +2050,11 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
holded as unknown as AdapterDefinition,
miravia as unknown as AdapterDefinition,
pccomponentes as unknown as AdapterDefinition,
+ phoneHouse as unknown as AdapterDefinition,
+ planetaHuerto as unknown as AdapterDefinition,
quipu as unknown as AdapterDefinition,
sprinter as unknown as AdapterDefinition,
+ tiendanimal as unknown as AdapterDefinition,
atlasForMen as unknown as AdapterDefinition,
auchan as unknown as AdapterDefinition,
axonaut as unknown as AdapterDefinition,
@@ -2048,19 +2073,24 @@ const RAW_ADAPTERS: AdapterDefinition[] = [
laPoste as unknown as AdapterDefinition,
laRedoute as unknown as AdapterDefinition,
ldlc as unknown as AdapterDefinition,
+ macway as unknown as AdapterDefinition,
manomano as unknown as AdapterDefinition,
natureEtDecouvertes as unknown as AdapterDefinition,
octopia as unknown as AdapterDefinition,
+ orangeMarketplace as unknown as AdapterDefinition,
pennylane as unknown as AdapterDefinition,
pixmania as unknown as AdapterDefinition,
placeDesTendances as unknown as AdapterDefinition,
printemps as unknown as AdapterDefinition,
privateSportShop as unknown as AdapterDefinition,
qonto as unknown as AdapterDefinition,
+ retif as unknown as AdapterDefinition,
rueDuCommerce as unknown as AdapterDefinition,
sarenza as unknown as AdapterDefinition,
sellsy as unknown as AdapterDefinition,
ubaldi as unknown as AdapterDefinition,
+ vertbaudet as unknown as AdapterDefinition,
+ yvesRocher as unknown as AdapterDefinition,
afasProfit as unknown as AdapterDefinition,
anwb as unknown as AdapterDefinition,
bolCom as unknown as AdapterDefinition,
diff --git a/packages/backend/src/adapters/de/autodoc.json b/packages/backend/src/adapters/de/autodoc.json
new file mode 100644
index 000000000..8e7be6c1b
--- /dev/null
+++ b/packages/backend/src/adapters/de/autodoc.json
@@ -0,0 +1,2033 @@
+{
+ "slug": "autodoc",
+ "name": "AUTODOC Marketplace",
+ "aliases": [
+ "AUTODOC seller API",
+ "Autodoc Marktplatz",
+ "Autodoc place de marché",
+ "auto-doc.fr marketplace",
+ "AUTODOC Mirakl",
+ "autodocde-prod.mirakl.net"
+ ],
+ "description": "Run your shop on the AUTODOC marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France, Germany, Austria, Belgium, Italy, Luxembourg, the Netherlands, Poland and 3 more countries; sign in with the shop API key from your AUTODOC seller back office.",
+ "instructions": "## AUTODOC Marketplace\nRun your shop on the AUTODOC marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and AUTODOC, returns, order documents, invoices and transactions. The connector calls the AUTODOC seller platform at `https://autodocde-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France, Germany, Austria, Belgium, Italy, Luxembourg, the Netherlands, Poland, Portugal, Spain and the United Kingdom. One shop sells to all euro countries; selling in the United Kingdom in pounds needs a separate seller account with its own API key.\n\n**Who can sell**: AUTODOC selects sellers of vehicle spare parts and accessories in new condition; apply with the Join our marketplace button on its marketplace page or by e-mail (`marketplace-seller-recruitment@autodoc.eu`). Sellers must be registered in the EU with an EU warehouse and valid VAT ids (or the VAT one-stop shop). AUTODOC charges EUR 30 a month plus a commission by category. The connector needs a seller account that AUTODOC has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the AUTODOC seller back office: `https://autodocde-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `AUTODOC_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `AUTODOC_SHOP_ID` empty. Only if your user manages several shops on AUTODOC, set `AUTODOC_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `autodoc_get_account`). Without it your default shop is used.\n4. Install and run `autodoc_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the AUTODOC seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `autodoc_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `autodoc_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `autodoc_list_offers` for prices and stock and `autodoc_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `autodoc_get_products` looks products up in the AUTODOC catalog by EAN or another reference and returns the marketplace product SKU; `autodoc_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `autodoc_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `autodoc_update_tracking` stores the carrier and tracking number (carrier codes come from `autodoc_list_carriers`) and `autodoc_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `autodoc_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `autodoc_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `autodoc_list_order_documents`.\n\n**Writes: confirm first.** `autodoc_accept_order`, `autodoc_update_tracking`, `autodoc_ship_order`, `autodoc_resolve_incident`, `autodoc_accept_return`, `autodoc_receive_return`, `autodoc_update_offers`, `autodoc_reply_thread`, `autodoc_create_order_thread` and `autodoc_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `autodoc_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `autodoc_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`autodoc_get_offer` or `autodoc_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `autodoc_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `autodoc_list_offer_conditions`, logistic class codes from `autodoc_list_logistic_classes`.\n\n**File imports**: `autodoc_import_products` (P41) and `autodoc_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format AUTODOC asks for; the connector downloads it and uploads it to AUTODOC. Track them with `autodoc_list_product_imports` / `autodoc_get_product_import` and `autodoc_list_offer_imports` / `autodoc_get_offer_import`.\n\n**Returns**: `autodoc_list_returns` (RT11) lists return requests. Where AUTODOC lets the shop decide, `autodoc_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `autodoc_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `autodoc_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `autodoc_get_thread` reads one with its messages, `autodoc_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is AUTODOC) and `autodoc_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `autodoc_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `autodoc_list_invoices` (IV01) lists the accounting documents AUTODOC issues to the shop and `autodoc_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If AUTODOC uses Enhanced Seller Invoicing, IV01 returns no new documents; use `autodoc_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `autodoc_export_offers`, poll `autodoc_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `autodoc_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `autodoc_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `autodoc_get_account` and the same `shop_id`. Without `shop_id` a call uses `AUTODOC_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `autodoc_list_channels` (country sites), `autodoc_list_carriers`, `autodoc_list_shipping_zones`, `autodoc_list_shipping_methods` and `autodoc_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and AUTODOC can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `autodoc_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "de",
+ "category": "e-commerce",
+ "icon": "autodoc",
+ "docsUrl": "https://www.autodoc.co.uk/services/marketplace",
+ "requiredEnvVars": [
+ "AUTODOC_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "AUTODOC_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with AUTODOC and access to its seller back office to generate the shop API key. AUTODOC selects sellers of vehicle spare parts and accessories in new condition; apply with the Join our marketplace button on its marketplace page or by e-mail (`marketplace-seller-recruitment@autodoc.eu`). Sellers must be registered in the EU with an EU warehouse and valid VAT ids (or the VAT one-stop shop). AUTODOC charges EUR 30 a month plus a commission by category.",
+ "envVarMeta": {
+ "AUTODOC_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "AUTODOC seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://autodocde-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "AUTODOC_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on AUTODOC: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "AUTODOC refused the API key. Check that AUTODOC_API_KEY is the shop key from your AUTODOC seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set AUTODOC_SHOP_ID to a shop you manage.",
+ "404": "The AUTODOC seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://autodocde-prod.mirakl.net: AUTODOC may have moved its seller back office.",
+ "rate_limited": "AUTODOC is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "autodoc_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A AUTODOC seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your AUTODOC seller account",
+ "body": "Sign in to the AUTODOC seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the AUTODOC seller back office",
+ "url": "https://autodocde-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask AUTODOC (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "AUTODOC selects sellers of vehicle spare parts and accessories in new condition; apply with the Join our marketplace button on its marketplace page or by e-mail (`marketplace-seller-recruitment@autodoc.eu`). Sellers must be registered in the EU with an EU warehouse and valid VAT ids (or the VAT one-stop shop). AUTODOC charges EUR 30 a month plus a commission by category. See [the AUTODOC seller page](https://www.autodoc.co.uk/services/marketplace)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "AUTODOC_API_KEY",
+ "AUTODOC_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "AUTODOC refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "AUTODOC Marketplace",
+ "type": "REST",
+ "baseUrl": "https://autodocde-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{AUTODOC_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "autodoc_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use autodoc_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see autodoc_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before autodoc_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in autodoc_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from autodoc_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by autodoc_update_offers or autodoc_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by autodoc_update_offers or autodoc_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging autodoc_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll autodoc_get_offer_export_status about once a minute until COMPLETED, then read each file with autodoc_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from autodoc_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "autodoc_get_offer_export_status",
+ "description": "Status of an offer export started with autodoc_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to autodoc_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by autodoc_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by autodoc_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by autodoc_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references AUTODOC uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_threads",
+ "description": "List message threads (M11) with customers and AUTODOC: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with AUTODOC)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from autodoc_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in autodoc_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_invoices",
+ "description": "List the accounting documents AUTODOC issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_document_requests",
+ "description": "List accounting document requests (DR11), used when AUTODOC runs Enhanced Seller Invoicing: invoices and credit notes that AUTODOC or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by AUTODOC (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in autodoc_list_orders and autodoc_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in autodoc_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "autodoc_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from autodoc_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from autodoc_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from autodoc_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in autodoc_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in autodoc_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with autodoc_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with autodoc_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from autodoc_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or AUTODOC. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from autodoc_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (AUTODOC) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "autodoc_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, AUTODOC or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (AUTODOC) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from autodoc_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "autodoc_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from autodoc_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in autodoc_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from autodoc_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when AUTODOC handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from autodoc_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from autodoc_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "autodoc_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format AUTODOC asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with autodoc_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format AUTODOC defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "autodoc_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format AUTODOC asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with autodoc_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by autodoc_get_account, also shown in the back office). Leave it out to use AUTODOC_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "AUTODOC_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/de/autodoc.live.spec.ts b/packages/backend/src/adapters/de/autodoc.live.spec.ts
new file mode 100644
index 000000000..9a5f3de00
--- /dev/null
+++ b/packages/backend/src/adapters/de/autodoc.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './autodoc.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_AUTODOC_LIVE=1 (GET /api/version needs no key; the shop reads need AUTODOC_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'autodoc', hosts: ['autodocde-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/de/zooplus.json b/packages/backend/src/adapters/de/zooplus.json
new file mode 100644
index 000000000..d0e898a60
--- /dev/null
+++ b/packages/backend/src/adapters/de/zooplus.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "zooplus",
+ "name": "zooplus Marketplace",
+ "aliases": [
+ "zooplus seller API",
+ "zooplus Marktplatz",
+ "zooplus place de marché",
+ "zooplus marketplace partner",
+ "zooplus Mirakl"
+ ],
+ "description": "Run your shop on the zooplus marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Germany, France and Spain; sign in with the shop API key from your zooplus seller back office.",
+ "instructions": "## zooplus Marketplace\nRun your shop on the zooplus marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and zooplus, returns, order documents, invoices and transactions. The connector calls the zooplus seller platform at `https://zooplus-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Germany, France and Spain.\n\n**Who can sell**: zooplus reviews each application (apply now form on its marketplace page, questions to `info-marketplace@zooplus.com`), followed by an identity and company check. Sellers need an EU-registered business with an EU VAT number and stock in the EU, and must give customers a free return label. There is no subscription fee for the first three months. The connector needs a seller account that zooplus has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the zooplus seller back office: `https://zooplus-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `ZOOPLUS_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `ZOOPLUS_SHOP_ID` empty. Only if your user manages several shops on zooplus, set `ZOOPLUS_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `zooplus_get_account`). Without it your default shop is used.\n4. Install and run `zooplus_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the zooplus seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `zooplus_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `zooplus_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `zooplus_list_offers` for prices and stock and `zooplus_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `zooplus_get_products` looks products up in the zooplus catalog by EAN or another reference and returns the marketplace product SKU; `zooplus_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `zooplus_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `zooplus_update_tracking` stores the carrier and tracking number (carrier codes come from `zooplus_list_carriers`) and `zooplus_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `zooplus_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `zooplus_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `zooplus_list_order_documents`.\n\n**Writes: confirm first.** `zooplus_accept_order`, `zooplus_update_tracking`, `zooplus_ship_order`, `zooplus_resolve_incident`, `zooplus_accept_return`, `zooplus_receive_return`, `zooplus_update_offers`, `zooplus_reply_thread`, `zooplus_create_order_thread` and `zooplus_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `zooplus_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `zooplus_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`zooplus_get_offer` or `zooplus_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `zooplus_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `zooplus_list_offer_conditions`, logistic class codes from `zooplus_list_logistic_classes`.\n\n**File imports**: `zooplus_import_products` (P41) and `zooplus_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format zooplus asks for; the connector downloads it and uploads it to zooplus. Track them with `zooplus_list_product_imports` / `zooplus_get_product_import` and `zooplus_list_offer_imports` / `zooplus_get_offer_import`.\n\n**Returns**: `zooplus_list_returns` (RT11) lists return requests. Where zooplus lets the shop decide, `zooplus_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `zooplus_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `zooplus_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `zooplus_get_thread` reads one with its messages, `zooplus_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is zooplus) and `zooplus_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `zooplus_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `zooplus_list_invoices` (IV01) lists the accounting documents zooplus issues to the shop and `zooplus_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If zooplus uses Enhanced Seller Invoicing, IV01 returns no new documents; use `zooplus_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `zooplus_export_offers`, poll `zooplus_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `zooplus_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `zooplus_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `zooplus_get_account` and the same `shop_id`. Without `shop_id` a call uses `ZOOPLUS_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `zooplus_list_channels` (country sites), `zooplus_list_carriers`, `zooplus_list_shipping_zones`, `zooplus_list_shipping_methods` and `zooplus_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and zooplus can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `zooplus_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "de",
+ "category": "e-commerce",
+ "icon": "zooplus",
+ "docsUrl": "https://www.zooplus.com/info/about/marketplace",
+ "requiredEnvVars": [
+ "ZOOPLUS_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "ZOOPLUS_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with zooplus and access to its seller back office to generate the shop API key. zooplus reviews each application (apply now form on its marketplace page, questions to `info-marketplace@zooplus.com`), followed by an identity and company check. Sellers need an EU-registered business with an EU VAT number and stock in the EU, and must give customers a free return label. There is no subscription fee for the first three months.",
+ "envVarMeta": {
+ "ZOOPLUS_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "zooplus seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://zooplus-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "ZOOPLUS_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on zooplus: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "zooplus refused the API key. Check that ZOOPLUS_API_KEY is the shop key from your zooplus seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set ZOOPLUS_SHOP_ID to a shop you manage.",
+ "404": "The zooplus seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://zooplus-prod.mirakl.net: zooplus may have moved its seller back office.",
+ "rate_limited": "zooplus is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "zooplus_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A zooplus seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your zooplus seller account",
+ "body": "Sign in to the zooplus seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the zooplus seller back office",
+ "url": "https://zooplus-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask zooplus (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "zooplus reviews each application (apply now form on its marketplace page, questions to `info-marketplace@zooplus.com`), followed by an identity and company check. Sellers need an EU-registered business with an EU VAT number and stock in the EU, and must give customers a free return label. There is no subscription fee for the first three months. See [the zooplus seller page](https://www.zooplus.com/info/about/marketplace)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "ZOOPLUS_API_KEY",
+ "ZOOPLUS_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "zooplus refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "zooplus Marketplace",
+ "type": "REST",
+ "baseUrl": "https://zooplus-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{ZOOPLUS_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "zooplus_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use zooplus_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see zooplus_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before zooplus_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in zooplus_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from zooplus_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by zooplus_update_offers or zooplus_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by zooplus_update_offers or zooplus_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging zooplus_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll zooplus_get_offer_export_status about once a minute until COMPLETED, then read each file with zooplus_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from zooplus_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "zooplus_get_offer_export_status",
+ "description": "Status of an offer export started with zooplus_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to zooplus_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by zooplus_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by zooplus_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by zooplus_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references zooplus uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_threads",
+ "description": "List message threads (M11) with customers and zooplus: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with zooplus)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from zooplus_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in zooplus_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_invoices",
+ "description": "List the accounting documents zooplus issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_document_requests",
+ "description": "List accounting document requests (DR11), used when zooplus runs Enhanced Seller Invoicing: invoices and credit notes that zooplus or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by zooplus (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in zooplus_list_orders and zooplus_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in zooplus_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "zooplus_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from zooplus_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from zooplus_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from zooplus_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in zooplus_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in zooplus_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with zooplus_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with zooplus_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from zooplus_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or zooplus. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from zooplus_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (zooplus) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "zooplus_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, zooplus or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (zooplus) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from zooplus_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "zooplus_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from zooplus_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in zooplus_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from zooplus_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when zooplus handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from zooplus_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from zooplus_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "zooplus_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format zooplus asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with zooplus_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format zooplus defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "zooplus_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format zooplus asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with zooplus_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by zooplus_get_account, also shown in the back office). Leave it out to use ZOOPLUS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "ZOOPLUS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/de/zooplus.live.spec.ts b/packages/backend/src/adapters/de/zooplus.live.spec.ts
new file mode 100644
index 000000000..1456357d9
--- /dev/null
+++ b/packages/backend/src/adapters/de/zooplus.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './zooplus.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_ZOOPLUS_LIVE=1 (GET /api/version needs no key; the shop reads need ZOOPLUS_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'zooplus', hosts: ['zooplus-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/es/phone-house.json b/packages/backend/src/adapters/es/phone-house.json
new file mode 100644
index 000000000..0c566e08c
--- /dev/null
+++ b/packages/backend/src/adapters/es/phone-house.json
@@ -0,0 +1,2034 @@
+{
+ "slug": "phone-house",
+ "name": "Phone House Marketplace",
+ "aliases": [
+ "The Phone House",
+ "Phone House Spain",
+ "Phone House España",
+ "Phone House seller API",
+ "Phone House vendedores",
+ "Phone House Mirakl",
+ "phonehouse.es marketplace"
+ ],
+ "description": "Run your shop on the Phone House marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Spain; sign in with the shop API key from your Phone House seller back office.",
+ "instructions": "## Phone House Marketplace\nRun your shop on the Phone House marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Phone House, returns, order documents, invoices and transactions. The connector calls the Phone House seller platform at `https://phonehousespain-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Spain.\n\n**Who can sell**: Phone House selects its sellers and reviews each application. Sellers ship their orders themselves; Phone House measures product quality, price, delivery speed and logistics. Products need an EAN, and complete specifications when the Phone House catalogue does not know the product yet. The connector needs a seller account that Phone House has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Phone House seller back office: `https://phonehousespain-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `PHONE_HOUSE_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `PHONE_HOUSE_SHOP_ID` empty. Only if your user manages several shops on Phone House, set `PHONE_HOUSE_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `phone_house_get_account`). Without it your default shop is used.\n4. Install and run `phone_house_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Phone House seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `phone_house_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `phone_house_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `phone_house_list_offers` for prices and stock and `phone_house_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `phone_house_get_products` looks products up in the Phone House catalog by EAN or another reference and returns the marketplace product SKU; `phone_house_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `phone_house_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `phone_house_update_tracking` stores the carrier and tracking number (carrier codes come from `phone_house_list_carriers`) and `phone_house_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `phone_house_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `phone_house_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `phone_house_list_order_documents`.\n\n**Writes: confirm first.** `phone_house_accept_order`, `phone_house_update_tracking`, `phone_house_ship_order`, `phone_house_resolve_incident`, `phone_house_accept_return`, `phone_house_receive_return`, `phone_house_update_offers`, `phone_house_reply_thread`, `phone_house_create_order_thread` and `phone_house_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `phone_house_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `phone_house_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`phone_house_get_offer` or `phone_house_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `phone_house_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `phone_house_list_offer_conditions`, logistic class codes from `phone_house_list_logistic_classes`.\n\n**File imports**: `phone_house_import_products` (P41) and `phone_house_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Phone House asks for; the connector downloads it and uploads it to Phone House. Track them with `phone_house_list_product_imports` / `phone_house_get_product_import` and `phone_house_list_offer_imports` / `phone_house_get_offer_import`.\n\n**Returns**: `phone_house_list_returns` (RT11) lists return requests. Where Phone House lets the shop decide, `phone_house_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `phone_house_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `phone_house_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `phone_house_get_thread` reads one with its messages, `phone_house_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Phone House) and `phone_house_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `phone_house_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `phone_house_list_invoices` (IV01) lists the accounting documents Phone House issues to the shop and `phone_house_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Phone House uses Enhanced Seller Invoicing, IV01 returns no new documents; use `phone_house_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `phone_house_export_offers`, poll `phone_house_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `phone_house_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `phone_house_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `phone_house_get_account` and the same `shop_id`. Without `shop_id` a call uses `PHONE_HOUSE_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `phone_house_list_channels` (country sites), `phone_house_list_carriers`, `phone_house_list_shipping_zones`, `phone_house_list_shipping_methods` and `phone_house_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Phone House can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `phone_house_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "es",
+ "category": "e-commerce",
+ "icon": "phone-house",
+ "docsUrl": "https://phonehousespain-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "PHONE_HOUSE_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "PHONE_HOUSE_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Phone House and access to its seller back office to generate the shop API key. Phone House selects its sellers and reviews each application. Sellers ship their orders themselves; Phone House measures product quality, price, delivery speed and logistics. Products need an EAN, and complete specifications when the Phone House catalogue does not know the product yet.",
+ "envVarMeta": {
+ "PHONE_HOUSE_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Phone House seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://phonehousespain-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "PHONE_HOUSE_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Phone House: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Phone House refused the API key. Check that PHONE_HOUSE_API_KEY is the shop key from your Phone House seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set PHONE_HOUSE_SHOP_ID to a shop you manage.",
+ "404": "The Phone House seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://phonehousespain-prod.mirakl.net: Phone House may have moved its seller back office.",
+ "rate_limited": "Phone House is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "phone_house_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Phone House seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Phone House seller account",
+ "body": "Sign in to the Phone House seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Phone House seller back office",
+ "url": "https://phonehousespain-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Phone House (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Phone House selects its sellers and reviews each application. Sellers ship their orders themselves; Phone House measures product quality, price, delivery speed and logistics. Products need an EAN, and complete specifications when the Phone House catalogue does not know the product yet."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "PHONE_HOUSE_API_KEY",
+ "PHONE_HOUSE_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Phone House refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Phone House Marketplace",
+ "type": "REST",
+ "baseUrl": "https://phonehousespain-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{PHONE_HOUSE_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "phone_house_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use phone_house_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see phone_house_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before phone_house_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in phone_house_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from phone_house_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by phone_house_update_offers or phone_house_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by phone_house_update_offers or phone_house_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging phone_house_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll phone_house_get_offer_export_status about once a minute until COMPLETED, then read each file with phone_house_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from phone_house_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "phone_house_get_offer_export_status",
+ "description": "Status of an offer export started with phone_house_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to phone_house_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by phone_house_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by phone_house_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by phone_house_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Phone House uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_threads",
+ "description": "List message threads (M11) with customers and Phone House: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Phone House)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from phone_house_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in phone_house_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_invoices",
+ "description": "List the accounting documents Phone House issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Phone House runs Enhanced Seller Invoicing: invoices and credit notes that Phone House or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Phone House (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in phone_house_list_orders and phone_house_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in phone_house_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "phone_house_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from phone_house_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from phone_house_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from phone_house_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in phone_house_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in phone_house_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with phone_house_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with phone_house_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from phone_house_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Phone House. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from phone_house_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Phone House) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "phone_house_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Phone House or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Phone House) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from phone_house_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "phone_house_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from phone_house_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in phone_house_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from phone_house_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Phone House handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from phone_house_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from phone_house_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "phone_house_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Phone House asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with phone_house_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Phone House defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "phone_house_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Phone House asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with phone_house_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by phone_house_get_account, also shown in the back office). Leave it out to use PHONE_HOUSE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PHONE_HOUSE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/es/phone-house.live.spec.ts b/packages/backend/src/adapters/es/phone-house.live.spec.ts
new file mode 100644
index 000000000..db35c8d37
--- /dev/null
+++ b/packages/backend/src/adapters/es/phone-house.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './phone-house.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_PHONE_HOUSE_LIVE=1 (GET /api/version needs no key; the shop reads need PHONE_HOUSE_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'phone-house', hosts: ['phonehousespain-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/es/planeta-huerto.json b/packages/backend/src/adapters/es/planeta-huerto.json
new file mode 100644
index 000000000..50a8fa238
--- /dev/null
+++ b/packages/backend/src/adapters/es/planeta-huerto.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "planeta-huerto",
+ "name": "Planeta Huerto Marketplace",
+ "aliases": [
+ "Planetahuerto",
+ "Planeta Huerto seller API",
+ "Planeta Huerto vendedores",
+ "Planeta Huerto Mirakl",
+ "planetahuerto.es marketplace"
+ ],
+ "description": "Run your shop on the Planeta Huerto marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Spain and Portugal; sign in with the shop API key from your Planeta Huerto seller back office.",
+ "instructions": "## Planeta Huerto Marketplace\nRun your shop on the Planeta Huerto marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Planeta Huerto, returns, order documents, invoices and transactions. The connector calls the Planeta Huerto seller platform at `https://planetahuerto-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Spain and Portugal. Planeta Huerto sells on planetahuerto.es and planetahuerto.pt; product texts are needed in Spanish and Portuguese.\n\n**Who can sell**: Planeta Huerto sells healthy and sustainable products (food, cleaning, cosmetics, supplements, baby, pets, garden and home): write to `altas@planetahuerto.es` and the team sends the registration link. Registration needs the company tax id and bank details. There is no fixed term and no minimum stock; Planeta Huerto charges a commission per sale on the final price including VAT, by category. Sellers keep their stock and ship each order themselves; every product needs an EAN. The connector needs a seller account that Planeta Huerto has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Planeta Huerto seller back office: `https://planetahuerto-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `PLANETA_HUERTO_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `PLANETA_HUERTO_SHOP_ID` empty. Only if your user manages several shops on Planeta Huerto, set `PLANETA_HUERTO_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `planeta_huerto_get_account`). Without it your default shop is used.\n4. Install and run `planeta_huerto_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Planeta Huerto seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `planeta_huerto_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `planeta_huerto_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `planeta_huerto_list_offers` for prices and stock and `planeta_huerto_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `planeta_huerto_get_products` looks products up in the Planeta Huerto catalog by EAN or another reference and returns the marketplace product SKU; `planeta_huerto_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `planeta_huerto_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `planeta_huerto_update_tracking` stores the carrier and tracking number (carrier codes come from `planeta_huerto_list_carriers`) and `planeta_huerto_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `planeta_huerto_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `planeta_huerto_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `planeta_huerto_list_order_documents`.\n\n**Writes: confirm first.** `planeta_huerto_accept_order`, `planeta_huerto_update_tracking`, `planeta_huerto_ship_order`, `planeta_huerto_resolve_incident`, `planeta_huerto_accept_return`, `planeta_huerto_receive_return`, `planeta_huerto_update_offers`, `planeta_huerto_reply_thread`, `planeta_huerto_create_order_thread` and `planeta_huerto_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `planeta_huerto_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `planeta_huerto_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`planeta_huerto_get_offer` or `planeta_huerto_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `planeta_huerto_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `planeta_huerto_list_offer_conditions`, logistic class codes from `planeta_huerto_list_logistic_classes`.\n\n**File imports**: `planeta_huerto_import_products` (P41) and `planeta_huerto_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Planeta Huerto asks for; the connector downloads it and uploads it to Planeta Huerto. Track them with `planeta_huerto_list_product_imports` / `planeta_huerto_get_product_import` and `planeta_huerto_list_offer_imports` / `planeta_huerto_get_offer_import`.\n\n**Returns**: `planeta_huerto_list_returns` (RT11) lists return requests. Where Planeta Huerto lets the shop decide, `planeta_huerto_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `planeta_huerto_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `planeta_huerto_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `planeta_huerto_get_thread` reads one with its messages, `planeta_huerto_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Planeta Huerto) and `planeta_huerto_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `planeta_huerto_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `planeta_huerto_list_invoices` (IV01) lists the accounting documents Planeta Huerto issues to the shop and `planeta_huerto_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Planeta Huerto uses Enhanced Seller Invoicing, IV01 returns no new documents; use `planeta_huerto_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `planeta_huerto_export_offers`, poll `planeta_huerto_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `planeta_huerto_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `planeta_huerto_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `planeta_huerto_get_account` and the same `shop_id`. Without `shop_id` a call uses `PLANETA_HUERTO_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `planeta_huerto_list_channels` (country sites), `planeta_huerto_list_carriers`, `planeta_huerto_list_shipping_zones`, `planeta_huerto_list_shipping_methods` and `planeta_huerto_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Planeta Huerto can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `planeta_huerto_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "es",
+ "category": "e-commerce",
+ "icon": "planeta-huerto",
+ "docsUrl": "https://www.planetahuerto.es/pages/vender-en-marketplace",
+ "requiredEnvVars": [
+ "PLANETA_HUERTO_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "PLANETA_HUERTO_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Planeta Huerto and access to its seller back office to generate the shop API key. Planeta Huerto sells healthy and sustainable products (food, cleaning, cosmetics, supplements, baby, pets, garden and home): write to `altas@planetahuerto.es` and the team sends the registration link. Registration needs the company tax id and bank details. There is no fixed term and no minimum stock; Planeta Huerto charges a commission per sale on the final price including VAT, by category. Sellers keep their stock and ship each order themselves; every product needs an EAN.",
+ "envVarMeta": {
+ "PLANETA_HUERTO_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Planeta Huerto seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://planetahuerto-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "PLANETA_HUERTO_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Planeta Huerto: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Planeta Huerto refused the API key. Check that PLANETA_HUERTO_API_KEY is the shop key from your Planeta Huerto seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set PLANETA_HUERTO_SHOP_ID to a shop you manage.",
+ "404": "The Planeta Huerto seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://planetahuerto-prod.mirakl.net: Planeta Huerto may have moved its seller back office.",
+ "rate_limited": "Planeta Huerto is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "planeta_huerto_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Planeta Huerto seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Planeta Huerto seller account",
+ "body": "Sign in to the Planeta Huerto seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Planeta Huerto seller back office",
+ "url": "https://planetahuerto-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Planeta Huerto (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Planeta Huerto sells healthy and sustainable products (food, cleaning, cosmetics, supplements, baby, pets, garden and home): write to `altas@planetahuerto.es` and the team sends the registration link. Registration needs the company tax id and bank details. There is no fixed term and no minimum stock; Planeta Huerto charges a commission per sale on the final price including VAT, by category. Sellers keep their stock and ship each order themselves; every product needs an EAN. See [the Planeta Huerto seller page](https://www.planetahuerto.es/pages/vender-en-marketplace)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "PLANETA_HUERTO_API_KEY",
+ "PLANETA_HUERTO_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Planeta Huerto refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Planeta Huerto Marketplace",
+ "type": "REST",
+ "baseUrl": "https://planetahuerto-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{PLANETA_HUERTO_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "planeta_huerto_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use planeta_huerto_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see planeta_huerto_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before planeta_huerto_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in planeta_huerto_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from planeta_huerto_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by planeta_huerto_update_offers or planeta_huerto_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by planeta_huerto_update_offers or planeta_huerto_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging planeta_huerto_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll planeta_huerto_get_offer_export_status about once a minute until COMPLETED, then read each file with planeta_huerto_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from planeta_huerto_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_get_offer_export_status",
+ "description": "Status of an offer export started with planeta_huerto_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to planeta_huerto_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by planeta_huerto_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by planeta_huerto_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by planeta_huerto_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Planeta Huerto uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_threads",
+ "description": "List message threads (M11) with customers and Planeta Huerto: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Planeta Huerto)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from planeta_huerto_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in planeta_huerto_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_invoices",
+ "description": "List the accounting documents Planeta Huerto issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Planeta Huerto runs Enhanced Seller Invoicing: invoices and credit notes that Planeta Huerto or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Planeta Huerto (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in planeta_huerto_list_orders and planeta_huerto_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in planeta_huerto_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "planeta_huerto_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from planeta_huerto_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from planeta_huerto_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from planeta_huerto_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in planeta_huerto_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in planeta_huerto_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with planeta_huerto_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with planeta_huerto_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from planeta_huerto_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Planeta Huerto. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from planeta_huerto_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Planeta Huerto) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "planeta_huerto_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Planeta Huerto or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Planeta Huerto) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from planeta_huerto_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "planeta_huerto_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from planeta_huerto_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in planeta_huerto_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from planeta_huerto_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Planeta Huerto handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from planeta_huerto_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from planeta_huerto_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "planeta_huerto_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Planeta Huerto asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with planeta_huerto_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Planeta Huerto defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "planeta_huerto_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Planeta Huerto asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with planeta_huerto_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by planeta_huerto_get_account, also shown in the back office). Leave it out to use PLANETA_HUERTO_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PLANETA_HUERTO_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/es/planeta-huerto.live.spec.ts b/packages/backend/src/adapters/es/planeta-huerto.live.spec.ts
new file mode 100644
index 000000000..492209897
--- /dev/null
+++ b/packages/backend/src/adapters/es/planeta-huerto.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './planeta-huerto.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_PLANETA_HUERTO_LIVE=1 (GET /api/version needs no key; the shop reads need PLANETA_HUERTO_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'planeta-huerto', hosts: ['planetahuerto-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/es/tiendanimal.json b/packages/backend/src/adapters/es/tiendanimal.json
new file mode 100644
index 000000000..1f56821ee
--- /dev/null
+++ b/packages/backend/src/adapters/es/tiendanimal.json
@@ -0,0 +1,2031 @@
+{
+ "slug": "tiendanimal",
+ "name": "Tiendanimal Marketplace",
+ "aliases": [
+ "Tiendanimal seller API",
+ "Tiendanimal vendedores",
+ "Tiendanimal Mirakl",
+ "tiendanimal.es marketplace"
+ ],
+ "description": "Run your shop on the Tiendanimal marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Spain; sign in with the shop API key from your Tiendanimal seller back office.",
+ "instructions": "## Tiendanimal Marketplace\nRun your shop on the Tiendanimal marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Tiendanimal, returns, order documents, invoices and transactions. The connector calls the Tiendanimal seller platform at `https://tiendanimal-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Spain. Marketplace orders ship within Spain, without the Canary Islands, Ceuta and Melilla.\n\n**Who can sell**: Tiendanimal reviews each application and signs an agreement with each seller: contact its marketplace sales team. Products must be new and carry an EAN, and prices include tax. Sellers ship with their own carrier, accept each order within five working days and take returns within 14 days. The connector needs a seller account that Tiendanimal has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Tiendanimal seller back office: `https://tiendanimal-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `TIENDANIMAL_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `TIENDANIMAL_SHOP_ID` empty. Only if your user manages several shops on Tiendanimal, set `TIENDANIMAL_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `tiendanimal_get_account`). Without it your default shop is used.\n4. Install and run `tiendanimal_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Tiendanimal seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `tiendanimal_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `tiendanimal_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `tiendanimal_list_offers` for prices and stock and `tiendanimal_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `tiendanimal_get_products` looks products up in the Tiendanimal catalog by EAN or another reference and returns the marketplace product SKU; `tiendanimal_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `tiendanimal_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `tiendanimal_update_tracking` stores the carrier and tracking number (carrier codes come from `tiendanimal_list_carriers`) and `tiendanimal_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `tiendanimal_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `tiendanimal_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `tiendanimal_list_order_documents`.\n\n**Writes: confirm first.** `tiendanimal_accept_order`, `tiendanimal_update_tracking`, `tiendanimal_ship_order`, `tiendanimal_resolve_incident`, `tiendanimal_accept_return`, `tiendanimal_receive_return`, `tiendanimal_update_offers`, `tiendanimal_reply_thread`, `tiendanimal_create_order_thread` and `tiendanimal_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `tiendanimal_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `tiendanimal_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`tiendanimal_get_offer` or `tiendanimal_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `tiendanimal_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `tiendanimal_list_offer_conditions`, logistic class codes from `tiendanimal_list_logistic_classes`.\n\n**File imports**: `tiendanimal_import_products` (P41) and `tiendanimal_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Tiendanimal asks for; the connector downloads it and uploads it to Tiendanimal. Track them with `tiendanimal_list_product_imports` / `tiendanimal_get_product_import` and `tiendanimal_list_offer_imports` / `tiendanimal_get_offer_import`.\n\n**Returns**: `tiendanimal_list_returns` (RT11) lists return requests. Where Tiendanimal lets the shop decide, `tiendanimal_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `tiendanimal_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `tiendanimal_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `tiendanimal_get_thread` reads one with its messages, `tiendanimal_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Tiendanimal) and `tiendanimal_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `tiendanimal_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `tiendanimal_list_invoices` (IV01) lists the accounting documents Tiendanimal issues to the shop and `tiendanimal_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Tiendanimal uses Enhanced Seller Invoicing, IV01 returns no new documents; use `tiendanimal_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `tiendanimal_export_offers`, poll `tiendanimal_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `tiendanimal_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `tiendanimal_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `tiendanimal_get_account` and the same `shop_id`. Without `shop_id` a call uses `TIENDANIMAL_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `tiendanimal_list_channels` (country sites), `tiendanimal_list_carriers`, `tiendanimal_list_shipping_zones`, `tiendanimal_list_shipping_methods` and `tiendanimal_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Tiendanimal can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `tiendanimal_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "es",
+ "category": "e-commerce",
+ "icon": "tiendanimal",
+ "docsUrl": "https://tiendanimal-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "TIENDANIMAL_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "TIENDANIMAL_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Tiendanimal and access to its seller back office to generate the shop API key. Tiendanimal reviews each application and signs an agreement with each seller: contact its marketplace sales team. Products must be new and carry an EAN, and prices include tax. Sellers ship with their own carrier, accept each order within five working days and take returns within 14 days.",
+ "envVarMeta": {
+ "TIENDANIMAL_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Tiendanimal seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://tiendanimal-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "TIENDANIMAL_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Tiendanimal: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Tiendanimal refused the API key. Check that TIENDANIMAL_API_KEY is the shop key from your Tiendanimal seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set TIENDANIMAL_SHOP_ID to a shop you manage.",
+ "404": "The Tiendanimal seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://tiendanimal-prod.mirakl.net: Tiendanimal may have moved its seller back office.",
+ "rate_limited": "Tiendanimal is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "tiendanimal_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Tiendanimal seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Tiendanimal seller account",
+ "body": "Sign in to the Tiendanimal seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Tiendanimal seller back office",
+ "url": "https://tiendanimal-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Tiendanimal (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Tiendanimal reviews each application and signs an agreement with each seller: contact its marketplace sales team. Products must be new and carry an EAN, and prices include tax. Sellers ship with their own carrier, accept each order within five working days and take returns within 14 days."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "TIENDANIMAL_API_KEY",
+ "TIENDANIMAL_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Tiendanimal refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Tiendanimal Marketplace",
+ "type": "REST",
+ "baseUrl": "https://tiendanimal-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{TIENDANIMAL_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "tiendanimal_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use tiendanimal_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see tiendanimal_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before tiendanimal_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in tiendanimal_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from tiendanimal_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by tiendanimal_update_offers or tiendanimal_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by tiendanimal_update_offers or tiendanimal_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging tiendanimal_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll tiendanimal_get_offer_export_status about once a minute until COMPLETED, then read each file with tiendanimal_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from tiendanimal_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_get_offer_export_status",
+ "description": "Status of an offer export started with tiendanimal_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to tiendanimal_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by tiendanimal_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by tiendanimal_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by tiendanimal_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Tiendanimal uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_threads",
+ "description": "List message threads (M11) with customers and Tiendanimal: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Tiendanimal)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from tiendanimal_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in tiendanimal_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_invoices",
+ "description": "List the accounting documents Tiendanimal issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Tiendanimal runs Enhanced Seller Invoicing: invoices and credit notes that Tiendanimal or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Tiendanimal (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in tiendanimal_list_orders and tiendanimal_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in tiendanimal_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "tiendanimal_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from tiendanimal_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from tiendanimal_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from tiendanimal_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in tiendanimal_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in tiendanimal_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with tiendanimal_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with tiendanimal_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from tiendanimal_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Tiendanimal. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from tiendanimal_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Tiendanimal) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "tiendanimal_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Tiendanimal or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Tiendanimal) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from tiendanimal_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "tiendanimal_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from tiendanimal_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in tiendanimal_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from tiendanimal_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Tiendanimal handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from tiendanimal_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from tiendanimal_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "tiendanimal_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Tiendanimal asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with tiendanimal_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Tiendanimal defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "tiendanimal_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Tiendanimal asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with tiendanimal_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by tiendanimal_get_account, also shown in the back office). Leave it out to use TIENDANIMAL_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "TIENDANIMAL_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/es/tiendanimal.live.spec.ts b/packages/backend/src/adapters/es/tiendanimal.live.spec.ts
new file mode 100644
index 000000000..61574f04b
--- /dev/null
+++ b/packages/backend/src/adapters/es/tiendanimal.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './tiendanimal.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_TIENDANIMAL_LIVE=1 (GET /api/version needs no key; the shop reads need TIENDANIMAL_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'tiendanimal', hosts: ['tiendanimal-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/fr/macway.json b/packages/backend/src/adapters/fr/macway.json
new file mode 100644
index 000000000..3f51d7b73
--- /dev/null
+++ b/packages/backend/src/adapters/fr/macway.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "macway",
+ "name": "MacWay Marketplace",
+ "aliases": [
+ "MacWay seller API",
+ "MacWay vendeur marketplace",
+ "MacWay place de marché",
+ "MacWay Mirakl",
+ "marketplace.macway.com"
+ ],
+ "description": "Run your shop on the MacWay marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France; sign in with the shop API key from your MacWay seller back office.",
+ "instructions": "## MacWay Marketplace\nRun your shop on the MacWay marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and MacWay, returns, order documents, invoices and transactions. The connector calls the MacWay seller platform at `https://marketplace.macway.com` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France.\n\n**Who can sell**: MacWay selects its sellers, based among other things on buyer ratings, refund rate and response time to customers; contact its marketplace team by e-mail (`contact.marketplace@macway.com`). The marketplace sells Apple-related high-tech products. The connector needs a seller account that MacWay has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the MacWay seller back office: `https://marketplace.macway.com/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `MACWAY_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `MACWAY_SHOP_ID` empty. Only if your user manages several shops on MacWay, set `MACWAY_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `macway_get_account`). Without it your default shop is used.\n4. Install and run `macway_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the MacWay seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `macway_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `macway_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `macway_list_offers` for prices and stock and `macway_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `macway_get_products` looks products up in the MacWay catalog by EAN or another reference and returns the marketplace product SKU; `macway_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `macway_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `macway_update_tracking` stores the carrier and tracking number (carrier codes come from `macway_list_carriers`) and `macway_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `macway_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `macway_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `macway_list_order_documents`.\n\n**Writes: confirm first.** `macway_accept_order`, `macway_update_tracking`, `macway_ship_order`, `macway_resolve_incident`, `macway_accept_return`, `macway_receive_return`, `macway_update_offers`, `macway_reply_thread`, `macway_create_order_thread` and `macway_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `macway_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `macway_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`macway_get_offer` or `macway_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `macway_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `macway_list_offer_conditions`, logistic class codes from `macway_list_logistic_classes`.\n\n**File imports**: `macway_import_products` (P41) and `macway_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format MacWay asks for; the connector downloads it and uploads it to MacWay. Track them with `macway_list_product_imports` / `macway_get_product_import` and `macway_list_offer_imports` / `macway_get_offer_import`.\n\n**Returns**: `macway_list_returns` (RT11) lists return requests. Where MacWay lets the shop decide, `macway_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `macway_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `macway_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `macway_get_thread` reads one with its messages, `macway_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is MacWay) and `macway_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `macway_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `macway_list_invoices` (IV01) lists the accounting documents MacWay issues to the shop and `macway_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If MacWay uses Enhanced Seller Invoicing, IV01 returns no new documents; use `macway_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `macway_export_offers`, poll `macway_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `macway_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `macway_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `macway_get_account` and the same `shop_id`. Without `shop_id` a call uses `MACWAY_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `macway_list_channels` (country sites), `macway_list_carriers`, `macway_list_shipping_zones`, `macway_list_shipping_methods` and `macway_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and MacWay can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `macway_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "fr",
+ "category": "e-commerce",
+ "icon": "macway",
+ "docsUrl": "https://marketplace.macway.com/login",
+ "requiredEnvVars": [
+ "MACWAY_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "MACWAY_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with MacWay and access to its seller back office to generate the shop API key. MacWay selects its sellers, based among other things on buyer ratings, refund rate and response time to customers; contact its marketplace team by e-mail (`contact.marketplace@macway.com`). The marketplace sells Apple-related high-tech products.",
+ "envVarMeta": {
+ "MACWAY_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "MacWay seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://marketplace.macway.com/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "MACWAY_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on MacWay: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "MacWay refused the API key. Check that MACWAY_API_KEY is the shop key from your MacWay seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set MACWAY_SHOP_ID to a shop you manage.",
+ "404": "The MacWay seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://marketplace.macway.com: MacWay may have moved its seller back office.",
+ "rate_limited": "MacWay is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "macway_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A MacWay seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your MacWay seller account",
+ "body": "Sign in to the MacWay seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the MacWay seller back office",
+ "url": "https://marketplace.macway.com/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask MacWay (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "MacWay selects its sellers, based among other things on buyer ratings, refund rate and response time to customers; contact its marketplace team by e-mail (`contact.marketplace@macway.com`). The marketplace sells Apple-related high-tech products."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "MACWAY_API_KEY",
+ "MACWAY_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "MacWay refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "MacWay Marketplace",
+ "type": "REST",
+ "baseUrl": "https://marketplace.macway.com/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{MACWAY_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "macway_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use macway_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see macway_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before macway_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in macway_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from macway_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by macway_update_offers or macway_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by macway_update_offers or macway_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging macway_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll macway_get_offer_export_status about once a minute until COMPLETED, then read each file with macway_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from macway_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "macway_get_offer_export_status",
+ "description": "Status of an offer export started with macway_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to macway_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by macway_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by macway_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by macway_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references MacWay uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_threads",
+ "description": "List message threads (M11) with customers and MacWay: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with MacWay)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from macway_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in macway_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_invoices",
+ "description": "List the accounting documents MacWay issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_document_requests",
+ "description": "List accounting document requests (DR11), used when MacWay runs Enhanced Seller Invoicing: invoices and credit notes that MacWay or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by MacWay (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in macway_list_orders and macway_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in macway_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "macway_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from macway_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from macway_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from macway_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in macway_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in macway_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with macway_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with macway_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from macway_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or MacWay. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from macway_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (MacWay) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "macway_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, MacWay or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (MacWay) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from macway_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "macway_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from macway_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in macway_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from macway_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when MacWay handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from macway_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from macway_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "macway_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format MacWay asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with macway_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format MacWay defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "macway_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format MacWay asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with macway_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by macway_get_account, also shown in the back office). Leave it out to use MACWAY_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "MACWAY_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/fr/macway.live.spec.ts b/packages/backend/src/adapters/fr/macway.live.spec.ts
new file mode 100644
index 000000000..1b9f2d530
--- /dev/null
+++ b/packages/backend/src/adapters/fr/macway.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './macway.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_MACWAY_LIVE=1 (GET /api/version needs no key; the shop reads need MACWAY_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'macway', hosts: ['marketplace.macway.com'] });
diff --git a/packages/backend/src/adapters/fr/orange-marketplace.json b/packages/backend/src/adapters/fr/orange-marketplace.json
new file mode 100644
index 000000000..0d64c45ad
--- /dev/null
+++ b/packages/backend/src/adapters/fr/orange-marketplace.json
@@ -0,0 +1,2033 @@
+{
+ "slug": "orange-marketplace",
+ "name": "Orange Marketplace",
+ "aliases": [
+ "Orange France marketplace",
+ "Marketplace Orange",
+ "Sosh marketplace",
+ "Orange vendeur marketplace",
+ "boutique.orange.fr marketplace",
+ "Orange Mirakl"
+ ],
+ "description": "Run your shop on the Orange marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France; sign in with the shop API key from your Orange seller back office.",
+ "instructions": "## Orange Marketplace\nRun your shop on the Orange marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Orange, returns, order documents, invoices and transactions. The connector calls the Orange seller platform at `https://orangefr-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France.\n\n**Who can sell**: Orange selects its sellers after a due diligence check (finance, CSR, compliance). It asks for at least one year of marketplace sales and two closed financial years, a rating of 3.9/5 or more on other marketplaces with 100 reviews or 1,000 orders in the last 12 months, a warehouse in the EU and customer service in French within 24 business hours. The fee is a commission per order plus EUR 49.99 a month. The connector needs a seller account that Orange has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Orange seller back office: `https://orangefr-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `ORANGE_MARKETPLACE_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `ORANGE_MARKETPLACE_SHOP_ID` empty. Only if your user manages several shops on Orange, set `ORANGE_MARKETPLACE_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `orange_marketplace_get_account`). Without it your default shop is used.\n4. Install and run `orange_marketplace_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Orange seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `orange_marketplace_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `orange_marketplace_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `orange_marketplace_list_offers` for prices and stock and `orange_marketplace_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `orange_marketplace_get_products` looks products up in the Orange catalog by EAN or another reference and returns the marketplace product SKU; `orange_marketplace_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `orange_marketplace_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `orange_marketplace_update_tracking` stores the carrier and tracking number (carrier codes come from `orange_marketplace_list_carriers`) and `orange_marketplace_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `orange_marketplace_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `orange_marketplace_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `orange_marketplace_list_order_documents`.\n\n**Writes: confirm first.** `orange_marketplace_accept_order`, `orange_marketplace_update_tracking`, `orange_marketplace_ship_order`, `orange_marketplace_resolve_incident`, `orange_marketplace_accept_return`, `orange_marketplace_receive_return`, `orange_marketplace_update_offers`, `orange_marketplace_reply_thread`, `orange_marketplace_create_order_thread` and `orange_marketplace_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `orange_marketplace_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `orange_marketplace_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`orange_marketplace_get_offer` or `orange_marketplace_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `orange_marketplace_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `orange_marketplace_list_offer_conditions`, logistic class codes from `orange_marketplace_list_logistic_classes`.\n\n**File imports**: `orange_marketplace_import_products` (P41) and `orange_marketplace_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Orange asks for; the connector downloads it and uploads it to Orange. Track them with `orange_marketplace_list_product_imports` / `orange_marketplace_get_product_import` and `orange_marketplace_list_offer_imports` / `orange_marketplace_get_offer_import`.\n\n**Returns**: `orange_marketplace_list_returns` (RT11) lists return requests. Where Orange lets the shop decide, `orange_marketplace_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `orange_marketplace_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `orange_marketplace_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `orange_marketplace_get_thread` reads one with its messages, `orange_marketplace_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Orange) and `orange_marketplace_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `orange_marketplace_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `orange_marketplace_list_invoices` (IV01) lists the accounting documents Orange issues to the shop and `orange_marketplace_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Orange uses Enhanced Seller Invoicing, IV01 returns no new documents; use `orange_marketplace_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `orange_marketplace_export_offers`, poll `orange_marketplace_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `orange_marketplace_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `orange_marketplace_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `orange_marketplace_get_account` and the same `shop_id`. Without `shop_id` a call uses `ORANGE_MARKETPLACE_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `orange_marketplace_list_channels` (country sites), `orange_marketplace_list_carriers`, `orange_marketplace_list_shipping_zones`, `orange_marketplace_list_shipping_methods` and `orange_marketplace_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Orange can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `orange_marketplace_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "fr",
+ "category": "e-commerce",
+ "icon": "orange-marketplace",
+ "docsUrl": "https://boutique.orange.fr/information/marketplace/grow-your-business-on-orange-marketplace",
+ "requiredEnvVars": [
+ "ORANGE_MARKETPLACE_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "ORANGE_MARKETPLACE_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Orange and access to its seller back office to generate the shop API key. Orange selects its sellers after a due diligence check (finance, CSR, compliance). It asks for at least one year of marketplace sales and two closed financial years, a rating of 3.9/5 or more on other marketplaces with 100 reviews or 1,000 orders in the last 12 months, a warehouse in the EU and customer service in French within 24 business hours. The fee is a commission per order plus EUR 49.99 a month.",
+ "envVarMeta": {
+ "ORANGE_MARKETPLACE_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Orange seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://orangefr-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "ORANGE_MARKETPLACE_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Orange: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Orange refused the API key. Check that ORANGE_MARKETPLACE_API_KEY is the shop key from your Orange seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set ORANGE_MARKETPLACE_SHOP_ID to a shop you manage.",
+ "404": "The Orange seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://orangefr-prod.mirakl.net: Orange may have moved its seller back office.",
+ "rate_limited": "Orange is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "orange_marketplace_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Orange seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Orange seller account",
+ "body": "Sign in to the Orange seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Orange seller back office",
+ "url": "https://orangefr-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Orange (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Orange selects its sellers after a due diligence check (finance, CSR, compliance). It asks for at least one year of marketplace sales and two closed financial years, a rating of 3.9/5 or more on other marketplaces with 100 reviews or 1,000 orders in the last 12 months, a warehouse in the EU and customer service in French within 24 business hours. The fee is a commission per order plus EUR 49.99 a month. See [the Orange seller page](https://boutique.orange.fr/information/marketplace/grow-your-business-on-orange-marketplace)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "ORANGE_MARKETPLACE_API_KEY",
+ "ORANGE_MARKETPLACE_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Orange refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Orange Marketplace",
+ "type": "REST",
+ "baseUrl": "https://orangefr-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{ORANGE_MARKETPLACE_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "orange_marketplace_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use orange_marketplace_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see orange_marketplace_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before orange_marketplace_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in orange_marketplace_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from orange_marketplace_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by orange_marketplace_update_offers or orange_marketplace_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by orange_marketplace_update_offers or orange_marketplace_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging orange_marketplace_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll orange_marketplace_get_offer_export_status about once a minute until COMPLETED, then read each file with orange_marketplace_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from orange_marketplace_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_get_offer_export_status",
+ "description": "Status of an offer export started with orange_marketplace_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to orange_marketplace_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by orange_marketplace_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by orange_marketplace_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by orange_marketplace_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Orange uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_threads",
+ "description": "List message threads (M11) with customers and Orange: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Orange)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from orange_marketplace_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in orange_marketplace_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_invoices",
+ "description": "List the accounting documents Orange issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Orange runs Enhanced Seller Invoicing: invoices and credit notes that Orange or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Orange (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in orange_marketplace_list_orders and orange_marketplace_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in orange_marketplace_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "orange_marketplace_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from orange_marketplace_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from orange_marketplace_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from orange_marketplace_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in orange_marketplace_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in orange_marketplace_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with orange_marketplace_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with orange_marketplace_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from orange_marketplace_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Orange. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from orange_marketplace_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Orange) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "orange_marketplace_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Orange or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Orange) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from orange_marketplace_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "orange_marketplace_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from orange_marketplace_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in orange_marketplace_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from orange_marketplace_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Orange handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from orange_marketplace_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from orange_marketplace_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "orange_marketplace_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Orange asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with orange_marketplace_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Orange defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "orange_marketplace_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Orange asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with orange_marketplace_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by orange_marketplace_get_account, also shown in the back office). Leave it out to use ORANGE_MARKETPLACE_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "ORANGE_MARKETPLACE_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/fr/orange-marketplace.live.spec.ts b/packages/backend/src/adapters/fr/orange-marketplace.live.spec.ts
new file mode 100644
index 000000000..fa3595db3
--- /dev/null
+++ b/packages/backend/src/adapters/fr/orange-marketplace.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './orange-marketplace.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_ORANGE_MARKETPLACE_LIVE=1 (GET /api/version needs no key; the shop reads need ORANGE_MARKETPLACE_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'orange-marketplace', hosts: ['orangefr-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/fr/retif.json b/packages/backend/src/adapters/fr/retif.json
new file mode 100644
index 000000000..6da40c015
--- /dev/null
+++ b/packages/backend/src/adapters/fr/retif.json
@@ -0,0 +1,2034 @@
+{
+ "slug": "retif",
+ "name": "RETIF Marketplace",
+ "aliases": [
+ "Groupe RETIF",
+ "RETIF seller API",
+ "RETIF vendeur",
+ "RETIF marketplace B2B",
+ "RETIF Mirakl",
+ "retif.eu marketplace",
+ "marketplace.retif.eu"
+ ],
+ "description": "Run your shop on the RETIF marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France, Belgium, Germany, Spain, Italy, Luxembourg and the Netherlands; sign in with the shop API key from your RETIF seller back office.",
+ "instructions": "## RETIF Marketplace\nRun your shop on the RETIF marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and RETIF, returns, order documents, invoices and transactions. The connector calls the RETIF seller platform at `https://marketplace.retif.eu` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France, Belgium, Germany, Spain, Italy, Luxembourg and the Netherlands. One seller account sells in every RETIF country. RETIF sells to businesses only.\n\n**Who can sell**: RETIF accepts sellers that focus on business customers: contact RETIF to register your interest. Sellers invoice and ship directly to the customer. There is no setup or monthly fee; RETIF charges a commission per sale that depends on the product category. The connector needs a seller account that RETIF has already opened.\n\nRETIF supports colour variants only; other variant types are listed as separate products.\n\n**Setup (about 5 minutes)**\n1. Sign in to the RETIF seller back office: `https://marketplace.retif.eu/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `RETIF_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `RETIF_SHOP_ID` empty. Only if your user manages several shops on RETIF, set `RETIF_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `retif_get_account`). Without it your default shop is used.\n4. Install and run `retif_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the RETIF seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `retif_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `retif_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `retif_list_offers` for prices and stock and `retif_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `retif_get_products` looks products up in the RETIF catalog by EAN or another reference and returns the marketplace product SKU; `retif_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `retif_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `retif_update_tracking` stores the carrier and tracking number (carrier codes come from `retif_list_carriers`) and `retif_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `retif_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `retif_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `retif_list_order_documents`.\n\n**Writes: confirm first.** `retif_accept_order`, `retif_update_tracking`, `retif_ship_order`, `retif_resolve_incident`, `retif_accept_return`, `retif_receive_return`, `retif_update_offers`, `retif_reply_thread`, `retif_create_order_thread` and `retif_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `retif_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `retif_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`retif_get_offer` or `retif_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `retif_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `retif_list_offer_conditions`, logistic class codes from `retif_list_logistic_classes`.\n\n**File imports**: `retif_import_products` (P41) and `retif_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format RETIF asks for; the connector downloads it and uploads it to RETIF. Track them with `retif_list_product_imports` / `retif_get_product_import` and `retif_list_offer_imports` / `retif_get_offer_import`.\n\n**Returns**: `retif_list_returns` (RT11) lists return requests. Where RETIF lets the shop decide, `retif_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `retif_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `retif_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `retif_get_thread` reads one with its messages, `retif_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is RETIF) and `retif_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `retif_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `retif_list_invoices` (IV01) lists the accounting documents RETIF issues to the shop and `retif_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If RETIF uses Enhanced Seller Invoicing, IV01 returns no new documents; use `retif_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `retif_export_offers`, poll `retif_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `retif_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `retif_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `retif_get_account` and the same `shop_id`. Without `shop_id` a call uses `RETIF_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `retif_list_channels` (country sites), `retif_list_carriers`, `retif_list_shipping_zones`, `retif_list_shipping_methods` and `retif_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and RETIF can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `retif_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "fr",
+ "category": "e-commerce",
+ "icon": "retif",
+ "docsUrl": "https://www.retif.eu/contacts/",
+ "requiredEnvVars": [
+ "RETIF_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "RETIF_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with RETIF and access to its seller back office to generate the shop API key. RETIF accepts sellers that focus on business customers: contact RETIF to register your interest. Sellers invoice and ship directly to the customer. There is no setup or monthly fee; RETIF charges a commission per sale that depends on the product category.",
+ "envVarMeta": {
+ "RETIF_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "RETIF seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://marketplace.retif.eu/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "RETIF_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on RETIF: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "RETIF refused the API key. Check that RETIF_API_KEY is the shop key from your RETIF seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set RETIF_SHOP_ID to a shop you manage.",
+ "404": "The RETIF seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://marketplace.retif.eu: RETIF may have moved its seller back office.",
+ "rate_limited": "RETIF is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "retif_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A RETIF seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your RETIF seller account",
+ "body": "Sign in to the RETIF seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the RETIF seller back office",
+ "url": "https://marketplace.retif.eu/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask RETIF (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "RETIF accepts sellers that focus on business customers: contact RETIF to register your interest. Sellers invoice and ship directly to the customer. There is no setup or monthly fee; RETIF charges a commission per sale that depends on the product category. See [the RETIF seller page](https://www.retif.eu/contacts/)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "RETIF_API_KEY",
+ "RETIF_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "RETIF refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "RETIF Marketplace",
+ "type": "REST",
+ "baseUrl": "https://marketplace.retif.eu/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{RETIF_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "retif_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use retif_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see retif_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before retif_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in retif_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from retif_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by retif_update_offers or retif_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by retif_update_offers or retif_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging retif_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll retif_get_offer_export_status about once a minute until COMPLETED, then read each file with retif_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from retif_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "retif_get_offer_export_status",
+ "description": "Status of an offer export started with retif_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to retif_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by retif_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by retif_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by retif_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references RETIF uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_threads",
+ "description": "List message threads (M11) with customers and RETIF: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with RETIF)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from retif_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in retif_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_invoices",
+ "description": "List the accounting documents RETIF issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_document_requests",
+ "description": "List accounting document requests (DR11), used when RETIF runs Enhanced Seller Invoicing: invoices and credit notes that RETIF or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by RETIF (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in retif_list_orders and retif_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in retif_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "retif_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from retif_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from retif_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from retif_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in retif_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in retif_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with retif_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with retif_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from retif_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or RETIF. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from retif_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (RETIF) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "retif_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, RETIF or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (RETIF) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from retif_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "retif_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from retif_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in retif_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from retif_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when RETIF handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from retif_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from retif_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "retif_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format RETIF asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with retif_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format RETIF defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "retif_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format RETIF asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with retif_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by retif_get_account, also shown in the back office). Leave it out to use RETIF_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "RETIF_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/fr/retif.live.spec.ts b/packages/backend/src/adapters/fr/retif.live.spec.ts
new file mode 100644
index 000000000..7ea718385
--- /dev/null
+++ b/packages/backend/src/adapters/fr/retif.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './retif.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_RETIF_LIVE=1 (GET /api/version needs no key; the shop reads need RETIF_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'retif', hosts: ['marketplace.retif.eu'] });
diff --git a/packages/backend/src/adapters/fr/vertbaudet.json b/packages/backend/src/adapters/fr/vertbaudet.json
new file mode 100644
index 000000000..df0fad982
--- /dev/null
+++ b/packages/backend/src/adapters/fr/vertbaudet.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "vertbaudet",
+ "name": "Vertbaudet Marketplace",
+ "aliases": [
+ "Vertbaudet seller API",
+ "Vertbaudet vendeur marketplace",
+ "Vertbaudet place de marché",
+ "Vertbaudet Marktplatz",
+ "Vertbaudet Mirakl"
+ ],
+ "description": "Run your shop on the Vertbaudet marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France and Germany; sign in with the shop API key from your Vertbaudet seller back office.",
+ "instructions": "## Vertbaudet Marketplace\nRun your shop on the Vertbaudet marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Vertbaudet, returns, order documents, invoices and transactions. The connector calls the Vertbaudet seller platform at `https://vertbaudetfr-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France and Germany. Free-text product attributes for Germany must be written in German.\n\n**Who can sell**: Vertbaudet selects brands and retailers with new, mid-range or higher children's and maternity products; contact it by e-mail (`business@vertbaudet.com`). The business must be registered in the EU, ship to France from the eurozone and offer French content and customer service. The fee is a 17 % commission plus EUR 49.90 a month. The connector needs a seller account that Vertbaudet has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Vertbaudet seller back office: `https://vertbaudetfr-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `VERTBAUDET_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `VERTBAUDET_SHOP_ID` empty. Only if your user manages several shops on Vertbaudet, set `VERTBAUDET_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `vertbaudet_get_account`). Without it your default shop is used.\n4. Install and run `vertbaudet_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Vertbaudet seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `vertbaudet_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `vertbaudet_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `vertbaudet_list_offers` for prices and stock and `vertbaudet_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `vertbaudet_get_products` looks products up in the Vertbaudet catalog by EAN or another reference and returns the marketplace product SKU; `vertbaudet_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `vertbaudet_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `vertbaudet_update_tracking` stores the carrier and tracking number (carrier codes come from `vertbaudet_list_carriers`) and `vertbaudet_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `vertbaudet_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `vertbaudet_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `vertbaudet_list_order_documents`.\n\n**Writes: confirm first.** `vertbaudet_accept_order`, `vertbaudet_update_tracking`, `vertbaudet_ship_order`, `vertbaudet_resolve_incident`, `vertbaudet_accept_return`, `vertbaudet_receive_return`, `vertbaudet_update_offers`, `vertbaudet_reply_thread`, `vertbaudet_create_order_thread` and `vertbaudet_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `vertbaudet_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `vertbaudet_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`vertbaudet_get_offer` or `vertbaudet_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `vertbaudet_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `vertbaudet_list_offer_conditions`, logistic class codes from `vertbaudet_list_logistic_classes`.\n\n**File imports**: `vertbaudet_import_products` (P41) and `vertbaudet_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Vertbaudet asks for; the connector downloads it and uploads it to Vertbaudet. Track them with `vertbaudet_list_product_imports` / `vertbaudet_get_product_import` and `vertbaudet_list_offer_imports` / `vertbaudet_get_offer_import`.\n\n**Returns**: `vertbaudet_list_returns` (RT11) lists return requests. Where Vertbaudet lets the shop decide, `vertbaudet_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `vertbaudet_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `vertbaudet_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `vertbaudet_get_thread` reads one with its messages, `vertbaudet_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Vertbaudet) and `vertbaudet_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `vertbaudet_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `vertbaudet_list_invoices` (IV01) lists the accounting documents Vertbaudet issues to the shop and `vertbaudet_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Vertbaudet uses Enhanced Seller Invoicing, IV01 returns no new documents; use `vertbaudet_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `vertbaudet_export_offers`, poll `vertbaudet_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `vertbaudet_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `vertbaudet_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `vertbaudet_get_account` and the same `shop_id`. Without `shop_id` a call uses `VERTBAUDET_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `vertbaudet_list_channels` (country sites), `vertbaudet_list_carriers`, `vertbaudet_list_shipping_zones`, `vertbaudet_list_shipping_methods` and `vertbaudet_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Vertbaudet can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `vertbaudet_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "fr",
+ "category": "e-commerce",
+ "icon": "vertbaudet",
+ "docsUrl": "https://vertbaudetfr-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "VERTBAUDET_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "VERTBAUDET_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Vertbaudet and access to its seller back office to generate the shop API key. Vertbaudet selects brands and retailers with new, mid-range or higher children's and maternity products; contact it by e-mail (`business@vertbaudet.com`). The business must be registered in the EU, ship to France from the eurozone and offer French content and customer service. The fee is a 17 % commission plus EUR 49.90 a month.",
+ "envVarMeta": {
+ "VERTBAUDET_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Vertbaudet seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://vertbaudetfr-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "VERTBAUDET_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Vertbaudet: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Vertbaudet refused the API key. Check that VERTBAUDET_API_KEY is the shop key from your Vertbaudet seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set VERTBAUDET_SHOP_ID to a shop you manage.",
+ "404": "The Vertbaudet seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://vertbaudetfr-prod.mirakl.net: Vertbaudet may have moved its seller back office.",
+ "rate_limited": "Vertbaudet is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "vertbaudet_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Vertbaudet seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Vertbaudet seller account",
+ "body": "Sign in to the Vertbaudet seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Vertbaudet seller back office",
+ "url": "https://vertbaudetfr-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Vertbaudet (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Vertbaudet selects brands and retailers with new, mid-range or higher children's and maternity products; contact it by e-mail (`business@vertbaudet.com`). The business must be registered in the EU, ship to France from the eurozone and offer French content and customer service. The fee is a 17 % commission plus EUR 49.90 a month."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "VERTBAUDET_API_KEY",
+ "VERTBAUDET_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Vertbaudet refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Vertbaudet Marketplace",
+ "type": "REST",
+ "baseUrl": "https://vertbaudetfr-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{VERTBAUDET_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "vertbaudet_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use vertbaudet_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see vertbaudet_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before vertbaudet_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in vertbaudet_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from vertbaudet_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by vertbaudet_update_offers or vertbaudet_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by vertbaudet_update_offers or vertbaudet_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging vertbaudet_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll vertbaudet_get_offer_export_status about once a minute until COMPLETED, then read each file with vertbaudet_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from vertbaudet_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_get_offer_export_status",
+ "description": "Status of an offer export started with vertbaudet_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to vertbaudet_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by vertbaudet_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by vertbaudet_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by vertbaudet_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Vertbaudet uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_threads",
+ "description": "List message threads (M11) with customers and Vertbaudet: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Vertbaudet)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from vertbaudet_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in vertbaudet_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_invoices",
+ "description": "List the accounting documents Vertbaudet issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Vertbaudet runs Enhanced Seller Invoicing: invoices and credit notes that Vertbaudet or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Vertbaudet (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in vertbaudet_list_orders and vertbaudet_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in vertbaudet_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "vertbaudet_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from vertbaudet_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from vertbaudet_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from vertbaudet_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in vertbaudet_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in vertbaudet_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with vertbaudet_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with vertbaudet_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from vertbaudet_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Vertbaudet. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from vertbaudet_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Vertbaudet) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "vertbaudet_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Vertbaudet or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Vertbaudet) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from vertbaudet_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "vertbaudet_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from vertbaudet_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in vertbaudet_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from vertbaudet_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Vertbaudet handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from vertbaudet_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from vertbaudet_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "vertbaudet_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Vertbaudet asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with vertbaudet_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Vertbaudet defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "vertbaudet_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Vertbaudet asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with vertbaudet_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by vertbaudet_get_account, also shown in the back office). Leave it out to use VERTBAUDET_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "VERTBAUDET_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/fr/vertbaudet.live.spec.ts b/packages/backend/src/adapters/fr/vertbaudet.live.spec.ts
new file mode 100644
index 000000000..be1df7c60
--- /dev/null
+++ b/packages/backend/src/adapters/fr/vertbaudet.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './vertbaudet.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_VERTBAUDET_LIVE=1 (GET /api/version needs no key; the shop reads need VERTBAUDET_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'vertbaudet', hosts: ['vertbaudetfr-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/fr/yves-rocher.json b/packages/backend/src/adapters/fr/yves-rocher.json
new file mode 100644
index 000000000..3cddb521a
--- /dev/null
+++ b/packages/backend/src/adapters/fr/yves-rocher.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "yves-rocher",
+ "name": "Yves Rocher Marketplace",
+ "aliases": [
+ "Yves Rocher seller API",
+ "Yves Rocher marketplace partenaires",
+ "Yves Rocher Mirakl",
+ "yves-rocher.fr marketplace",
+ "Groupe Rocher"
+ ],
+ "description": "Run your shop on the Yves Rocher marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in France; sign in with the shop API key from your Yves Rocher seller back office.",
+ "instructions": "## Yves Rocher Marketplace\nRun your shop on the Yves Rocher marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Yves Rocher, returns, order documents, invoices and transactions. The connector calls the Yves Rocher seller platform at `https://yvesrocherfr-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France.\n\n**Who can sell**: Yves Rocher selects a small number of partner brands: write to its marketplace team (`support-marketplace@yrnet.com`). Products must meet the naturalness standards of the Yves Rocher CSR charter and contain no controversial ingredients. There is no setup fee; Yves Rocher charges a monthly fee and a commission per sale. Sellers answer customer messages within 48 hours. The connector needs a seller account that Yves Rocher has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Yves Rocher seller back office: `https://yvesrocherfr-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `YVES_ROCHER_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `YVES_ROCHER_SHOP_ID` empty. Only if your user manages several shops on Yves Rocher, set `YVES_ROCHER_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `yves_rocher_get_account`). Without it your default shop is used.\n4. Install and run `yves_rocher_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Yves Rocher seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `yves_rocher_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `yves_rocher_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `yves_rocher_list_offers` for prices and stock and `yves_rocher_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `yves_rocher_get_products` looks products up in the Yves Rocher catalog by EAN or another reference and returns the marketplace product SKU; `yves_rocher_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `yves_rocher_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `yves_rocher_update_tracking` stores the carrier and tracking number (carrier codes come from `yves_rocher_list_carriers`) and `yves_rocher_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `yves_rocher_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `yves_rocher_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `yves_rocher_list_order_documents`.\n\n**Writes: confirm first.** `yves_rocher_accept_order`, `yves_rocher_update_tracking`, `yves_rocher_ship_order`, `yves_rocher_resolve_incident`, `yves_rocher_accept_return`, `yves_rocher_receive_return`, `yves_rocher_update_offers`, `yves_rocher_reply_thread`, `yves_rocher_create_order_thread` and `yves_rocher_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `yves_rocher_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `yves_rocher_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`yves_rocher_get_offer` or `yves_rocher_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `yves_rocher_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `yves_rocher_list_offer_conditions`, logistic class codes from `yves_rocher_list_logistic_classes`.\n\n**File imports**: `yves_rocher_import_products` (P41) and `yves_rocher_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Yves Rocher asks for; the connector downloads it and uploads it to Yves Rocher. Track them with `yves_rocher_list_product_imports` / `yves_rocher_get_product_import` and `yves_rocher_list_offer_imports` / `yves_rocher_get_offer_import`.\n\n**Returns**: `yves_rocher_list_returns` (RT11) lists return requests. Where Yves Rocher lets the shop decide, `yves_rocher_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `yves_rocher_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `yves_rocher_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `yves_rocher_get_thread` reads one with its messages, `yves_rocher_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Yves Rocher) and `yves_rocher_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `yves_rocher_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `yves_rocher_list_invoices` (IV01) lists the accounting documents Yves Rocher issues to the shop and `yves_rocher_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Yves Rocher uses Enhanced Seller Invoicing, IV01 returns no new documents; use `yves_rocher_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `yves_rocher_export_offers`, poll `yves_rocher_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `yves_rocher_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `yves_rocher_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `yves_rocher_get_account` and the same `shop_id`. Without `shop_id` a call uses `YVES_ROCHER_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `yves_rocher_list_channels` (country sites), `yves_rocher_list_carriers`, `yves_rocher_list_shipping_zones`, `yves_rocher_list_shipping_methods` and `yves_rocher_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Yves Rocher can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `yves_rocher_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "fr",
+ "category": "e-commerce",
+ "icon": "yves-rocher",
+ "docsUrl": "https://yvesrocherfr-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "YVES_ROCHER_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "YVES_ROCHER_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Yves Rocher and access to its seller back office to generate the shop API key. Yves Rocher selects a small number of partner brands: write to its marketplace team (`support-marketplace@yrnet.com`). Products must meet the naturalness standards of the Yves Rocher CSR charter and contain no controversial ingredients. There is no setup fee; Yves Rocher charges a monthly fee and a commission per sale. Sellers answer customer messages within 48 hours.",
+ "envVarMeta": {
+ "YVES_ROCHER_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Yves Rocher seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://yvesrocherfr-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "YVES_ROCHER_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Yves Rocher: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Yves Rocher refused the API key. Check that YVES_ROCHER_API_KEY is the shop key from your Yves Rocher seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set YVES_ROCHER_SHOP_ID to a shop you manage.",
+ "404": "The Yves Rocher seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://yvesrocherfr-prod.mirakl.net: Yves Rocher may have moved its seller back office.",
+ "rate_limited": "Yves Rocher is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "yves_rocher_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Yves Rocher seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Yves Rocher seller account",
+ "body": "Sign in to the Yves Rocher seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Yves Rocher seller back office",
+ "url": "https://yvesrocherfr-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Yves Rocher (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Yves Rocher selects a small number of partner brands: write to its marketplace team (`support-marketplace@yrnet.com`). Products must meet the naturalness standards of the Yves Rocher CSR charter and contain no controversial ingredients. There is no setup fee; Yves Rocher charges a monthly fee and a commission per sale. Sellers answer customer messages within 48 hours."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "YVES_ROCHER_API_KEY",
+ "YVES_ROCHER_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Yves Rocher refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Yves Rocher Marketplace",
+ "type": "REST",
+ "baseUrl": "https://yvesrocherfr-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{YVES_ROCHER_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "yves_rocher_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use yves_rocher_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see yves_rocher_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before yves_rocher_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in yves_rocher_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from yves_rocher_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by yves_rocher_update_offers or yves_rocher_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by yves_rocher_update_offers or yves_rocher_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging yves_rocher_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll yves_rocher_get_offer_export_status about once a minute until COMPLETED, then read each file with yves_rocher_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from yves_rocher_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_get_offer_export_status",
+ "description": "Status of an offer export started with yves_rocher_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to yves_rocher_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by yves_rocher_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by yves_rocher_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by yves_rocher_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Yves Rocher uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_threads",
+ "description": "List message threads (M11) with customers and Yves Rocher: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Yves Rocher)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from yves_rocher_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in yves_rocher_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_invoices",
+ "description": "List the accounting documents Yves Rocher issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Yves Rocher runs Enhanced Seller Invoicing: invoices and credit notes that Yves Rocher or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Yves Rocher (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in yves_rocher_list_orders and yves_rocher_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in yves_rocher_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "yves_rocher_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from yves_rocher_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from yves_rocher_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from yves_rocher_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in yves_rocher_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in yves_rocher_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with yves_rocher_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with yves_rocher_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from yves_rocher_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Yves Rocher. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from yves_rocher_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Yves Rocher) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "yves_rocher_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Yves Rocher or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Yves Rocher) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from yves_rocher_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "yves_rocher_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from yves_rocher_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in yves_rocher_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from yves_rocher_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Yves Rocher handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from yves_rocher_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from yves_rocher_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "yves_rocher_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Yves Rocher asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with yves_rocher_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Yves Rocher defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "yves_rocher_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Yves Rocher asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with yves_rocher_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by yves_rocher_get_account, also shown in the back office). Leave it out to use YVES_ROCHER_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "YVES_ROCHER_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/fr/yves-rocher.live.spec.ts b/packages/backend/src/adapters/fr/yves-rocher.live.spec.ts
new file mode 100644
index 000000000..49081a3e8
--- /dev/null
+++ b/packages/backend/src/adapters/fr/yves-rocher.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './yves-rocher.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_YVES_ROCHER_LIVE=1 (GET /api/version needs no key; the shop reads need YVES_ROCHER_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'yves-rocher', hosts: ['yvesrocherfr-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/intl/mirakl.json b/packages/backend/src/adapters/intl/mirakl.json
index b1945bcc9..ff7d7d26a 100644
--- a/packages/backend/src/adapters/intl/mirakl.json
+++ b/packages/backend/src/adapters/intl/mirakl.json
@@ -3,7 +3,7 @@
"name": "Mirakl Seller API",
"aliases": ["Mirakl Marketplace Platform"],
"description": "Run your shop on any Mirakl-powered marketplace that has no connector of its own in the catalog from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, customer and operator messages, returns, order documents, invoices and transactions. One install per marketplace.",
- "instructions": "## Mirakl Seller API\nThis connector uses the **Mirakl Marketplace Platform (MMP) shop API**, the same REST API on every marketplace that runs on Mirakl. Each marketplace operator has its own Mirakl instance, so **one install covers one marketplace**: install the connector once per marketplace you sell on (for example once for Leroy Merlin and once for Conforama) and give each install a name that says which one it is.\n\n**Retailers with their own connector**: 1-800-Flowers.com, Åhléns, ANWB, Atlas For Men, Auchan, B&Q, Best Buy, Black Red White, Bloomingdale's, Boulanger, BrandAlley, Brico Dépôt, Bricomarché, Bunnings, BUT, Carrefour, Casa del Libro, Conforama, Conrad, Coppel, Cultura, Debenhams, Decathlon, Douglas Partner Program, E.Leclerc, El Corte Inglés, Elkjøp, EmpikPlace, ePRICE, Fressnapf, GACD, Greenweez, H&M Home, home24, HORNBACH, IBS.it, INNO, Jardiland and Gamm vert, Kiabi, Kohl's, Kruidvat, La Poste, La Redoute, LDLC, Leen Bakker, Leroy Merlin, Lowe's, Macy's, Maisons du Monde, MediaMarkt, Minted, MODIVO, Mountain Warehouse, Nature & Découvertes, Nordstrom, Obelink, Parts Town, PcComponentes, Pixmania, Place des Tendances, Praxis and Brico, Printemps, Private Sport Shop, Ripley, Roman, Rue du Commerce, SalonCentric, Sarenza, Shop Apotheke, Sprinter, Stadium, Super-Pharm, Superdrug, Tesco, The Range, Ubaldi, Vente-unique, vtwonen, Worten, XXXLutz each have a dedicated connector in the catalog with the seller address already set. Install that one instead; use this generic connector for any other marketplace that runs on Mirakl.\n\n**Setup (about 5 minutes per marketplace)**\n1. Sign in to the marketplace's seller back office (the Mirakl portal the operator gave you).\n2. Copy the address of the portal without any path into `MIRAKL_URL`. The connector adds `/api` itself, so do not paste it. Addresses of common marketplaces:\n - Leroy Merlin (ADEO): `https://adeo-marketplace.mirakl.net`\n - BUT: `https://but-prod.mirakl.net`\n - Conforama: `https://conforama-prod.mirakl.net`\n - home24: `https://home24.mirakl.net`\n - Maisons du Monde: `https://maisonsdumonde-prod.mirakl.net`\n - Vente-unique: `https://venteunique-prod.mirakl.net`\n - ePrice: `https://marketplace.eprice.it`\n Other operators work the same way, also those on their own domain: use the address of the seller back office you sign in to.\n3. Click your user name in the top right corner, open **My user settings** and the **API Key** tab, and generate a key (or copy the existing one). Paste it into `MIRAKL_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n4. Only if your user manages several shops on this marketplace (common on home24 and Vente-unique): set `MIRAKL_SHOP_ID` to the shop to work on (shown in the back office and in `mirakl_get_account`). Without it Mirakl uses your default shop.\n5. Install and run `mirakl_get_account`.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `mirakl_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `mirakl_update_tracking` stores the carrier and tracking number (carrier codes come from `mirakl_list_carriers`) and `mirakl_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `mirakl_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `mirakl_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `mirakl_list_order_documents`.\n\n**Writes: confirm first.** `mirakl_accept_order`, `mirakl_update_tracking`, `mirakl_ship_order`, `mirakl_resolve_incident`, `mirakl_accept_return`, `mirakl_receive_return`, `mirakl_update_offers`, `mirakl_reply_thread`, `mirakl_create_order_thread` and `mirakl_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `mirakl_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `mirakl_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`mirakl_get_offer` or `mirakl_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `mirakl_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `mirakl_list_offer_conditions`, logistic class codes from `mirakl_list_logistic_classes`.\n\n**File imports**: `mirakl_import_products` (P41) and `mirakl_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the operator's format; the connector downloads it and uploads it to Mirakl. Track them with `mirakl_list_product_imports` / `mirakl_get_product_import` and `mirakl_list_offer_imports` / `mirakl_get_offer_import`.\n\n**Returns**: `mirakl_list_returns` (RT11) lists return requests. Where the operator lets the shop decide, `mirakl_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `mirakl_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `mirakl_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; Mirakl refuses `entity_id` without `entity_type`), `mirakl_get_thread` reads one with its messages, `mirakl_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`) and `mirakl_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `mirakl_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `mirakl_list_invoices` (IV01) lists the operator's accounting documents and `mirakl_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). On marketplaces with Enhanced Seller Invoicing IV01 returns no new documents; use `mirakl_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `mirakl_export_offers`, poll `mirakl_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `mirakl_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `mirakl_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `mirakl_get_account` and the same `shop_id`. Without `shop_id` a call uses `MIRAKL_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `mirakl_list_channels` (country sites), `mirakl_list_carriers`, `mirakl_list_shipping_zones`, `mirakl_list_shipping_methods` and `mirakl_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; Mirakl answers in UTC.\n\n**Rate limits**: Mirakl limits each API separately and the operator can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `mirakl_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or belongs to another marketplace, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns (or that `MIRAKL_URL` is not a Mirakl instance), 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "instructions": "## Mirakl Seller API\nThis connector uses the **Mirakl Marketplace Platform (MMP) shop API**, the same REST API on every marketplace that runs on Mirakl. Each marketplace operator has its own Mirakl instance, so **one install covers one marketplace**: install the connector once per marketplace you sell on (for example once for Leroy Merlin and once for Conforama) and give each install a name that says which one it is.\n\n**Retailers with their own connector**: 1-800-Flowers.com, Åhléns, ANWB, Atlas For Men, Auchan, AUTODOC, B&Q, Best Buy, Black Red White, Bloomingdale's, Boulanger, BrandAlley, Brico Dépôt, Bricomarché, Bunnings, BUT, Carrefour, Casa del Libro, Conforama, Conrad, Coppel, Cultura, Debenhams, Decathlon, Douglas Partner Program, E.Leclerc, El Corte Inglés, Elkjøp, EmpikPlace, ePRICE, Fressnapf, GACD, Greenweez, H&M Home, home24, HORNBACH, IBS.it, INNO, Jardiland and Gamm vert, KaBuM!, Kiabi, Kohl's, Kruidvat, La Poste, La Redoute, LDLC, Leen Bakker, Leroy Merlin, Lowe's, MacWay, Macy's, Maisons du Monde, MediaMarkt, Minted, MODIVO, Mountain Warehouse, Nature & Découvertes, Nordstrom, Obelink, Orange, Parts Town, PcComponentes, Phone House, Pixmania, Place des Tendances, Planeta Huerto, Praxis and Brico, Printemps, Private Sport Shop, Public.gr, RETIF, Ripley, Roman, Rue du Commerce, Saks, SalonCentric, Sarenza, Shop Apotheke, Sprinter, Stadium, Super-Pharm, Superdrug, Tesco, The Knot, The Range, Tiendanimal, Ubaldi, URBN, Vente-unique, Vertbaudet, vtwonen, Worten, XXXLutz, Yves Rocher, zooplus each have a dedicated connector in the catalog with the seller address already set. Install that one instead; use this generic connector for any other marketplace that runs on Mirakl.\n\n**Setup (about 5 minutes per marketplace)**\n1. Sign in to the marketplace's seller back office (the Mirakl portal the operator gave you).\n2. Copy the address of the portal without any path into `MIRAKL_URL`. The connector adds `/api` itself, so do not paste it. Addresses of common marketplaces:\n - Leroy Merlin (ADEO): `https://adeo-marketplace.mirakl.net`\n - BUT: `https://but-prod.mirakl.net`\n - Conforama: `https://conforama-prod.mirakl.net`\n - home24: `https://home24.mirakl.net`\n - Maisons du Monde: `https://maisonsdumonde-prod.mirakl.net`\n - Vente-unique: `https://venteunique-prod.mirakl.net`\n - ePrice: `https://marketplace.eprice.it`\n Other operators work the same way, also those on their own domain: use the address of the seller back office you sign in to.\n3. Click your user name in the top right corner, open **My user settings** and the **API Key** tab, and generate a key (or copy the existing one). Paste it into `MIRAKL_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n4. Only if your user manages several shops on this marketplace (common on home24 and Vente-unique): set `MIRAKL_SHOP_ID` to the shop to work on (shown in the back office and in `mirakl_get_account`). Without it Mirakl uses your default shop.\n5. Install and run `mirakl_get_account`.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `mirakl_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `mirakl_update_tracking` stores the carrier and tracking number (carrier codes come from `mirakl_list_carriers`) and `mirakl_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `mirakl_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `mirakl_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `mirakl_list_order_documents`.\n\n**Writes: confirm first.** `mirakl_accept_order`, `mirakl_update_tracking`, `mirakl_ship_order`, `mirakl_resolve_incident`, `mirakl_accept_return`, `mirakl_receive_return`, `mirakl_update_offers`, `mirakl_reply_thread`, `mirakl_create_order_thread` and `mirakl_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `mirakl_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `mirakl_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`mirakl_get_offer` or `mirakl_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `mirakl_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `mirakl_list_offer_conditions`, logistic class codes from `mirakl_list_logistic_classes`.\n\n**File imports**: `mirakl_import_products` (P41) and `mirakl_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the operator's format; the connector downloads it and uploads it to Mirakl. Track them with `mirakl_list_product_imports` / `mirakl_get_product_import` and `mirakl_list_offer_imports` / `mirakl_get_offer_import`.\n\n**Returns**: `mirakl_list_returns` (RT11) lists return requests. Where the operator lets the shop decide, `mirakl_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `mirakl_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `mirakl_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; Mirakl refuses `entity_id` without `entity_type`), `mirakl_get_thread` reads one with its messages, `mirakl_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`) and `mirakl_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `mirakl_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `mirakl_list_invoices` (IV01) lists the operator's accounting documents and `mirakl_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). On marketplaces with Enhanced Seller Invoicing IV01 returns no new documents; use `mirakl_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `mirakl_export_offers`, poll `mirakl_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `mirakl_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `mirakl_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `mirakl_get_account` and the same `shop_id`. Without `shop_id` a call uses `MIRAKL_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `mirakl_list_channels` (country sites), `mirakl_list_carriers`, `mirakl_list_shipping_zones`, `mirakl_list_shipping_methods` and `mirakl_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; Mirakl answers in UTC.\n\n**Rate limits**: Mirakl limits each API separately and the operator can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `mirakl_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or belongs to another marketplace, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns (or that `MIRAKL_URL` is not a Mirakl instance), 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
"region": "intl",
"category": "e-commerce",
"icon": "mirakl",
diff --git a/packages/backend/src/adapters/intl/public-gr.json b/packages/backend/src/adapters/intl/public-gr.json
new file mode 100644
index 000000000..a89e9d57a
--- /dev/null
+++ b/packages/backend/src/adapters/intl/public-gr.json
@@ -0,0 +1,2032 @@
+{
+ "slug": "public-gr",
+ "name": "Public.gr Marketplace",
+ "aliases": [
+ "Public",
+ "Public Greece",
+ "Public marketplace",
+ "Public.gr seller API",
+ "Public.gr Mirakl"
+ ],
+ "description": "Run your shop on the Public.gr marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in Greece; sign in with the shop API key from your Public.gr seller back office.",
+ "instructions": "## Public.gr Marketplace\nRun your shop on the Public.gr marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Public.gr, returns, order documents, invoices and transactions. The connector calls the Public.gr seller platform at `https://publicgr-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Greece.\n\n**Who can sell**: Public reviews each seller application; approval takes about two to three weeks. Sellers need a Greek or EU VAT number and issue their invoices through the Greek myDATA system. Product titles, descriptions and attributes must be in Greek, and sellers ship their orders themselves. The connector needs a seller account that Public.gr has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Public.gr seller back office: `https://publicgr-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `PUBLIC_GR_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `PUBLIC_GR_SHOP_ID` empty. Only if your user manages several shops on Public.gr, set `PUBLIC_GR_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `public_gr_get_account`). Without it your default shop is used.\n4. Install and run `public_gr_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Public.gr seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `public_gr_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `public_gr_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `public_gr_list_offers` for prices and stock and `public_gr_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `public_gr_get_products` looks products up in the Public.gr catalog by EAN or another reference and returns the marketplace product SKU; `public_gr_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `public_gr_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `public_gr_update_tracking` stores the carrier and tracking number (carrier codes come from `public_gr_list_carriers`) and `public_gr_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `public_gr_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `public_gr_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `public_gr_list_order_documents`.\n\n**Writes: confirm first.** `public_gr_accept_order`, `public_gr_update_tracking`, `public_gr_ship_order`, `public_gr_resolve_incident`, `public_gr_accept_return`, `public_gr_receive_return`, `public_gr_update_offers`, `public_gr_reply_thread`, `public_gr_create_order_thread` and `public_gr_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `public_gr_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `public_gr_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`public_gr_get_offer` or `public_gr_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `public_gr_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `public_gr_list_offer_conditions`, logistic class codes from `public_gr_list_logistic_classes`.\n\n**File imports**: `public_gr_import_products` (P41) and `public_gr_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Public.gr asks for; the connector downloads it and uploads it to Public.gr. Track them with `public_gr_list_product_imports` / `public_gr_get_product_import` and `public_gr_list_offer_imports` / `public_gr_get_offer_import`.\n\n**Returns**: `public_gr_list_returns` (RT11) lists return requests. Where Public.gr lets the shop decide, `public_gr_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `public_gr_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `public_gr_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `public_gr_get_thread` reads one with its messages, `public_gr_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Public.gr) and `public_gr_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `public_gr_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `public_gr_list_invoices` (IV01) lists the accounting documents Public.gr issues to the shop and `public_gr_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Public.gr uses Enhanced Seller Invoicing, IV01 returns no new documents; use `public_gr_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `public_gr_export_offers`, poll `public_gr_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `public_gr_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `public_gr_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `public_gr_get_account` and the same `shop_id`. Without `shop_id` a call uses `PUBLIC_GR_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `public_gr_list_channels` (country sites), `public_gr_list_carriers`, `public_gr_list_shipping_zones`, `public_gr_list_shipping_methods` and `public_gr_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Public.gr can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `public_gr_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "intl",
+ "category": "e-commerce",
+ "icon": "public-gr",
+ "docsUrl": "https://publicgr-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "PUBLIC_GR_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "PUBLIC_GR_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Public.gr and access to its seller back office to generate the shop API key. Public reviews each seller application; approval takes about two to three weeks. Sellers need a Greek or EU VAT number and issue their invoices through the Greek myDATA system. Product titles, descriptions and attributes must be in Greek, and sellers ship their orders themselves.",
+ "envVarMeta": {
+ "PUBLIC_GR_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Public.gr seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://publicgr-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "PUBLIC_GR_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Public.gr: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Public.gr refused the API key. Check that PUBLIC_GR_API_KEY is the shop key from your Public.gr seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set PUBLIC_GR_SHOP_ID to a shop you manage.",
+ "404": "The Public.gr seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://publicgr-prod.mirakl.net: Public.gr may have moved its seller back office.",
+ "rate_limited": "Public.gr is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "public_gr_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Public.gr seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Public.gr seller account",
+ "body": "Sign in to the Public.gr seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Public.gr seller back office",
+ "url": "https://publicgr-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Public.gr (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Public reviews each seller application; approval takes about two to three weeks. Sellers need a Greek or EU VAT number and issue their invoices through the Greek myDATA system. Product titles, descriptions and attributes must be in Greek, and sellers ship their orders themselves."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "PUBLIC_GR_API_KEY",
+ "PUBLIC_GR_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Public.gr refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Public.gr Marketplace",
+ "type": "REST",
+ "baseUrl": "https://publicgr-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{PUBLIC_GR_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "public_gr_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use public_gr_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see public_gr_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before public_gr_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in public_gr_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from public_gr_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by public_gr_update_offers or public_gr_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by public_gr_update_offers or public_gr_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging public_gr_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll public_gr_get_offer_export_status about once a minute until COMPLETED, then read each file with public_gr_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from public_gr_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "public_gr_get_offer_export_status",
+ "description": "Status of an offer export started with public_gr_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to public_gr_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by public_gr_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by public_gr_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by public_gr_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Public.gr uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_threads",
+ "description": "List message threads (M11) with customers and Public.gr: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Public.gr)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from public_gr_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in public_gr_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_invoices",
+ "description": "List the accounting documents Public.gr issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Public.gr runs Enhanced Seller Invoicing: invoices and credit notes that Public.gr or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Public.gr (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in public_gr_list_orders and public_gr_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in public_gr_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "public_gr_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from public_gr_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from public_gr_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from public_gr_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in public_gr_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in public_gr_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with public_gr_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with public_gr_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from public_gr_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Public.gr. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from public_gr_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Public.gr) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "public_gr_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Public.gr or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Public.gr) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from public_gr_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "public_gr_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from public_gr_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in public_gr_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from public_gr_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Public.gr handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from public_gr_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from public_gr_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "public_gr_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Public.gr asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with public_gr_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Public.gr defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "public_gr_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Public.gr asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with public_gr_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by public_gr_get_account, also shown in the back office). Leave it out to use PUBLIC_GR_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "PUBLIC_GR_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/intl/public-gr.live.spec.ts b/packages/backend/src/adapters/intl/public-gr.live.spec.ts
new file mode 100644
index 000000000..a2b78269c
--- /dev/null
+++ b/packages/backend/src/adapters/intl/public-gr.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './public-gr.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_PUBLIC_GR_LIVE=1 (GET /api/version needs no key; the shop reads need PUBLIC_GR_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'public-gr', hosts: ['publicgr-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/intl/saks.json b/packages/backend/src/adapters/intl/saks.json
new file mode 100644
index 000000000..7ace01af3
--- /dev/null
+++ b/packages/backend/src/adapters/intl/saks.json
@@ -0,0 +1,2033 @@
+{
+ "slug": "saks",
+ "name": "Saks Marketplace",
+ "aliases": [
+ "Saks Fifth Avenue",
+ "Saks Fifth Avenue Marketplace",
+ "Saks Brand-Direct Marketplace",
+ "Saks seller API",
+ "Saks Mirakl",
+ "saksus-prod.mirakl.net"
+ ],
+ "description": "Run your shop on the Saks brand-direct marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in the United States; sign in with the shop API key from your Saks seller back office.",
+ "instructions": "## Saks Marketplace\nRun your shop on the Saks brand-direct marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Saks, returns, order documents, invoices and transactions. The connector calls the Saks seller platform at `https://saksus-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: the United States.\n\n**Who can sell**: Saks invites the luxury brands it sells; there is no open application. Invited brands set up their shop from a personal invitation link and upload a signed Saks marketplace addendum, a W-9 or W-8, a certificate of insurance, a bank letter and a return address confirmation; Saks then approves the shop in about 7 to 14 business days. The connector needs a seller account that Saks has already opened.\n\nSaks gives integrating brands a separate test store first. Its API key does not work here: generate the key in the production seller back office.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Saks seller back office: `https://saksus-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `SAKS_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `SAKS_SHOP_ID` empty. Only if your user manages several shops on Saks, set `SAKS_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `saks_get_account`). Without it your default shop is used.\n4. Install and run `saks_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Saks seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `saks_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `saks_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `saks_list_offers` for prices and stock and `saks_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `saks_get_products` looks products up in the Saks catalog by EAN or another reference and returns the marketplace product SKU; `saks_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `saks_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `saks_update_tracking` stores the carrier and tracking number (carrier codes come from `saks_list_carriers`) and `saks_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `saks_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `saks_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `saks_list_order_documents`.\n\n**Writes: confirm first.** `saks_accept_order`, `saks_update_tracking`, `saks_ship_order`, `saks_resolve_incident`, `saks_accept_return`, `saks_receive_return`, `saks_update_offers`, `saks_reply_thread`, `saks_create_order_thread` and `saks_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `saks_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `saks_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`saks_get_offer` or `saks_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `saks_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `saks_list_offer_conditions`, logistic class codes from `saks_list_logistic_classes`.\n\n**File imports**: `saks_import_products` (P41) and `saks_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Saks asks for; the connector downloads it and uploads it to Saks. Track them with `saks_list_product_imports` / `saks_get_product_import` and `saks_list_offer_imports` / `saks_get_offer_import`.\n\n**Returns**: `saks_list_returns` (RT11) lists return requests. Where Saks lets the shop decide, `saks_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `saks_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `saks_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `saks_get_thread` reads one with its messages, `saks_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Saks) and `saks_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `saks_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `saks_list_invoices` (IV01) lists the accounting documents Saks issues to the shop and `saks_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Saks uses Enhanced Seller Invoicing, IV01 returns no new documents; use `saks_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `saks_export_offers`, poll `saks_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `saks_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `saks_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `saks_get_account` and the same `shop_id`. Without `shop_id` a call uses `SAKS_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `saks_list_channels` (country sites), `saks_list_carriers`, `saks_list_shipping_zones`, `saks_list_shipping_methods` and `saks_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and Saks can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `saks_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "intl",
+ "category": "e-commerce",
+ "icon": "saks",
+ "docsUrl": "https://marketplace.saks.com",
+ "requiredEnvVars": [
+ "SAKS_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "SAKS_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with Saks and access to its seller back office to generate the shop API key. Saks invites the luxury brands it sells; there is no open application. Invited brands set up their shop from a personal invitation link and upload a signed Saks marketplace addendum, a W-9 or W-8, a certificate of insurance, a bank letter and a return address confirmation; Saks then approves the shop in about 7 to 14 business days.",
+ "envVarMeta": {
+ "SAKS_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "Saks seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://saksus-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "SAKS_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on Saks: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "Saks refused the API key. Check that SAKS_API_KEY is the shop key from your Saks seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set SAKS_SHOP_ID to a shop you manage.",
+ "404": "The Saks seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://saksus-prod.mirakl.net: Saks may have moved its seller back office.",
+ "rate_limited": "Saks is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "saks_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A Saks seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your Saks seller account",
+ "body": "Sign in to the Saks seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the Saks seller back office",
+ "url": "https://saksus-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask Saks (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "Saks invites the luxury brands it sells; there is no open application. Invited brands set up their shop from a personal invitation link and upload a signed Saks marketplace addendum, a W-9 or W-8, a certificate of insurance, a bank letter and a return address confirmation; Saks then approves the shop in about 7 to 14 business days. See [the Saks seller page](https://marketplace.saks.com)."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "SAKS_API_KEY",
+ "SAKS_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "Saks refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "Saks Marketplace",
+ "type": "REST",
+ "baseUrl": "https://saksus-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{SAKS_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "saks_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use saks_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see saks_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before saks_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in saks_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from saks_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by saks_update_offers or saks_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by saks_update_offers or saks_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging saks_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll saks_get_offer_export_status about once a minute until COMPLETED, then read each file with saks_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from saks_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "saks_get_offer_export_status",
+ "description": "Status of an offer export started with saks_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to saks_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by saks_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by saks_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by saks_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references Saks uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_threads",
+ "description": "List message threads (M11) with customers and Saks: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with Saks)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from saks_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in saks_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_invoices",
+ "description": "List the accounting documents Saks issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_document_requests",
+ "description": "List accounting document requests (DR11), used when Saks runs Enhanced Seller Invoicing: invoices and credit notes that Saks or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by Saks (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in saks_list_orders and saks_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in saks_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "saks_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from saks_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from saks_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from saks_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in saks_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in saks_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with saks_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with saks_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from saks_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or Saks. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from saks_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (Saks) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "saks_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, Saks or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (Saks) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from saks_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "saks_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from saks_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in saks_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from saks_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Saks handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from saks_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from saks_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "saks_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format Saks asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with saks_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format Saks defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "saks_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format Saks asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with saks_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by saks_get_account, also shown in the back office). Leave it out to use SAKS_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "SAKS_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/intl/saks.live.spec.ts b/packages/backend/src/adapters/intl/saks.live.spec.ts
new file mode 100644
index 000000000..9700a1273
--- /dev/null
+++ b/packages/backend/src/adapters/intl/saks.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './saks.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_SAKS_LIVE=1 (GET /api/version needs no key; the shop reads need SAKS_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'saks', hosts: ['saksus-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/intl/the-knot.json b/packages/backend/src/adapters/intl/the-knot.json
new file mode 100644
index 000000000..dcda1f8c6
--- /dev/null
+++ b/packages/backend/src/adapters/intl/the-knot.json
@@ -0,0 +1,2033 @@
+{
+ "slug": "the-knot",
+ "name": "The Knot Marketplace",
+ "aliases": [
+ "The Knot",
+ "The Knot Registry Store",
+ "The Knot seller API",
+ "The Knot Worldwide marketplace",
+ "theknot.com marketplace",
+ "The Knot Mirakl"
+ ],
+ "description": "Run your shop on The Knot marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in the United States; sign in with the shop API key from your The Knot seller back office.",
+ "instructions": "## The Knot Marketplace\nRun your shop on The Knot marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and The Knot, returns, order documents, invoices and transactions. The connector calls The Knot seller platform at `https://knot-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: the United States.\n\n**Who can sell**: The Knot chooses the brands it sells in its registry store; no public application page was found, so ask The Knot or your integrator for an introduction. Sellers ship from the United States. The connector needs a seller account that The Knot has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to The Knot seller back office: `https://knot-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `THE_KNOT_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `THE_KNOT_SHOP_ID` empty. Only if your user manages several shops on The Knot, set `THE_KNOT_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `the_knot_get_account`). Without it your default shop is used.\n4. Install and run `the_knot_get_account`: it returns the shop the key belongs to.\n\n**Platform**: The Knot seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `the_knot_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `the_knot_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `the_knot_list_offers` for prices and stock and `the_knot_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `the_knot_get_products` looks products up in The Knot catalog by EAN or another reference and returns the marketplace product SKU; `the_knot_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `the_knot_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `the_knot_update_tracking` stores the carrier and tracking number (carrier codes come from `the_knot_list_carriers`) and `the_knot_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `the_knot_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `the_knot_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `the_knot_list_order_documents`.\n\n**Writes: confirm first.** `the_knot_accept_order`, `the_knot_update_tracking`, `the_knot_ship_order`, `the_knot_resolve_incident`, `the_knot_accept_return`, `the_knot_receive_return`, `the_knot_update_offers`, `the_knot_reply_thread`, `the_knot_create_order_thread` and `the_knot_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `the_knot_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `the_knot_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`the_knot_get_offer` or `the_knot_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `the_knot_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `the_knot_list_offer_conditions`, logistic class codes from `the_knot_list_logistic_classes`.\n\n**File imports**: `the_knot_import_products` (P41) and `the_knot_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format The Knot asks for; the connector downloads it and uploads it to The Knot. Track them with `the_knot_list_product_imports` / `the_knot_get_product_import` and `the_knot_list_offer_imports` / `the_knot_get_offer_import`.\n\n**Returns**: `the_knot_list_returns` (RT11) lists return requests. Where The Knot lets the shop decide, `the_knot_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `the_knot_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `the_knot_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `the_knot_get_thread` reads one with its messages, `the_knot_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is The Knot) and `the_knot_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `the_knot_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `the_knot_list_invoices` (IV01) lists the accounting documents The Knot issues to the shop and `the_knot_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If The Knot uses Enhanced Seller Invoicing, IV01 returns no new documents; use `the_knot_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `the_knot_export_offers`, poll `the_knot_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `the_knot_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `the_knot_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `the_knot_get_account` and the same `shop_id`. Without `shop_id` a call uses `THE_KNOT_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `the_knot_list_channels` (country sites), `the_knot_list_carriers`, `the_knot_list_shipping_zones`, `the_knot_list_shipping_methods` and `the_knot_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and The Knot can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `the_knot_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "intl",
+ "category": "e-commerce",
+ "icon": "the-knot",
+ "docsUrl": "https://knot-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "THE_KNOT_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "THE_KNOT_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with The Knot and access to its seller back office to generate the shop API key. The Knot chooses the brands it sells in its registry store; no public application page was found, so ask The Knot or your integrator for an introduction. Sellers ship from the United States.",
+ "envVarMeta": {
+ "THE_KNOT_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "The Knot seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://knot-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "THE_KNOT_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on The Knot: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "The Knot refused the API key. Check that THE_KNOT_API_KEY is the shop key from your The Knot seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set THE_KNOT_SHOP_ID to a shop you manage.",
+ "404": "The The Knot seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://knot-prod.mirakl.net: The Knot may have moved its seller back office.",
+ "rate_limited": "The Knot is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "the_knot_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A The Knot seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your The Knot seller account",
+ "body": "Sign in to The Knot seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open The Knot seller back office",
+ "url": "https://knot-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask The Knot (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "The Knot chooses the brands it sells in its registry store; no public application page was found, so ask The Knot or your integrator for an introduction. Sellers ship from the United States."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "THE_KNOT_API_KEY",
+ "THE_KNOT_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "The Knot refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "The Knot Marketplace",
+ "type": "REST",
+ "baseUrl": "https://knot-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{THE_KNOT_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "the_knot_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use the_knot_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see the_knot_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before the_knot_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in the_knot_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from the_knot_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by the_knot_update_offers or the_knot_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by the_knot_update_offers or the_knot_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging the_knot_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll the_knot_get_offer_export_status about once a minute until COMPLETED, then read each file with the_knot_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from the_knot_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "the_knot_get_offer_export_status",
+ "description": "Status of an offer export started with the_knot_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to the_knot_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by the_knot_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by the_knot_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by the_knot_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references The Knot uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_threads",
+ "description": "List message threads (M11) with customers and The Knot: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with The Knot)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from the_knot_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in the_knot_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_invoices",
+ "description": "List the accounting documents The Knot issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_document_requests",
+ "description": "List accounting document requests (DR11), used when The Knot runs Enhanced Seller Invoicing: invoices and credit notes that The Knot or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by The Knot (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in the_knot_list_orders and the_knot_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in the_knot_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "the_knot_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from the_knot_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from the_knot_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from the_knot_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in the_knot_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in the_knot_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with the_knot_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with the_knot_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from the_knot_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or The Knot. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from the_knot_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (The Knot) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "the_knot_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, The Knot or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (The Knot) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from the_knot_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "the_knot_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from the_knot_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in the_knot_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from the_knot_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when The Knot handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from the_knot_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from the_knot_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "the_knot_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format The Knot asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with the_knot_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format The Knot defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "the_knot_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format The Knot asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with the_knot_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by the_knot_get_account, also shown in the back office). Leave it out to use THE_KNOT_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "THE_KNOT_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/intl/the-knot.live.spec.ts b/packages/backend/src/adapters/intl/the-knot.live.spec.ts
new file mode 100644
index 000000000..5530d032d
--- /dev/null
+++ b/packages/backend/src/adapters/intl/the-knot.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './the-knot.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_THE_KNOT_LIVE=1 (GET /api/version needs no key; the shop reads need THE_KNOT_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'the-knot', hosts: ['knot-prod.mirakl.net'] });
diff --git a/packages/backend/src/adapters/intl/urbn.json b/packages/backend/src/adapters/intl/urbn.json
new file mode 100644
index 000000000..263ffa7c9
--- /dev/null
+++ b/packages/backend/src/adapters/intl/urbn.json
@@ -0,0 +1,2036 @@
+{
+ "slug": "urbn",
+ "name": "URBN Marketplace",
+ "aliases": [
+ "Urban Outfitters",
+ "Urban Outfitters Marketplace",
+ "UO MRKT",
+ "Anthropologie",
+ "Curated by Anthropologie",
+ "Free People",
+ "FP Mart",
+ "URBN seller API",
+ "URBN Mirakl"
+ ],
+ "description": "Run your shop on the URBN marketplaces (Urban Outfitters, Anthropologie and Free People) from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, imports, messages, returns, invoices and transactions. The marketplace sells in the United States; sign in with the shop API key from your URBN seller back office.",
+ "instructions": "## URBN Marketplace\nRun your shop on the URBN marketplaces (Urban Outfitters, Anthropologie and Free People) from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and URBN, returns, order documents, invoices and transactions. The connector calls the URBN seller platform at `https://urbanoutfitters-prod.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: the United States.\n\n**Who can sell**: URBN invites the brands it sells on urbanoutfitters.com (UO Marketplace), anthropologie.com (Curated by Anthropologie) and freepeople.com (FP Mart); each brand site chooses its own sellers. Sellers sign the URBN Marketplace Seller Agreement, ship every order themselves and handle their own returns. The connector needs a seller account that URBN has already opened.\n\nThe seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it.\n\n**Setup (about 5 minutes)**\n1. Sign in to the URBN seller back office: `https://urbanoutfitters-prod.mirakl.net/login`.\n2. In the back office open your user name (top right) > **My user settings** > **API key** and click **Generate a new key** (or copy the existing key). Paste it into `URBN_API_KEY`. The key is sent as is in the `Authorization` header, without `Bearer`. Generating a new key invalidates the old one, so any other tool using it stops working.\n3. Leave `URBN_SHOP_ID` empty. Only if your user manages several shops on URBN, set `URBN_SHOP_ID` to the numeric id of the shop this connector should work on (shown on the dashboard of the back office next to **Identifier** or **Shop ID**, and returned as `shop_id` by `urbn_get_account`). Without it your default shop is used.\n4. Install and run `urbn_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the URBN seller back office runs on Mirakl software, so the operation codes in the tool descriptions (OR11, OF24 and so on) and the error names are those of that software.\n\n**Where to start**: `urbn_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `urbn_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `urbn_list_offers` for prices and stock and `urbn_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `urbn_get_products` looks products up in the URBN catalog by EAN or another reference and returns the marketplace product SKU; `urbn_list_product_offers` lists the offers of every shop for given products, best price first, at about 5 calls a minute.\n\n**Order workflow**: a new order waits in `WAITING_ACCEPTANCE`. `urbn_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `urbn_update_tracking` stores the carrier and tracking number (carrier codes come from `urbn_list_carriers`) and `urbn_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `urbn_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `urbn_resolve_incident` closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by `urbn_list_order_documents`.\n\n**Writes: confirm first.** `urbn_accept_order`, `urbn_update_tracking`, `urbn_ship_order`, `urbn_resolve_incident`, `urbn_accept_return`, `urbn_receive_return`, `urbn_update_offers`, `urbn_reply_thread`, `urbn_create_order_thread` and `urbn_import_products` act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. `urbn_import_offers` can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.\n\n**Updating offers (prices and stock)**: `urbn_update_offers` (OF24) replaces the whole offer. Every field you leave out is reset: a missing `quantity` becomes 0, a missing `discount` or `description` is deleted. Always read the offer first (`urbn_get_offer` or `urbn_list_offers` with `sku`) and send it back complete with only the intended change: `shop_sku`, `product_id` and `product_id_type` (from `product_references`), `state_code`, `price`, `quantity`, `leadtime_to_ship`, `logistic_class` (its code), `min_quantity_alert`, `description`, `discount`, `all_prices`, `available_started` / `available_ended` (read as `available_start_date` / `available_end_date`) and any `offer_additional_fields`. Leave `update_delete` empty or `update`. The call returns an `import_id`; the change is applied asynchronously, so check it with `urbn_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `urbn_list_offer_conditions`, logistic class codes from `urbn_list_logistic_classes`.\n\n**File imports**: `urbn_import_products` (P41) and `urbn_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format URBN asks for; the connector downloads it and uploads it to URBN. Track them with `urbn_list_product_imports` / `urbn_get_product_import` and `urbn_list_offer_imports` / `urbn_get_offer_import`.\n\n**Returns**: `urbn_list_returns` (RT11) lists return requests. Where URBN lets the shop decide, `urbn_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `urbn_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `urbn_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `urbn_get_thread` reads one with its messages, `urbn_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is URBN) and `urbn_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `urbn_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `urbn_list_invoices` (IV01) lists the accounting documents URBN issues to the shop and `urbn_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If URBN uses Enhanced Seller Invoicing, IV01 returns no new documents; use `urbn_list_document_requests` (DR11) and the transactions then.\n\n**Whole catalogue**: to read every offer (a stock or price check across the catalogue, counting offers), start an export with `urbn_export_offers`, poll `urbn_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `urbn_get_offer_export_file`; `include_fields` keeps only the columns you need. A full export is allowed once a day; for what changed since, pass `last_request_date` (a differential export, at most once a minute). Do not page through every offer with `urbn_list_offers`: it is meant for a few offers at a time and answers 429 when paged through a large catalogue.\n\n**Several shops**: every tool takes an optional `shop_id`. A user who manages several shops on this marketplace (an agency, or one shop per country) can work on all of them with one install: pass the shop's id on each call and check which shop it is with `urbn_get_account` and the same `shop_id`. Without `shop_id` a call uses `URBN_SHOP_ID`, or the user's default shop when that is empty. Ask the user for the ids of their shops; the back office shows them.\n\n**Reference lists**: `urbn_list_channels` (country sites), `urbn_list_carriers`, `urbn_list_shipping_zones`, `urbn_list_shipping_methods` and `urbn_list_logistic_classes` change rarely; read them once per conversation.\n\n**Pagination**: orders, offers, invoices and product imports page with `max` (at most 100) and `offset`. Threads, returns, transactions, document requests and offer imports return a `next_page_token`; pass it as `page_token` to get the next page (all other filters are then ignored) until it is missing.\n\n**Dates** are ISO 8601, e.g. `2026-10-01T00:00:00Z`; answers are in UTC.\n\n**Rate limits**: Each API has its own limit and URBN can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `urbn_get_account` and the reference lists about once a day. A 429 carries a `Retry-After` header with the seconds to wait; do not retry in a loop.\n\n**Errors**: 401 means the key is wrong or was replaced by a newer one, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop or that the marketplace does not use that feature, such as returns, 400 a wrong parameter or an order in the wrong state (the message names it, e.g. `ORDER_INVALID_STATE`).",
+ "region": "intl",
+ "category": "e-commerce",
+ "icon": "urbn",
+ "docsUrl": "https://urbanoutfitters-prod.mirakl.net/login",
+ "requiredEnvVars": [
+ "URBN_API_KEY"
+ ],
+ "optionalEnvVars": [
+ "URBN_SHOP_ID"
+ ],
+ "prerequisites": "An open seller account with URBN and access to its seller back office to generate the shop API key. URBN invites the brands it sells on urbanoutfitters.com (UO Marketplace), anthropologie.com (Curated by Anthropologie) and freepeople.com (FP Mart); each brand site chooses its own sellers. Sellers sign the URBN Marketplace Seller Agreement, ship every order themselves and handle their own returns.",
+ "envVarMeta": {
+ "URBN_API_KEY": {
+ "label": "Shop API key",
+ "kind": "credential",
+ "secret": true,
+ "help": "URBN seller back office: your user name (top right) > My user settings > API key > Generate a new key. Generating a new key invalidates the previous one.",
+ "link": "https://urbanoutfitters-prod.mirakl.net/login",
+ "pattern": "^[A-Za-z0-9_-]{16,128}$",
+ "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces."
+ },
+ "URBN_SHOP_ID": {
+ "label": "Shop ID (optional)",
+ "kind": "setting",
+ "help": "Only when your user manages several shops on URBN: the numeric id of the shop to use. Leave empty to use your default shop.",
+ "example": "2001",
+ "pattern": "^[0-9]+$",
+ "patternMessage": "The shop id is a number."
+ }
+ },
+ "verifyHints": {
+ "401": "URBN refused the API key. Check that URBN_API_KEY is the shop key from your URBN seller back office, under your user name (top right) > My user settings > API key, and that it was not replaced by a newer key there.",
+ "403": "The key works, but your user is not allowed to do this on the shop. Ask the shop administrator for the role, or set URBN_SHOP_ID to a shop you manage.",
+ "404": "The URBN seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://urbanoutfitters-prod.mirakl.net: URBN may have moved its seller back office.",
+ "rate_limited": "URBN is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again."
+ },
+ "probe": {
+ "tool": "urbn_get_account"
+ },
+ "setupGuide": {
+ "effort": "api_key",
+ "minutes": 5,
+ "examples": [
+ "Which orders are waiting for my acceptance?",
+ "Which customer messages still need a reply?",
+ "Show the price and stock of my offer for SKU 4711"
+ ],
+ "needs": [
+ "A URBN seller account that is already open",
+ "A user who can open **My user settings** in the seller back office"
+ ],
+ "steps": [
+ {
+ "id": "open-account",
+ "title": "Open your URBN seller account",
+ "body": "Sign in to the URBN seller back office. Then open the menu below and create a key, or copy the one that is already there.",
+ "action": {
+ "label": "Open the URBN seller back office",
+ "url": "https://urbanoutfitters-prod.mirakl.net/login"
+ },
+ "values": [
+ {
+ "label": "Menu",
+ "value": "Your user name (top right) > My user settings > API key",
+ "pick": true
+ },
+ {
+ "label": "Button",
+ "value": "Generate a new key",
+ "pick": true,
+ "note": "Replaces the previous key: anything else that uses the old key stops working."
+ }
+ ],
+ "problems": [
+ {
+ "q": "I do not see an API key tab",
+ "a": "API access is switched on per shop. Ask URBN (your marketplace contact or the seller support) to enable it for your user."
+ },
+ {
+ "q": "I manage several shops",
+ "a": "The key belongs to your user, not to one shop. Note the id of the shop to use, shown on the dashboard next to **Identifier** or **Shop ID**: you enter it in the next step."
+ },
+ {
+ "q": "I do not have a seller account yet",
+ "a": "URBN invites the brands it sells on urbanoutfitters.com (UO Marketplace), anthropologie.com (Curated by Anthropologie) and freepeople.com (FP Mart); each brand site chooses its own sellers. Sellers sign the URBN Marketplace Seller Agreement, ship every order themselves and handle their own returns."
+ }
+ ]
+ },
+ {
+ "id": "api-key",
+ "title": "Paste the key",
+ "body": "Paste the key alone, without `Bearer`, quotes or spaces. Leave the shop ID empty unless your user manages several shops.",
+ "fields": [
+ "URBN_API_KEY",
+ "URBN_SHOP_ID"
+ ],
+ "problems": [
+ {
+ "q": "URBN refused the key",
+ "a": "Copy it again from the back office. If a newer key was generated, only the newest one works."
+ },
+ {
+ "q": "Which shop ID do I enter?",
+ "a": "The numeric id on the dashboard of the back office, next to **Identifier** or **Shop ID**. With a single shop, leave the field empty. To work on several shops, set the connector up once per shop."
+ }
+ ]
+ }
+ ]
+ },
+ "connector": {
+ "name": "URBN Marketplace",
+ "type": "REST",
+ "baseUrl": "https://urbanoutfitters-prod.mirakl.net/api",
+ "authType": "API_KEY",
+ "authConfig": {
+ "headerName": "Authorization",
+ "apiKey": "{{URBN_API_KEY}}"
+ },
+ "headers": {
+ "Accept": "application/json"
+ }
+ },
+ "tools": [
+ {
+ "name": "urbn_get_account",
+ "description": "Read the shop behind the API key on this marketplace (A01): shop id and name, state, channels, currency, grade and approval rate, contact and shipping settings. The quickest check that the key works. Meant to be called about once a day, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/account",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_orders",
+ "description": "List orders (OR11) with their lines, customer, shipping address, prices, state and incidents. Filter by state (e.g. WAITING_ACCEPTANCE for orders to accept, SHIPPING for orders to ship), by creation or update date, by order id or channel. Pages with max (at most 100) and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_state_codes": {
+ "type": "string",
+ "description": "Comma-separated order states: STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED."
+ },
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids (e.g. 1234567-A), up to 100."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Orders created at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z)."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Orders created before this time, ISO 8601."
+ },
+ "start_update_date": {
+ "type": "string",
+ "description": "Orders updated at or after this time, ISO 8601. Best filter for polling changes."
+ },
+ "end_update_date": {
+ "type": "string",
+ "description": "Orders updated before this time, ISO 8601."
+ },
+ "has_incident": {
+ "type": "boolean",
+ "description": "true: only orders with an open incident; false: only orders without one."
+ },
+ "customer_debited": {
+ "type": "boolean",
+ "description": "true: only orders the customer has paid."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated sales channel codes (country sites of the marketplace)."
+ },
+ "order_references_for_seller": {
+ "type": "string",
+ "description": "Comma-separated order references you set for yourself."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Orders per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of orders to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "order_state_codes": "$order_state_codes",
+ "order_ids": "$order_ids",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "start_update_date": "$start_update_date",
+ "end_update_date": "$end_update_date",
+ "has_incident": "$has_incident",
+ "customer_debited": "$customer_debited",
+ "channel_codes": "$channel_codes",
+ "order_references_for_seller": "$order_references_for_seller",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_offers",
+ "description": "List the shop's offers (OF21): SKU, product, price and discount, all channel prices, quantity in stock, condition, lead time and whether the offer is active (with the inactivity reasons). Filter by sku or product. Pages with max (at most 100) and offset. Meant for a few offers at a time: paging through a whole catalogue is rate-limited (429); to read every offer use urbn_export_offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "Your offer SKU (shop_sku)."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "The marketplace's product SKU."
+ },
+ "offer_state_codes": {
+ "type": "string",
+ "description": "Comma-separated offer condition codes (see urbn_list_offer_conditions)."
+ },
+ "pricing_channel_code": {
+ "type": "string",
+ "description": "Channel whose prices should be returned as the applicable price."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Offers per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of offers to skip, for paging."
+ },
+ "sort": {
+ "type": "string",
+ "enum": [
+ "totalPrice",
+ "price",
+ "productTitle"
+ ],
+ "description": "Sort field (default totalPrice)."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction (default asc)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "sku": "$sku",
+ "product_id": "$product_id",
+ "offer_state_codes": "$offer_state_codes",
+ "pricing_channel_code": "$pricing_channel_code",
+ "max": "$max",
+ "offset": "$offset",
+ "sort": "$sort",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_offer",
+ "description": "Read one offer in full by its offer id (OF22): every price field, discount, quantity, condition, logistic class, lead time and custom fields. Read it before urbn_update_offers, which needs the complete offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offer_id": {
+ "type": "integer",
+ "description": "Offer id on the marketplace (offer_id in urbn_list_offers), not your SKU."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offer_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/{offer_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_offer_conditions",
+ "description": "List the offer conditions (OF61) the marketplace accepts, e.g. new or used, with the code to put in state_code when updating offers.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/states",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_offer_imports",
+ "description": "List offer imports and updates (OF04), from files and from urbn_update_offers: status (WAITING, RUNNING, COMPLETE, FAILED), lines read, in success and in error, offers inserted, updated and deleted. Newest first. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "WAITING_SYNCHRONIZATION_PRODUCT",
+ "WAITING",
+ "RUNNING",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "Only imports in this mode."
+ },
+ "start_date": {
+ "type": "string",
+ "description": "Imports created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Imports created before this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "mode": "$mode",
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_offer_import",
+ "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by urbn_update_offers or urbn_import_offers: status, lines in success and in error, offers inserted, updated and deleted, and whether an error report exists.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by urbn_update_offers or urbn_import_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_export_offers",
+ "description": "Start an export of all the shop's offers as files (OF52), the way to read the whole catalogue (every SKU with price and stock) instead of paging urbn_list_offers. Without last_request_date it exports every active offer (a full export: at most once a day); with it, only offers changed since then, including deleted and inactive ones (a differential export: at most once a minute). Returns a tracking_id: poll urbn_get_offer_export_status about once a minute until COMPLETED, then read each file with urbn_get_offer_export_file. Keep files small with include_fields (for example shop-sku, product-sku, quantity, price) and items_per_chunk. Asking again for the same export returns the same tracking_id.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "export_type": {
+ "type": "string",
+ "enum": [
+ "application/json",
+ "text/csv"
+ ],
+ "default": "application/json",
+ "description": "File format: application/json (default here) or text/csv."
+ },
+ "include_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only these fields, by their export names (for example shop-sku, product-sku, quantity, price, state-code, active). All fields when left out."
+ },
+ "channel_codes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only offers sellable on these channels (codes from urbn_list_channels)."
+ },
+ "include_inactive_offers": {
+ "type": "boolean",
+ "description": "Full export only: true to include inactive offers. Leave it out with last_request_date, which already returns inactive and deleted offers (the call is refused otherwise)."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Differential export: only offers changed since this time, ISO 8601 (e.g. 2026-11-16T08:00:00Z). Leave out for a full export."
+ },
+ "items_per_chunk": {
+ "type": "integer",
+ "description": "Maximum offers per file. Smaller files are easier to read one at a time."
+ },
+ "megabytes_per_chunk": {
+ "type": "integer",
+ "description": "Maximum size of each file in megabytes."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/export/async",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "export_type": "$export_type",
+ "include_fields": "$include_fields",
+ "channel_codes": "$channel_codes",
+ "include_inactive_offers": "$include_inactive_offers",
+ "last_request_date": "$last_request_date",
+ "items_per_chunk": "$items_per_chunk",
+ "megabytes_per_chunk": "$megabytes_per_chunk"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": true
+ }
+ },
+ {
+ "name": "urbn_get_offer_export_status",
+ "description": "Status of an offer export started with urbn_export_offers (OF53): PENDING, COMPLETED or FAILED (with error.code and error.detail), and once COMPLETED the urls of the files. Call it about once a minute until it is no longer PENDING (never more than every 10 seconds). Each url looks like .../offers/export/async/file/?file=: pass that tracking_id and the file value to urbn_get_offer_export_file.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id returned by urbn_export_offers."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/status/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_offer_export_file",
+ "description": "Read one file of a completed offer export (OF54): the offers with their SKU, product, quantity, prices and the other exported fields, as JSON or CSV depending on export_type. Take tracking_id and file from one of the urls returned by urbn_get_offer_export_status (the file value is the part after ?file=, decoded, e.g. of52-export//0.json) and read the files one by one.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "tracking_id": {
+ "type": "string",
+ "description": "tracking_id of the export (the path segment after /file/ in the url)."
+ },
+ "file": {
+ "type": "string",
+ "description": "The file value of the url, decoded: of52-export//0.json (slashes, not %2F)."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "tracking_id",
+ "file"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/offers/export/async/file/{tracking_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "file": "$file",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_product_imports",
+ "description": "List product imports (P51) with their status (WAITING, RUNNING, SENT, COMPLETE, FAILED, CANCELLED), the transformation counts and the integration result (products synchronized, rejected, invalid). Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "CANCELLED",
+ "WAITING",
+ "RUNNING",
+ "SENT",
+ "COMPLETE",
+ "FAILED"
+ ],
+ "description": "Only imports in this status."
+ },
+ "last_request_date": {
+ "type": "string",
+ "description": "Only imports that changed since this time, ISO 8601. Without it every product import is returned."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Imports per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of imports to skip, for paging."
+ },
+ "order": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "description": "Sort direction by creation date (default asc). desc lists the newest first."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "status": "$status",
+ "last_request_date": "$last_request_date",
+ "max": "$max",
+ "offset": "$offset",
+ "order": "$order",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_product_import",
+ "description": "Read the status of one product import (P42) by its import_id: import status, reason, transformation counts and the integration details (synchronized, rejected, invalid, wrong identifiers).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "import_id": {
+ "type": "integer",
+ "description": "The import_id returned by urbn_import_products."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "import_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/imports/{import_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_products",
+ "description": "Look up products in the marketplace catalog by their identifiers (P31), e.g. EAN, and get the marketplace product SKU, title and category. Up to 100 products per call.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000,EAN|4000000000000. The types are the product references URBN uses (EAN, UPC...); SKU and SHOP_SKU are not accepted."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "product_references"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "product_references": "$product_references",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_product_offers",
+ "description": "List the offers of every shop for given products (P11), sorted by best price, to compare your price with the competition. Give product_ids or product_references (up to 100). The limit is about 5 calls a minute.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "product_ids": {
+ "type": "string",
+ "description": "Comma-separated marketplace product SKUs."
+ },
+ "product_references": {
+ "type": "string",
+ "description": "Comma-separated | pairs, e.g. EAN|3276000000000."
+ },
+ "all_offers": {
+ "type": "boolean",
+ "description": "true to include inactive offers (default: active offers only)."
+ },
+ "channel_codes": {
+ "type": "string",
+ "description": "Comma-separated channel codes: only offers sold on these channels."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Products per page, 1 to 100."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of products to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/products/offers",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "product_ids": "$product_ids",
+ "product_references": "$product_references",
+ "all_offers": "$all_offers",
+ "channel_codes": "$channel_codes",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_threads",
+ "description": "List message threads (M11) with customers and URBN: topic, linked order or offer, participants, last message date and since when a shop reply is needed. Filter with entity_type and entity_id for one order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "entity_type": {
+ "type": "string",
+ "enum": [
+ "MMP_ORDER",
+ "MMP_OFFER",
+ "MPS_ORDER",
+ "MPS_SERVICE",
+ "SELLER_OPERATOR"
+ ],
+ "description": "Only threads on this kind of entity: MMP_ORDER (orders), MMP_OFFER (offers), SELLER_OPERATOR (with URBN)."
+ },
+ "entity_id": {
+ "type": "string",
+ "description": "Comma-separated entity ids, e.g. order ids. Needs entity_type."
+ },
+ "updated_since": {
+ "type": "string",
+ "description": "Only threads changed at or after this time, ISO 8601."
+ },
+ "with_messages": {
+ "type": "boolean",
+ "description": "true to include the messages (the last 100 of each thread)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Threads per page, 1 to 100 (default 50)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "entity_type": "$entity_type",
+ "entity_id": "$entity_id",
+ "updated_since": "$updated_since",
+ "with_messages": "$with_messages",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_get_thread",
+ "description": "Read one message thread (M10) with all its messages, senders, recipients, attachments and the linked order or offer.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id (a UUID) from urbn_list_threads."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/inbox/threads/{thread_id}",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_returns",
+ "description": "List return requests (RT11) with their state, return lines, reason, RMA, tracking and the linked order. Filter by state, order or date. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_state": {
+ "type": "string",
+ "description": "Only returns in this state: WAITING_ACCEPTANCE, IN_PROGRESS, REFUSED, RECEIVED, NO_RECEPTION, CLOSED or CANCELED."
+ },
+ "order_commercial_id": {
+ "type": "string",
+ "description": "Only returns of this order (commercial id)."
+ },
+ "return_creation_date_from": {
+ "type": "string",
+ "description": "Returns created after this time, ISO 8601."
+ },
+ "return_creation_date_to": {
+ "type": "string",
+ "description": "Returns created before this time, ISO 8601."
+ },
+ "return_last_updated_from": {
+ "type": "string",
+ "description": "Returns updated after this time, ISO 8601."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Returns per page, 1 to 100 (default 10)."
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/returns",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "return_state": "$return_state",
+ "order_commercial_id": "$order_commercial_id",
+ "return_creation_date_from": "$return_creation_date_from",
+ "return_creation_date_to": "$return_creation_date_to",
+ "return_last_updated_from": "$return_last_updated_from",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_reasons",
+ "description": "List the marketplace's reason codes (RE01): incident, cancellation, refund and message reasons, with their labels and whether the shop may use them. Use a code as the topic of a message thread.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "locale": {
+ "type": "string",
+ "description": "Language of the labels, e.g. fr_FR. Only a locale active on this marketplace works (others answer 400); leave empty for the default."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/reasons",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "locale": "$locale",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_carriers",
+ "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in urbn_update_tracking.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/carriers",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_invoices",
+ "description": "List the accounting documents URBN issues to the shop (IV01): invoices and credit notes with period, totals with and without tax, commission details, payment state and due date. Pages with max and offset.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "start_date": {
+ "type": "string",
+ "description": "Documents created at or after this time, ISO 8601."
+ },
+ "end_date": {
+ "type": "string",
+ "description": "Documents created before this time, ISO 8601."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "ALL",
+ "AUTO_INVOICE",
+ "MANUAL_INVOICE",
+ "MANUAL_CREDIT"
+ ],
+ "description": "Document type. The default is AUTO_INVOICE (the regular billing-cycle invoices); ALL includes manual invoices and credits."
+ },
+ "payment_status": {
+ "type": "string",
+ "enum": [
+ "PENDING",
+ "PAID",
+ "FAILED"
+ ],
+ "description": "Only documents in this payment state."
+ },
+ "max": {
+ "type": "integer",
+ "description": "Documents per page, 1 to 100.",
+ "default": 20
+ },
+ "offset": {
+ "type": "integer",
+ "description": "Number of documents to skip, for paging."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/invoices",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "start_date": "$start_date",
+ "end_date": "$end_date",
+ "type": "$type",
+ "payment_status": "$payment_status",
+ "max": "$max",
+ "offset": "$offset",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_transactions",
+ "description": "List the shop's transaction lines (TL02): order amounts, shipping, commissions, refunds, manual credits and payouts, with amount, type, payment state, balance and the accounting document they belong to. Filter by date, type or order. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "date_created_from": {
+ "type": "string",
+ "description": "Lines created at or after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Lines created before this time, ISO 8601."
+ },
+ "transaction_date_from": {
+ "type": "string",
+ "description": "Lines whose transaction date is at or after this time, ISO 8601."
+ },
+ "transaction_date_to": {
+ "type": "string",
+ "description": "Lines whose transaction date is before this time, ISO 8601."
+ },
+ "last_updated_from": {
+ "type": "string",
+ "description": "Lines updated at or after this time, ISO 8601."
+ },
+ "transaction_type": {
+ "type": "string",
+ "description": "Only this transaction type, e.g. ORDER_AMOUNT, ORDER_SHIPPING_AMOUNT, COMMISSION_FEE, REFUND_ORDER_AMOUNT, PAYMENT."
+ },
+ "payment_state": {
+ "type": "string",
+ "description": "Only lines in this payment state: PENDING, PAYABLE, PAID, NOT_APPLICABLE or RESERVE."
+ },
+ "order_id": {
+ "type": "string",
+ "description": "Only lines of this order."
+ },
+ "accounting_document_number": {
+ "type": "string",
+ "description": "Only lines of this accounting document (invoice number)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Lines per page, 1 to 2000.",
+ "default": 100
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/sellerpayment/transactions_logs",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "transaction_date_from": "$transaction_date_from",
+ "transaction_date_to": "$transaction_date_to",
+ "last_updated_from": "$last_updated_from",
+ "transaction_type": "$transaction_type",
+ "payment_state": "$payment_state",
+ "order_id": "$order_id",
+ "accounting_document_number": "$accounting_document_number",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_document_requests",
+ "description": "List accounting document requests (DR11), used when URBN runs Enhanced Seller Invoicing: invoices and credit notes that URBN or the shop issues, with state, type, issuer, document number, amounts and payment state. Filter by date, state, type or document number. Pass next_page_token back as page_token for more.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "state": {
+ "type": "string",
+ "enum": [
+ "STAGING",
+ "TO_PROCESS",
+ "ISSUED",
+ "CANCELED"
+ ],
+ "description": "Only requests in this state. TO_PROCESS are documents the shop still has to issue."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "INVOICE",
+ "CREDIT_NOTE"
+ ],
+ "description": "Only invoices or only credit notes."
+ },
+ "issuer_type": {
+ "type": "string",
+ "enum": [
+ "OPERATOR",
+ "SHOP"
+ ],
+ "description": "Only documents issued by URBN (OPERATOR), or by the shop (SHOP)."
+ },
+ "document_number": {
+ "type": "string",
+ "description": "Only the request with this accounting document number."
+ },
+ "date_created_from": {
+ "type": "string",
+ "description": "Requests created after this time, ISO 8601."
+ },
+ "date_created_to": {
+ "type": "string",
+ "description": "Requests created before this time, ISO 8601."
+ },
+ "issue_date_from": {
+ "type": "string",
+ "description": "Requests issued after this time, ISO 8601."
+ },
+ "issue_date_to": {
+ "type": "string",
+ "description": "Requests issued before this time, ISO 8601."
+ },
+ "payment_state": {
+ "type": "string",
+ "enum": [
+ "PAID",
+ "PENDING"
+ ],
+ "description": "Only paid or pending documents (purchase order and fee requests only)."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Requests per page.",
+ "default": 20
+ },
+ "page_token": {
+ "type": "string",
+ "description": "next_page_token from the previous page. All other filters are then ignored."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/document-request/requests",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "state": "$state",
+ "type": "$type",
+ "issuer_type": "$issuer_type",
+ "document_number": "$document_number",
+ "date_created_from": "$date_created_from",
+ "date_created_to": "$date_created_to",
+ "issue_date_from": "$issue_date_from",
+ "issue_date_to": "$issue_date_to",
+ "payment_state": "$payment_state",
+ "limit": "$limit",
+ "page_token": "$page_token",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_order_documents",
+ "description": "List the documents attached to one or more orders (OR72): delivery notes, shipping labels, customer invoices and other files, with id, file name, type code and upload date. Download links are not part of this tool; open the file in the back office.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_ids": {
+ "type": "string",
+ "description": "Comma-separated order ids, e.g. 1234567-A,1234568-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_ids"
+ ]
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/orders/documents",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "order_ids": "$order_ids",
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_channels",
+ "description": "List the marketplace's sales channels (CH11), usually one per country site, with code and label. Use the codes as channel_codes in urbn_list_orders and urbn_list_product_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/channels",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_shipping_zones",
+ "description": "List the active shipping zones of the marketplace (SH11) with code and label, e.g. mainland France or Corsica. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/zones",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_shipping_methods",
+ "description": "List the active shipping methods of the marketplace (SH12), e.g. standard, express or pick-up, with code, label, whether a tracking number is mandatory and whether it is click and collect. The code appears as shipping_type_code on orders. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/types",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_list_logistic_classes",
+ "description": "List the marketplace's logistic classes (SH31), the size or weight bands that decide shipping prices, with code and label. Use the code as logistic_class in urbn_update_offers. Changes rarely: call it once, not on every question.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ }
+ },
+ "endpointMapping": {
+ "method": "GET",
+ "path": "/shipping/logistic_classes",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ }
+ },
+ {
+ "name": "urbn_accept_order",
+ "description": "Accept or refuse the lines of an order waiting for acceptance (OR21). Every line of the order must be listed. Refusing a line cancels it for good. Acts on the live marketplace: name the order and the decision per line and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_lines": {
+ "type": "array",
+ "description": "One entry per order line: {\"id\": \"\", \"accepted\": true}. Use accepted false only when the user explicitly wants to refuse that line.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "order_line_id from urbn_list_orders."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true to accept, false to refuse (cancels the line)."
+ }
+ },
+ "required": [
+ "id",
+ "accepted"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_lines"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/accept",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "order_lines": "$order_lines"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_update_tracking",
+ "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from urbn_list_carriers, or carrier_name with carrier_url for a carrier the marketplace does not know. Acts on the live marketplace and is shown to the customer: name the order and the tracking data and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "tracking_number": {
+ "type": "string",
+ "description": "The carrier's tracking number."
+ },
+ "carrier_code": {
+ "type": "string",
+ "description": "Carrier code from urbn_list_carriers."
+ },
+ "carrier_name": {
+ "type": "string",
+ "description": "Carrier name, for a carrier that is not in urbn_list_carriers."
+ },
+ "carrier_url": {
+ "type": "string",
+ "description": "Full tracking URL, for a carrier that is not in urbn_list_carriers."
+ },
+ "carrier_standard_code": {
+ "type": "string",
+ "description": "Standard carrier code, when the marketplace uses them."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/tracking",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "tracking_number": "$tracking_number",
+ "carrier_code": "$carrier_code",
+ "carrier_name": "$carrier_name",
+ "carrier_url": "$carrier_url",
+ "carrier_standard_code": "$carrier_standard_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_ship_order",
+ "description": "Confirm that an order in SHIPPING has been shipped (OR24); it moves to SHIPPED and the customer is notified. Set the tracking first with urbn_update_tracking. Cannot be undone: name the order and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/ship",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_update_offers",
+ "description": "Create or update offers, including price and stock (OF24). Replaces each offer completely: every field left out is reset (a missing quantity becomes 0), so read the offer first and send it back whole with only the intended change. Returns an import_id to check with urbn_get_offer_import. Acts on the live marketplace: list each SKU with the old and new values and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "Offers to create or update. Each needs shop_sku, state_code and price; product_id and product_id_type are required when the offer is new. Send every field the offer has (quantity, leadtime_to_ship, logistic_class, description, discount, all_prices, min_quantity_alert, available_started, available_ended, offer_additional_fields...), otherwise it is reset. Leave update_delete empty or set it to update.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "shop_sku": {
+ "type": "string",
+ "description": "Your SKU of the offer."
+ },
+ "product_id": {
+ "type": "string",
+ "description": "Product reference, e.g. the EAN."
+ },
+ "product_id_type": {
+ "type": "string",
+ "description": "Type of product_id, e.g. EAN, or SHOP_SKU / SKU as the marketplace allows."
+ },
+ "state_code": {
+ "type": "string",
+ "description": "Offer condition code from urbn_list_offer_conditions."
+ },
+ "price": {
+ "type": "number",
+ "description": "Price in the marketplace currency."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Stock available. If left out it is set to 0."
+ },
+ "leadtime_to_ship": {
+ "type": "integer",
+ "description": "Days to ship."
+ },
+ "logistic_class": {
+ "type": "string",
+ "description": "Logistic class code."
+ },
+ "description": {
+ "type": "string",
+ "description": "Offer description."
+ },
+ "discount": {
+ "type": "object",
+ "description": "Discount {price, start_date, end_date}; left out means deleted."
+ },
+ "all_prices": {
+ "type": "array",
+ "description": "Channel and volume prices, as read from the offer.",
+ "items": {
+ "type": "object"
+ }
+ },
+ "update_delete": {
+ "type": "string",
+ "enum": [
+ "update"
+ ],
+ "description": "Leave empty or update. Deleting offers is not done with this tool."
+ }
+ },
+ "required": [
+ "shop_sku",
+ "state_code",
+ "price"
+ ]
+ }
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "offers"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "offers": "$offers"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_reply_thread",
+ "description": "Reply in a message thread (M12) to the customer or URBN. The message is delivered at once and cannot be taken back: show the user the text and the recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "thread_id": {
+ "type": "string",
+ "description": "Thread id from urbn_list_threads."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients, e.g. [{\"type\": \"CUSTOMER\"}] or [{\"type\": \"OPERATOR\"}]. type is CUSTOMER, OPERATOR (URBN) or SHOP; add id only to pick one participant of the thread.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR",
+ "SHOP"
+ ]
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ]
+ }
+ },
+ "topic": {
+ "type": "object",
+ "description": "Optional new topic: {\"type\": \"FREE_TEXT\", \"value\": \"...\"} or {\"type\": \"REASON_CODE\", \"value\": \"\"}."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "thread_id",
+ "body",
+ "to"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/inbox/threads/{thread_id}/message",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "message_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": "$topic"
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "urbn_create_order_thread",
+ "description": "Start a new message thread on an order (OR43) with the customer, URBN or both. The message is delivered at once: show the user the text, topic and recipients and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "body": {
+ "type": "string",
+ "description": "Message text (up to 50,000 characters)."
+ },
+ "to": {
+ "type": "array",
+ "description": "Recipients: CUSTOMER, OPERATOR (URBN) or both.",
+ "items": {
+ "type": "string",
+ "enum": [
+ "CUSTOMER",
+ "OPERATOR"
+ ]
+ }
+ },
+ "topic_type": {
+ "type": "string",
+ "enum": [
+ "FREE_TEXT",
+ "REASON_CODE"
+ ],
+ "description": "FREE_TEXT for your own subject, REASON_CODE for a code from urbn_list_reasons.",
+ "default": "FREE_TEXT"
+ },
+ "topic_value": {
+ "type": "string",
+ "description": "The subject text, or the reason code."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "body",
+ "to",
+ "topic_value"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/orders/{order_id}/threads",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "thread_input": {
+ "__json": {
+ "body": "$body",
+ "to": "$to",
+ "topic": {
+ "type": "$topic_type",
+ "value": "$topic_value"
+ }
+ }
+ }
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "urbn_resolve_incident",
+ "description": "Mark the open incident on one order line as resolved (OR64), once the customer's problem is solved. reason_code must be an INCIDENT_CLOSE reason from urbn_list_reasons. Closes the incident on the live marketplace: name the order, the line and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "order_id": {
+ "type": "string",
+ "description": "Order id, e.g. 1234567-A."
+ },
+ "order_line_id": {
+ "type": "string",
+ "description": "Order line id with the open incident, e.g. 1234567-A-1 (order_line_id in urbn_list_orders)."
+ },
+ "reason_code": {
+ "type": "string",
+ "description": "Code of an INCIDENT_CLOSE reason from urbn_list_reasons."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "order_id",
+ "order_line_id",
+ "reason_code"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/orders/{order_id}/lines/{order_line_id}/resolve_incident",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "encodePathParams": true,
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "reason_code": "$reason_code"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_accept_return",
+ "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when URBN handles returns in the seller back office and leaves the decision to the shop. Refusing needs a rejection_reason_code. This only decides the request; refunds are not made by this tool. Acts on the live marketplace: name the return, the decision and the reason and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from urbn_list_returns."
+ },
+ "accepted": {
+ "type": "boolean",
+ "description": "true accepts the return, false refuses it."
+ },
+ "rejection_reason_code": {
+ "type": "string",
+ "enum": [
+ "RETURN_REJECTION_NOT_ELIGIBLE",
+ "RETURN_REJECTION_NOT_NEEDED",
+ "RETURN_REJECTION_WINDOW_CLOSED"
+ ],
+ "description": "Required when accepted is false: not eligible, no return needed, or return window closed."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id",
+ "accepted"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/accept",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id",
+ "accepted": "$accepted",
+ "rejection_reason_code": "$rejection_reason_code"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_receive_return",
+ "description": "Confirm that the goods of an accepted return arrived at your warehouse (RT25). The return moves to RECEIVED. Acts on the live marketplace: name the return and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "return_id": {
+ "type": "string",
+ "description": "Return id from urbn_list_returns."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "return_id"
+ ]
+ },
+ "endpointMapping": {
+ "method": "PUT",
+ "path": "/returns/receive",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyMapping": {
+ "returns": [
+ {
+ "id": "$return_id"
+ }
+ ]
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": true
+ }
+ },
+ {
+ "name": "urbn_import_products",
+ "description": "Send a product file to the marketplace (P41) to create or enrich products in its catalog. file_url is the address of a CSV, XLSX or XML file in the product file format URBN asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with urbn_get_product_import. The limit is one import every 15 minutes. Changes the marketplace catalog: describe the file and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the product file (CSV, XLSX or XML)."
+ },
+ "operator_format": {
+ "type": "boolean",
+ "description": "true when the file is already in the product format URBN defines."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/products/imports",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "operator_format": "$operator_format"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false
+ }
+ },
+ {
+ "name": "urbn_import_offers",
+ "description": "Import an offer file (OF01) to create, update or delete offers in bulk. REPLACE mode deletes every offer that is not in the file, and NORMAL mode deletes the lines marked delete. file_url is the address of a CSV, XLSX or XML file in the offer file format URBN asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with urbn_get_offer_import. Installed switched off; describe the file and the mode and get a yes from the user first.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Public https URL of the offer file."
+ },
+ "import_mode": {
+ "type": "string",
+ "enum": [
+ "NORMAL",
+ "REPLACE"
+ ],
+ "description": "NORMAL creates, updates or deletes the offers in the file. REPLACE also deletes every offer missing from it.",
+ "default": "NORMAL"
+ },
+ "with_products": {
+ "type": "boolean",
+ "description": "true when the file also carries product data."
+ },
+ "shop_id": {
+ "type": "string",
+ "description": "Shop to work on, for a user who manages several shops on this marketplace: the numeric shop_id (returned by urbn_get_account, also shown in the back office). Leave it out to use URBN_SHOP_ID, or the user's default shop when that is empty."
+ }
+ },
+ "required": [
+ "file_url"
+ ]
+ },
+ "endpointMapping": {
+ "method": "POST",
+ "path": "/offers/imports",
+ "envDefaults": {
+ "shop_id": "URBN_SHOP_ID"
+ },
+ "queryParams": {
+ "shop_id": "$shop_id"
+ },
+ "bodyEncoding": "form-data",
+ "bodyMapping": {
+ "file": {
+ "__file": "$file_url"
+ },
+ "import_mode": "$import_mode",
+ "with_products": "$with_products"
+ }
+ },
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false
+ },
+ "enabled": false
+ }
+ ]
+}
diff --git a/packages/backend/src/adapters/intl/urbn.live.spec.ts b/packages/backend/src/adapters/intl/urbn.live.spec.ts
new file mode 100644
index 000000000..3e477cc58
--- /dev/null
+++ b/packages/backend/src/adapters/intl/urbn.live.spec.ts
@@ -0,0 +1,6 @@
+import * as adapter from './urbn.json';
+import { describeRetailerAdapter } from '../retailer-adapter.spec-helper';
+
+// Generated by scripts/generate-retailer-adapters.mjs from scripts/retailer-marketplaces.json: do not edit by hand.
+// Static checks always run. Live, reads only: RUN_URBN_LIVE=1 (GET /api/version needs no key; the shop reads need URBN_API_KEY).
+describeRetailerAdapter(adapter, { slug: 'urbn', hosts: ['urbanoutfitters-prod.mirakl.net'] });
diff --git a/packages/frontend/public/logos/connectors/autodoc.svg b/packages/frontend/public/logos/connectors/autodoc.svg
new file mode 100644
index 000000000..1a9acfe16
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/autodoc.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/kabum.svg b/packages/frontend/public/logos/connectors/kabum.svg
new file mode 100644
index 000000000..53100cfec
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/kabum.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/macway.svg b/packages/frontend/public/logos/connectors/macway.svg
new file mode 100644
index 000000000..21c6c2840
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/macway.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/orange-marketplace.svg b/packages/frontend/public/logos/connectors/orange-marketplace.svg
new file mode 100644
index 000000000..4a06f63e5
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/orange-marketplace.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/phone-house.svg b/packages/frontend/public/logos/connectors/phone-house.svg
new file mode 100644
index 000000000..d099eab51
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/phone-house.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/planeta-huerto.svg b/packages/frontend/public/logos/connectors/planeta-huerto.svg
new file mode 100644
index 000000000..ba099f9fd
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/planeta-huerto.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/public-gr.svg b/packages/frontend/public/logos/connectors/public-gr.svg
new file mode 100644
index 000000000..cd427cc07
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/public-gr.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/retif.svg b/packages/frontend/public/logos/connectors/retif.svg
new file mode 100644
index 000000000..7a5c97ff0
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/retif.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/saks.svg b/packages/frontend/public/logos/connectors/saks.svg
new file mode 100644
index 000000000..0ee06e733
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/saks.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/the-knot.svg b/packages/frontend/public/logos/connectors/the-knot.svg
new file mode 100644
index 000000000..7ea3c9a3a
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/the-knot.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/tiendanimal.svg b/packages/frontend/public/logos/connectors/tiendanimal.svg
new file mode 100644
index 000000000..19d12ce05
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/tiendanimal.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/urbn.svg b/packages/frontend/public/logos/connectors/urbn.svg
new file mode 100644
index 000000000..fe1ba2ab1
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/urbn.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/vertbaudet.svg b/packages/frontend/public/logos/connectors/vertbaudet.svg
new file mode 100644
index 000000000..acc0ea067
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/vertbaudet.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/yves-rocher.svg b/packages/frontend/public/logos/connectors/yves-rocher.svg
new file mode 100644
index 000000000..46b20a8ed
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/yves-rocher.svg
@@ -0,0 +1,4 @@
+
diff --git a/packages/frontend/public/logos/connectors/zooplus.svg b/packages/frontend/public/logos/connectors/zooplus.svg
new file mode 100644
index 000000000..09a101ec6
--- /dev/null
+++ b/packages/frontend/public/logos/connectors/zooplus.svg
@@ -0,0 +1,4 @@
+
diff --git a/scripts/generate-retailer-adapters.mjs b/scripts/generate-retailer-adapters.mjs
index 9b9e9720a..6d9fe0717 100644
--- a/scripts/generate-retailer-adapters.mjs
+++ b/scripts/generate-retailer-adapters.mjs
@@ -39,14 +39,14 @@ const USAGE_MARKER = '**Order workflow**';
* help and verify hints). When one of them changes in the source adapter the
* script stops, so the wording below is read again before it is regenerated.
*/
-const REVIEWED_SOURCE_SHA256 = '9e803eb5a80a369b9b065009b30944f36a9308f0126684d2e5f8d7d0b6ef1940';
+const REVIEWED_SOURCE_SHA256 = '47d31cc1ca0946463942d301c57359f49c235b819e6e6e3dcc2102894be67928';
const COUNTRY = {
AT: 'Austria', BE: 'Belgium', CA: 'Canada', CH: 'Switzerland', CZ: 'the Czech Republic', DE: 'Germany',
DK: 'Denmark', ES: 'Spain', FR: 'France', GB: 'the United Kingdom', HU: 'Hungary', IE: 'Ireland', IT: 'Italy',
HR: 'Croatia', LU: 'Luxembourg', NL: 'the Netherlands', NO: 'Norway', PL: 'Poland', PT: 'Portugal', RO: 'Romania', SI: 'Slovenia',
SE: 'Sweden', SK: 'Slovakia', US: 'the United States',
- AU: 'Australia', CL: 'Chile', FI: 'Finland', IL: 'Israel', MX: 'Mexico', PE: 'Peru',
+ AU: 'Australia', BR: 'Brazil', CL: 'Chile', FI: 'Finland', GR: 'Greece', IL: 'Israel', MX: 'Mexico', PE: 'Peru',
};
const sha256 = (text) => createHash('sha256').update(text).digest('hex');
diff --git a/scripts/retailer-marketplaces.json b/scripts/retailer-marketplaces.json
index 826d97596..6b44eb7ca 100644
--- a/scripts/retailer-marketplaces.json
+++ b/scripts/retailer-marketplaces.json
@@ -1897,6 +1897,389 @@
"https://base.com/en-IN/integrations/partstown/",
"https://www.channelengine.com/en/marketplaces/mirakl"
]
+ },
+ {
+ "slug": "phone-house",
+ "name": "Phone House Marketplace",
+ "retailer": "Phone House",
+ "region": "es",
+ "brandColor": "#26282A",
+ "monogram": "PH",
+ "hosts": [{ "value": "https://phonehousespain-prod.mirakl.net", "label": "Spain" }],
+ "countries": ["ES"],
+ "shopIdNeeded": false,
+ "access": "Phone House selects its sellers and reviews each application. Sellers ship their orders themselves; Phone House measures product quality, price, delivery speed and logistics. Products need an EAN, and complete specifications when the Phone House catalogue does not know the product yet.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [],
+ "aliases": ["The Phone House", "Phone House Spain", "Phone House España", "Phone House seller API", "Phone House vendedores", "Phone House Mirakl", "phonehouse.es marketplace"],
+ "sources": [
+ "https://github.com/djimenezp/MpOrderCollector/blob/03d07417e249e9933b8f472ee1155c1859a698b0/marketplace/mirakl_api.py",
+ "https://github.com/STANDUP-SHOW/DropShipPro/blob/8666113063688700a56b81b207846c5d794632ec/backend/src/services/mirakl.ts",
+ "https://support.sello.io/hc/en-us/articles/360018419459",
+ "https://www.mirakl.com/resources/case-study/phone-house-marketplace",
+ "https://e-tailize.com/integrations/the-phone-house/",
+ "https://www.edesk.com/appstore/phone-house-spain/"
+ ]
+ },
+ {
+ "slug": "retif",
+ "name": "RETIF Marketplace",
+ "retailer": "RETIF",
+ "region": "fr",
+ "brandColor": "#E5271D",
+ "monogram": "Re",
+ "hosts": [{ "value": "https://marketplace.retif.eu", "label": "France and the other RETIF countries" }],
+ "countries": ["FR", "BE", "DE", "ES", "IT", "LU", "NL"],
+ "countriesNote": "One seller account sells in every RETIF country. RETIF sells to businesses only.",
+ "shopIdNeeded": false,
+ "access": "RETIF accepts sellers that focus on business customers: contact RETIF to register your interest. Sellers invoice and ship directly to the customer. There is no setup or monthly fee; RETIF charges a commission per sale that depends on the product category.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://www.retif.eu/contacts/",
+ "notes": [
+ "RETIF supports colour variants only; other variant types are listed as separate products."
+ ],
+ "aliases": ["Retif", "Groupe RETIF", "RETIF seller API", "RETIF vendeur", "RETIF marketplace B2B", "RETIF Mirakl", "retif.eu marketplace", "marketplace.retif.eu"],
+ "sources": [
+ "https://crt.sh/?q=%25.retif.eu",
+ "https://support.channelengine.com/hc/en-us/articles/29281083518237-RETIF-marketplace-guide",
+ "https://help.beezup.com/en/articles/7207015-retif-product-publication",
+ "https://www.mirakl.com/fr-fr/news/retif-groupe-choisit-mirakl-ads-pour-developper-son-activite-retail-media-et-devient-le-premier-acteur-b2b-a-lancer-son-activite-retail-media/",
+ "https://github.com/STANDUP-SHOW/DropShipPro/blob/8666113063688700a56b81b207846c5d794632ec/backend/src/services/mirakl.ts"
+ ]
+ },
+ {
+ "slug": "saks",
+ "name": "Saks Marketplace",
+ "retailer": "Saks",
+ "nameInSentence": "the Saks brand-direct marketplace",
+ "region": "intl",
+ "brandColor": "#1A1A1A",
+ "monogram": "Sa",
+ "hosts": [{ "value": "https://saksus-prod.mirakl.net", "label": "United States" }],
+ "countries": ["US"],
+ "shopIdNeeded": false,
+ "access": "Saks invites the luxury brands it sells; there is no open application. Invited brands set up their shop from a personal invitation link and upload a signed Saks marketplace addendum, a W-9 or W-8, a certificate of insurance, a bank letter and a return address confirmation; Saks then approves the shop in about 7 to 14 business days.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://marketplace.saks.com",
+ "notes": [
+ "Saks gives integrating brands a separate test store first. Its API key does not work here: generate the key in the production seller back office."
+ ],
+ "aliases": ["Saks Fifth Avenue", "Saks Fifth Avenue Marketplace", "Saks Brand-Direct Marketplace", "Saks seller API", "Saks Mirakl", "saksus-prod.mirakl.net"],
+ "sources": [
+ "https://marketplace.saks.com/onboarding/4-configure-your-store",
+ "https://marketplace.saks.com/onboarding/seller-registration",
+ "https://marketplace.saks.com/onboarding/1-gather-required-documents",
+ "https://marketplace.saks.com/onboarding/2-accept-invitation",
+ "https://marketplace.saks.com/onboarding/5-store-approval",
+ "https://marketplace.saks.com/integration-process",
+ "https://base.com/en-IN/integrations/saksus/",
+ "https://e-tailize.com/integrations/selling-on-saks/",
+ "https://info.mirakl.com/nrf-2024-recording"
+ ]
+ },
+ {
+ "slug": "kabum",
+ "name": "KaBuM! Marketplace",
+ "retailer": "KaBuM!",
+ "region": "br",
+ "brandColor": "#284D8E",
+ "monogram": "Ka",
+ "hosts": [{ "value": "https://marketplace-kabum.mirakl.net", "label": "Brazil" }],
+ "countries": ["BR"],
+ "shopIdNeeded": false,
+ "access": "KaBuM! reviews each seller after a pre-registration form, usually within one business day. Sellers need a Brazilian company registration (CNPJ) active for at least three months, must issue electronic invoices (NF-e) and sell new technology or gaming products from their own stock (no dropshipping). The commission is 18 % in all departments.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://www.kabum.com.br/hotsite/marketplace",
+ "notes": [],
+ "aliases": ["KaBuM", "Kabum marketplace", "KaBuM seller API", "KaBuM vendedor", "Vender no KaBuM", "KaBuM Mirakl", "marketplace-kabum.mirakl.net"],
+ "sources": [
+ "https://www.kabum.com.br/hotsite/documentacao-hubscore/",
+ "https://apis.io/apis/kabum/kabum-marketplace-seller-integration-api/",
+ "https://github.com/api-evangelist/kabum/blob/HEAD/README.md",
+ "https://www.kabum.com.br/hotsite/marketplace",
+ "https://base.com/pt-BR/integracoes/kabum/",
+ "https://blog.bling.com.br/kabum-marketplace/"
+ ]
+ },
+ {
+ "slug": "macway",
+ "name": "MacWay Marketplace",
+ "retailer": "MacWay",
+ "region": "fr",
+ "brandColor": "#148DDF",
+ "monogram": "Mw",
+ "hosts": [{ "value": "https://marketplace.macway.com", "label": "France" }],
+ "countries": ["FR"],
+ "shopIdNeeded": false,
+ "access": "MacWay selects its sellers, based among other things on buyer ratings, refund rate and response time to customers; contact its marketplace team by e-mail (`contact.marketplace@macway.com`). The marketplace sells Apple-related high-tech products.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [],
+ "aliases": ["Macway", "MacWay seller API", "MacWay vendeur marketplace", "MacWay place de marché", "MacWay Mirakl", "marketplace.macway.com"],
+ "sources": [
+ "https://github.com/djimenezp/MpOrderCollector/blob/HEAD/marketplace/mirakl_api.py",
+ "https://help.lengow.com/hc/en-us/articles/360012231491-MacWay-Mirakl",
+ "https://help.lengow.com/hc/en-us/articles/17736327015196",
+ "https://help.beezup.com/en/articles/5685546-macway-product-publication",
+ "https://e-tailize.com/integrations/macway/",
+ "https://static.macway.com/m/pdf/criteres_mkp.pdf",
+ "https://base.com/en-IN/integrations/macway/"
+ ]
+ },
+ {
+ "slug": "autodoc",
+ "name": "AUTODOC Marketplace",
+ "retailer": "AUTODOC",
+ "region": "de",
+ "brandColor": "#F85A00",
+ "monogram": "AD",
+ "hosts": [{ "value": "https://autodocde-prod.mirakl.net", "label": "All countries" }],
+ "countries": ["FR", "DE", "AT", "BE", "IT", "LU", "NL", "PL", "PT", "ES", "GB"],
+ "countriesNote": "One shop sells to all euro countries; selling in the United Kingdom in pounds needs a separate seller account with its own API key.",
+ "shopIdNeeded": false,
+ "access": "AUTODOC selects sellers of vehicle spare parts and accessories in new condition; apply with the Join our marketplace button on its marketplace page or by e-mail (`marketplace-seller-recruitment@autodoc.eu`). Sellers must be registered in the EU with an EU warehouse and valid VAT ids (or the VAT one-stop shop). AUTODOC charges EUR 30 a month plus a commission by category.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://www.autodoc.co.uk/services/marketplace",
+ "notes": [],
+ "aliases": ["Autodoc", "AUTODOC seller API", "Autodoc Marktplatz", "Autodoc place de marché", "auto-doc.fr marketplace", "AUTODOC Mirakl", "autodocde-prod.mirakl.net"],
+ "sources": [
+ "https://github.com/invoice-collector/invoice-collector/blob/HEAD/src/collectors/sketch/mirakl_autodoc_marketplace/mirakl_autodoc_marketplace.ts",
+ "https://base.com/en-IN/integrations/autodocde/",
+ "https://support.channelengine.com/hc/en-us/articles/25623258296221-AUTODOC-marketplace-guide",
+ "https://e-tailize.com/help/marketplaces/sell-on-autodoc/",
+ "https://help.beezup.com/en/articles/10080238-autodoc-products-publication",
+ "https://docs-m2.m2epro.com/docs/how-to-integrate-autodoc-marketplace-with-m2e-mirakl-connect/",
+ "https://www.mirakl.com/news/autodoc-launches-a-curated-marketplace-in-france-with-mirakl/"
+ ]
+ },
+ {
+ "slug": "public-gr",
+ "name": "Public.gr Marketplace",
+ "retailer": "Public.gr",
+ "region": "intl",
+ "brandColor": "#F15A22",
+ "monogram": "Pu",
+ "hosts": [{ "value": "https://publicgr-prod.mirakl.net", "label": "Greece" }],
+ "countries": ["GR"],
+ "shopIdNeeded": false,
+ "access": "Public reviews each seller application; approval takes about two to three weeks. Sellers need a Greek or EU VAT number and issue their invoices through the Greek myDATA system. Product titles, descriptions and attributes must be in Greek, and sellers ship their orders themselves.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Public", "Public Greece", "Public marketplace", "Public.gr seller API", "Public.gr Mirakl", "public.gr marketplace"],
+ "sources": [
+ "https://www.zunapro.com/greece/en/marketplace/public-gr",
+ "https://e-tailize.com/integrations/selling-on-public-gr/",
+ "https://www.edesk.com/appstore/public-gr/",
+ "https://www.channelengine.com/en/marketplaces/mirakl",
+ "https://www.parapolitika.gr/oikonomia/article/311779/to-publicgr-anigi-tis-portes-tou-ston-emporiko-kosmo/"
+ ]
+ },
+ {
+ "slug": "tiendanimal",
+ "name": "Tiendanimal Marketplace",
+ "retailer": "Tiendanimal",
+ "region": "es",
+ "brandColor": "#7AB800",
+ "letterColor": "#5D4F4A",
+ "monogram": "Ti",
+ "hosts": [{ "value": "https://tiendanimal-prod.mirakl.net", "label": "Spain" }],
+ "countries": ["ES"],
+ "countriesNote": "Marketplace orders ship within Spain, without the Canary Islands, Ceuta and Melilla.",
+ "shopIdNeeded": false,
+ "access": "Tiendanimal reviews each application and signs an agreement with each seller: contact its marketplace sales team. Products must be new and carry an EAN, and prices include tax. Sellers ship with their own carrier, accept each order within five working days and take returns within 14 days.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Tiendanimal seller API", "Tiendanimal vendedores", "Tiendanimal Mirakl", "tiendanimal.es marketplace"],
+ "sources": [
+ "https://www.mirakl.com/blogs/marketplace/tiendanimal-launches-pet-lovers-paradise-1-marketplace-for-pet-supplies/",
+ "https://help.beezup.com/en/articles/5685493-tiendanimal-products-publication",
+ "https://e-tailize.com/integrations/tiendanimal/",
+ "https://www.edesk.com/appstore/tiendanimal"
+ ]
+ },
+ {
+ "slug": "yves-rocher",
+ "name": "Yves Rocher Marketplace",
+ "retailer": "Yves Rocher",
+ "region": "fr",
+ "brandColor": "#014E2E",
+ "monogram": "YR",
+ "hosts": [{ "value": "https://yvesrocherfr-prod.mirakl.net", "label": "France" }],
+ "countries": ["FR"],
+ "shopIdNeeded": false,
+ "access": "Yves Rocher selects a small number of partner brands: write to its marketplace team (`support-marketplace@yrnet.com`). Products must meet the naturalness standards of the Yves Rocher CSR charter and contain no controversial ingredients. There is no setup fee; Yves Rocher charges a monthly fee and a commission per sale. Sellers answer customer messages within 48 hours.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Yves Rocher seller API", "Yves Rocher marketplace partenaires", "Yves Rocher Mirakl", "yves-rocher.fr marketplace", "Groupe Rocher"],
+ "sources": [
+ "https://support.channelengine.com/hc/en-us/articles/35332868852253-Yves-Rocher-marketplace-guide",
+ "https://support.shoppingfeed.com/hc/en-us/articles/26158896867868-Selling-on-Yves-Rocher-Integration-Guide-and-Best-Practices",
+ "https://www.lsa-conso.fr/yves-rocher-inaugure-sa-premiere-marketplace-digitale,457716"
+ ]
+ },
+ {
+ "slug": "planeta-huerto",
+ "name": "Planeta Huerto Marketplace",
+ "retailer": "Planeta Huerto",
+ "region": "es",
+ "brandColor": "#3D9266",
+ "monogram": "PH",
+ "hosts": [{ "value": "https://planetahuerto-prod.mirakl.net", "label": "Spain and Portugal" }],
+ "countries": ["ES", "PT"],
+ "countriesNote": "Planeta Huerto sells on planetahuerto.es and planetahuerto.pt; product texts are needed in Spanish and Portuguese.",
+ "shopIdNeeded": false,
+ "access": "Planeta Huerto sells healthy and sustainable products (food, cleaning, cosmetics, supplements, baby, pets, garden and home): write to `altas@planetahuerto.es` and the team sends the registration link. Registration needs the company tax id and bank details. There is no fixed term and no minimum stock; Planeta Huerto charges a commission per sale on the final price including VAT, by category. Sellers keep their stock and ship each order themselves; every product needs an EAN.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://www.planetahuerto.es/pages/vender-en-marketplace",
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Planetahuerto", "Planeta Huerto seller API", "Planeta Huerto vendedores", "Planeta Huerto Mirakl", "planetahuerto.es marketplace"],
+ "sources": [
+ "https://www.planetahuerto.es/pages/vender-en-marketplace",
+ "https://support.channelengine.com/hc/en-us/articles/33754545395869-Planeta-Huerto-marketplace-guide",
+ "https://help.beezup.com/en/articles/8638441-planeta-huerto-products-publication",
+ "https://www.channelengine.com/en/marketplaces/mirakl"
+ ]
+ },
+ {
+ "slug": "the-knot",
+ "name": "The Knot Marketplace",
+ "retailer": "The Knot",
+ "nameInSentence": "The Knot marketplace",
+ "region": "intl",
+ "brandColor": "#1A1A1A",
+ "monogram": "TK",
+ "hosts": [{ "value": "https://knot-prod.mirakl.net", "label": "United States" }],
+ "countries": ["US"],
+ "shopIdNeeded": false,
+ "access": "The Knot chooses the brands it sells in its registry store; no public application page was found, so ask The Knot or your integrator for an introduction. Sellers ship from the United States.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["The Knot", "The Knot Registry Store", "The Knot seller API", "The Knot Worldwide marketplace", "theknot.com marketplace", "The Knot Mirakl"],
+ "sources": [
+ "https://support.channelengine.com/hc/en-us/articles/34939929176733-The-Knot-marketplace-guide",
+ "https://base.com/en-IN/integrations/knot/",
+ "https://www.edesk.com/de/appstore/the-knot",
+ "https://job-boards.greenhouse.io/theknotworldwide/jobs/4613791008"
+ ]
+ },
+ {
+ "slug": "urbn",
+ "name": "URBN Marketplace",
+ "retailer": "URBN",
+ "nameInSentence": "the URBN marketplaces (Urban Outfitters, Anthropologie and Free People)",
+ "region": "intl",
+ "brandColor": "#231F20",
+ "monogram": "UR",
+ "hosts": [{ "value": "https://urbanoutfitters-prod.mirakl.net", "label": "United States" }],
+ "countries": ["US"],
+ "shopIdNeeded": false,
+ "access": "URBN invites the brands it sells on urbanoutfitters.com (UO Marketplace), anthropologie.com (Curated by Anthropologie) and freepeople.com (FP Mart); each brand site chooses its own sellers. Sellers sign the URBN Marketplace Seller Agreement, ship every order themselves and handle their own returns.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Urban Outfitters", "Urban Outfitters Marketplace", "UO MRKT", "Anthropologie", "Curated by Anthropologie", "Free People", "FP Mart", "URBN seller API", "URBN Mirakl"],
+ "sources": [
+ "https://images.anthropologie.com/is/content/Anthropologie/URBN%20Marketplace%20Seller%20Agreement.pdf",
+ "https://base.com/en-IN/integrations/urbanoutfitters/",
+ "https://info.mirakl.com/how-urbn-is-balancing-marketplace-synergy-with-brand-identity",
+ "https://www.acenda.com/sell-on-urban-outfitters",
+ "https://e-tailize.com/integrations/selling-on-anthropologie/",
+ "https://e-tailize.com/integrations/selling-on-free-people/"
+ ]
+ },
+ {
+ "slug": "orange-marketplace",
+ "name": "Orange Marketplace",
+ "retailer": "Orange",
+ "region": "fr",
+ "brandColor": "#FF7900",
+ "monogram": "Or",
+ "hosts": [{ "value": "https://orangefr-prod.mirakl.net", "label": "France" }],
+ "countries": ["FR"],
+ "shopIdNeeded": false,
+ "access": "Orange selects its sellers after a due diligence check (finance, CSR, compliance). It asks for at least one year of marketplace sales and two closed financial years, a rating of 3.9/5 or more on other marketplaces with 100 reviews or 1,000 orders in the last 12 months, a warehouse in the EU and customer service in French within 24 business hours. The fee is a commission per order plus EUR 49.99 a month.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://boutique.orange.fr/information/marketplace/grow-your-business-on-orange-marketplace",
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Orange France marketplace", "Marketplace Orange", "Sosh marketplace", "Orange vendeur marketplace", "boutique.orange.fr marketplace", "Orange Mirakl"],
+ "sources": [
+ "https://boutique.orange.fr/information/marketplace/grow-your-business-on-orange-marketplace",
+ "https://boutique.orange.fr/information/marketplace/pourquoi-devenir-vendeur-chez-orange",
+ "https://www.mirakl.com/fr-fr/news/mirakl-supports-orange-france-in-launch-its-new-marketplace/",
+ "https://base.com/en-IN/integrations/orangefr/",
+ "https://siecledigital.fr/2026/09/23/orange-sattaque-a-amazon-et-fnac-avec-sa-propre-marketplace-high-tech/"
+ ]
+ },
+ {
+ "slug": "vertbaudet",
+ "name": "Vertbaudet Marketplace",
+ "retailer": "Vertbaudet",
+ "region": "fr",
+ "brandColor": "#B1C903",
+ "letterColor": "#1A1A1A",
+ "monogram": "Vb",
+ "hosts": [{ "value": "https://vertbaudetfr-prod.mirakl.net", "label": "France and Germany" }],
+ "countries": ["FR", "DE"],
+ "countriesNote": "Free-text product attributes for Germany must be written in German.",
+ "shopIdNeeded": false,
+ "access": "Vertbaudet selects brands and retailers with new, mid-range or higher children's and maternity products; contact it by e-mail (`business@vertbaudet.com`). The business must be registered in the EU, ship to France from the eurozone and offer French content and customer service. The fee is a 17 % commission plus EUR 49.90 a month.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": null,
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Vertbaudet seller API", "Vertbaudet vendeur marketplace", "Vertbaudet place de marché", "Vertbaudet Marktplatz", "Vertbaudet Mirakl"],
+ "sources": [
+ "https://help.lengow.com/hc/en-us/articles/18605801427996-Vertbaudet-Mirakl-Starting-with-Vertbaudet",
+ "https://support.channelengine.com/hc/en-us/articles/23962335132189-Vertbaudet-marketplace-guide",
+ "https://www.mirakl.com/fr-fr/news/vertbaudet-accelere-sa-croissance-avec-mirakl-platform-mirakl-ads-et-mirakl-payout/",
+ "https://base.com/en-IN/integrations/vertbaudetfr/"
+ ]
+ },
+ {
+ "slug": "zooplus",
+ "name": "zooplus Marketplace",
+ "retailer": "zooplus",
+ "region": "de",
+ "brandColor": "#237803",
+ "monogram": "Zo",
+ "hosts": [{ "value": "https://zooplus-prod.mirakl.net", "label": "Germany, France and Spain" }],
+ "countries": ["DE", "FR", "ES"],
+ "shopIdNeeded": false,
+ "access": "zooplus reviews each application (apply now form on its marketplace page, questions to `info-marketplace@zooplus.com`), followed by an identity and company check. Sellers need an EU-registered business with an EU VAT number and stock in the EU, and must give customers a free return label. There is no subscription fee for the first three months.",
+ "keyPath": "your user name (top right) > My user settings > API key",
+ "sellerHelpUrl": "https://www.zooplus.com/info/about/marketplace",
+ "notes": [
+ "The seller address of this connector is the one the platform assigns to this retailer; no seller guide names it yet. If your seller back office opens at a different address, tell us in the chat so we can correct it."
+ ],
+ "aliases": ["Zooplus", "zooplus seller API", "zooplus Marktplatz", "zooplus place de marché", "zooplus marketplace partner", "zooplus Mirakl"],
+ "sources": [
+ "https://www.zooplus.com/info/about/marketplace",
+ "https://support.channelengine.com/hc/en-us/articles/22945285011357-Zooplus-marketplace-guide",
+ "https://globalpetindustry.com/news/zooplus-expands-marketplace-offer-in-spain-with-more-markets-planned-for-2027/",
+ "https://corporate.zooplus.com/wp-content/uploads/2026/08/PR_zooplus_Marketplace_EN_final-2.pdf",
+ "https://base.com/en-IN/integrations/zooplusde/",
+ "https://e-tailize.com/integrations/selling-on-zooplus/"
+ ]
}
]
}
diff --git a/server.json b/server.json
index b79b97cc8..47eb5a773 100644
--- a/server.json
+++ b/server.json
@@ -2,7 +2,7 @@
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.HelpCode-ai/anythingmcp",
"title": "AnythingMCP",
- "description": "MCP gateway and company brain: 886 connectors (SAP, ERP, SQL), file search, memory and skills.",
+ "description": "MCP gateway and company brain: 901 connectors (SAP, ERP, SQL), file search, memory and skills.",
"repository": {
"url": "https://github.com/HelpCode-ai/anythingmcp",
"source": "github"